class NRSER::Sys::Env::Path
@todo document NRSER::Env::Path class.
Constants
- SEPARATOR
Character used to separate path entries in string format.
@return [String]
Attributes
Key for the value in `ENV` that the object represents. This is set when loading from `ENV` and used to know where to write when saving back to it.
@return [nil | String]
The object that was originally provided at construction.
@return [nil | String
| each_index]
The actual internal list of paths.
@return [Hamster::Vector<String>]
Public Class Methods
# File lib/nrser/sys/env/path.rb, line 129 def self.from_ENV env_key new ENV[env_key.to_s], env_key: env_key end
See if a `path` matches any of `patterns`.
Short-circuits as soon as a match is found (so patterns may not all be tested).
@param [String] path
Path to test against.
@param [Array<String | Proc<String=>Boolean> | Regexp>] patterns
Patterns to test: - `String` - test if it and `path` are equal (`==`) - `Proc<String=>Boolean>` - call with `path` and evaluate result as Boolean. - `Regexp` - test if it matches `path` (`=~`)
@return [Boolean]
`true` if *any* of `patterns` match `path`.
# File lib/nrser/sys/env/path.rb, line 108 def self.matches_pattern? path, *patterns patterns.any? do |pattern| case pattern when String path == pattern when Proc pattern.call path when Regexp path =~ pattern else raise TypeError.new binding.erb <<-END Each `*patterns` arg should be String, Proc or Regexp, found: <%= pattern.pretty_inspect %> END end end end
Instantiate a new `NRSER::Env::Path`.
# File lib/nrser/sys/env/path.rb, line 163 def initialize source, env_key: nil @env_key = env_key.to_s.freeze @source = source.dup.freeze @value = self.class.normalize source end
@todo Document normalize method.
@param [nil | String
| each_index] source
Path source.
@return [return_type]
@todo Document return value.
# File lib/nrser/sys/env/path.rb, line 54 def self.normalize source paths = if source.nil? [] elsif source.is_a?( String ) source.to_s.split SEPARATOR elsif NRSER.array_like?( source ) # Flatten it if supported source = source.flatten if source.respond_to?( :flatten ) # Stringify each segment, split them and concat results source.flat_map { |entry| entry.to_s.split SEPARATOR } else raise ArgumentError.new binding.erb <<-END Expected a string or an "array-like" source, found: <%= source.pretty_inspect %> END end Hamster::Vector.new paths. # Get rid of empty paths reject( &:empty? ). # Get rid of duplicates uniq. # Freeze all the strings map( &:freeze ) end
Public Instance Methods
@param source (see .normalize) @return [self]
# File lib/nrser/sys/env/path.rb, line 197 def append source # Normalize the new source to a flat array of strings paths = self.class.normalize source # The new value is the current paths with the new paths appended, with # any paths in the current path removed from the new ones (de-duplication) @value = (@value + paths).uniq # Return self for chain-ability self end
Support for {Enumerable} mixin. Yields each path in order.
Specifically, proxies to {Hamster::Vector#each}
@see www.rubydoc.info/gems/hamster/Hamster/Vector#each-instance_method
@param [nil | Proc<(String
)=>*>] block
When present, block will be called once for each string path in this object. First path is most prominent, down to least last.
@return [self]
When `&block` is provided.
@return [Enumerator]
When `&block` is omitted.
# File lib/nrser/sys/env/path.rb, line 265 def each &block if block # Proxy for yielding @value.each &block # Return self for chain-ability self else # Return the {Enumerator} from the vector @value.each end end
# File lib/nrser/sys/env/path.rb, line 213 def insert source, before: nil, after: nil paths = self.class.normalize source before_index = if before @value.find_index do |path| self.class.matches_pattern? path, *before end end after_index = if after index = @value.rindex { |path| self.class.matches_pattern? path, *after } index += 1 if index end insert_index = if after_index && before_index # Make sure the conditions don't conflict with each other if after_index > before_index raise "Conflicting bounds!" end # Insert as far "down" the path as allowed [before_index, after_index].max else # Use the one that is not `nil`, or insert at the end if they both are before_index || after_index || @value.length end @value = @value.insert( insert_index, *paths ).uniq self end
@param source (see .normalize) @return [self]
# File lib/nrser/sys/env/path.rb, line 177 def prepend source # Normalize the new source to a flat array of strings paths = self.class.normalize source # The new value is the normalized paths followed by the current paths # with the new ones removed (de-duplication) @value = (paths + @value).uniq # Return self for chain-ability self end
The string paths in a new stdlib `Array`. Mutating this array will have no effect on the {NRSER::Env::Path} data.
@return [Array<String>]
# File lib/nrser/sys/env/path.rb, line 293 def to_a @value.to_a end
The paths joined with ':'.
@return [String]
# File lib/nrser/sys/env/path.rb, line 283 def to_s @value.join SEPARATOR end