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

env_key[R]

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]

source[R]

The object that was originally provided at construction.

@return [nil | String | each_index]

value[R]

The actual internal list of paths.

@return [Hamster::Vector<String>]

Public Class Methods

from_ENV(env_key) click to toggle source
# 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
matches_pattern?(path, *patterns) click to toggle source

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
new(source, env_key: nil) click to toggle source

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
normalize(source) click to toggle source

@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

<<(source)
Alias for: prepend
>>(source)
Alias for: prepend
append(source) click to toggle source

@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
each(&block) click to toggle source

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
insert(source, before: nil, after: nil) click to toggle source
# 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
prepend(source) click to toggle source

@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
Also aliased as: unshift, >>, push, <<
push(source)
Alias for: prepend
to_a() click to toggle source

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
to_s() click to toggle source

The paths joined with ':'.

@return [String]

# File lib/nrser/sys/env/path.rb, line 283
def to_s
  @value.join SEPARATOR
end
unshift(source)
Alias for: prepend