nrser 0.0.30 → 0.1.0

data/lib/nrser/{object → functions/object}/truthy.rb

@@ -1,7 +1,19 @@
-require 'set'
+# frozen_string_literal: true
 
-module NRSER 
-  # Down-cased versions of strings that are considered to communicate truth.
+# Definitions
+# =======================================================================
+
+module NRSER
+  # @!group Object Functions
+  
+  # Constants
+  # ============================================================================
+  
+  # Down-cased versions of strings that are considered to communicate true
+  # in things like ENV vars, CLI options, etc.
+  # 
+  # @return [Set<String>]
+  # 
   TRUTHY_STRINGS = Set.new [
     'true',
     't',
@@ -9,9 +21,14 @@ module NRSER
     'y',
     'on',
     '1',
-  ]
+  ].freeze
+  
   
-  # Down-cased versions of strings that are considered to communicate false.
+  # Down-cased versions of strings that are considered to communicate false
+  # in things like ENV vars, CLI options, etc.
+  # 
+  # @return [Set<String>]
+  # 
   FALSY_STRINGS = Set.new [
     'false',
     'f',
@@ -20,17 +37,30 @@ module NRSER
     'off',
     '0',
     '',
-  ]
+  ].freeze
+  
+  
+  # Functions
+  # ============================================================================
   
   # Evaluate an object (that probably came from outside Ruby, like an
   # environment variable) to see if it's meant to represent true or false.
   # 
-  # @param [Nil, String] object
+  # @pure Return value depends only on parameters.
+  # 
+  # @param [nil | String | Boolean] object
   #   Value to test.
   # 
   # @return [Boolean]
   #   `true` if the object is "truthy".
   # 
+  # @raise [ArgumentError]
+  #   When a string is received that is not in {NRSER::TRUTHY_STRINGS} or
+  #   {NRSER::FALSY_STRINGS} (case insensitive).
+  # 
+  # @raise [TypeError]
+  #   When `object` is not the right type.
+  # 
   def self.truthy? object
     case object
     when nil
@@ -60,11 +90,20 @@ module NRSER
   
   # Opposite of {NRSER.truthy?}.
   # 
+  # @pure Return value depends only on parameters.
+  # 
   # @param object (see .truthy?)
   # 
   # @return [Boolean]
   #   The negation of {NRSER.truthy?}.
   # 
+  # @raise [ArgumentError]
+  #   When a string is received that is not in {NRSER::TRUTHY_STRINGS} or
+  #   {NRSER::FALSY_STRINGS} (case insensitive).
+  # 
+  # @raise [TypeError]
+  #   When `object` is not the right type.
+  # 
   def self.falsy? object
     ! truthy?(object)
   end # .falsy?

data/lib/nrser/functions/path.rb

@@ -0,0 +1,150 @@
+module NRSER
+  # @!group Path Functions
+  
+  # @return [Pathname]
+  # 
+  def self.pn_from path
+    if path.is_a? Pathname
+      path
+    else
+      Pathname.new path
+    end
+  end
+  
+  
+  # @todo Document glob? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.looks_globish? path
+    %w|* ? [ {|.any? &path.to_s.method( :include? )
+  end # .glob?
+  
+  
+  # Ascend the directory tree starting at `from` (defaults to working
+  # directory) looking for a relative path.
+  # 
+  # How it works and what it returns is dependent on the sent options.
+  # 
+  # In the simplest / default case:
+  # 
+  # 1.
+  # 
+  # @param [String | Pathname] rel_path
+  #   Relative path to search for. Can contains glob patterns; see the `glob`
+  #   keyword.
+  # 
+  # @param [String | Pathname] from:
+  #   Where to start the search. This is the first directory checked.
+  # 
+  # @param [Boolean | :guess] glob:
+  #   Controls file-glob behavior with respect to `rel_path`:
+  #   
+  #   -   `:guess` (default) - boolean value is computed by passing `rel_path`
+  #       to {.looks_globish?}.
+  #       
+  #   -   `true` - {Pathname.glob} is used to search for `rel_path` in each
+  #       directory, and the first glob result that passes the test is
+  #       considered the match.
+  #       
+  #   -   `false` - `rel_path` is used as a literal file path (if it has a `*`
+  #       character it will only match paths with a literal `*` character,
+  #       etc.)
+  #   
+  #   **Be mindful that glob searches can easily consume significant resources
+  #   when using broad patterns and/or large file trees.**
+  #   
+  #   Basically, you probably don't *ever* want to use `**` - we walk all the
+  #   way up to the file system root, so it would be equivalent to searching
+  #   *the entire filesystem*.
+  # 
+  # @todo
+  #   There should be a way to cut the search off early or detect `**` in
+  #   the `rel_path` and error out or something to prevent full FS search.
+  # 
+  # @param [Symbol] test:
+  #   The test to perform on pathnames to see if they match. Defaults to
+  #   `:exist?` - which calls {Pathname#exist?} - but could be `:directory?`
+  #   or anything else that makes sense.
+  # 
+  # @param [Symbol] result:
+  #   What information to return:
+  #   
+  #   -   `:common_root` (default) - return the directory that the match was
+  #       relative to, so the return value is `from` or a ancestor of it.
+  #       
+  #   -   `:path` - return the full path that was matched.
+  #   
+  #   -   `:pair` - return the `:common_root` value followed by the `:path`
+  #       value in a two-element {Array}.
+  # 
+  # @return [nil]
+  #   When no match is found.
+  # 
+  # @return [Pathname]
+  #   When a match is found and `result` keyword is
+  #   
+  #   -   `:common_root` - the directory in `from.ascend` the match was made
+  #       from.
+  #       
+  #   -   `:path` - the path to the matched file.
+  # 
+  # @return [Array<(Pathname, Pathname)>]
+  #   When a match is found and `result` keyword is `:pair`, the directory
+  #   the match was relative to followed by the matched path.
+  # 
+  def self.find_up(
+    rel_path,
+    from: Pathname.pwd,
+    glob: :guess,
+    test: :exist?,
+    result: :common_root
+  )
+    # If `glob` is `:guess`, override `glob` with the result of
+    # {.looks_globish?}
+    # 
+    glob = looks_globish?( rel_path ) if glob == :guess
+    
+    found = find_map( pn_from( from ).ascend ) { |dir|
+      path = dir / rel_path
+      
+      found_path = if glob
+        Pathname.glob( path ).find { |match_path|
+          match_path.public_send test
+        }
+      else
+        path.public_send test
+      end
+      
+      unless found_path.nil?
+        [dir, found_path]
+      end
+    }
+    
+    return nil if found.nil?
+    
+    dir, path = found
+    
+    Types.match result,
+      :common_root, dir,
+      :pair, found,
+      :path, path
+  end
+  
+  
+  # Exactly like {NRSER.find_up} but raises if nothing is found.
+  # 
+  def self.find_up! *args
+    find_up( *args ).tap { |result|
+      if result.nil?
+        raise "HERE! #{ args.inspect }"
+      end
+    }
+  end
+  
+  
+end # module NRSER

data/lib/nrser/{proc.rb → functions/proc.rb}

@@ -1,24 +1,3 @@
-##
-# Methods that make useful {Proc} instances.
-## 
-
-# Requirements
-# =======================================================================
-
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
-# Project / Package
-# -----------------------------------------------------------------------
-require_relative './message'
-
-
-# Definitions
-# =======================================================================
-
 module NRSER
   
   # Creates a new {NRSER::Message} from the array.
@@ -95,7 +74,7 @@ module NRSER
   # 
   # @note
   #   `mappable`` entries are mapped into messages when {#to_chain} is called,
-  #   meaning subsequent changes to `mappable` **will not** affect the 
+  #   meaning subsequent changes to `mappable` **will not** affect the
   #   returned proc.
   # 
   # @example Equivalent of `Time.now.to_i`

data/lib/nrser/functions/string.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require_relative './string/looks_like'
+
+module NRSER
+  
+  # @!group String Functions
+  
+  WHITESPACE_RE = /\A[[:space:]]*\z/
+  
+  UNICODE_ELLIPSIS = '…'
+  
+  
+  def self.whitespace? string
+    string =~ WHITESPACE_RE
+  end
+  
+  
+  # turn a multi-line string into a single line, collapsing whitespace
+  # to a single space.
+  # 
+  # same as ActiveSupport's String.squish, adapted from there.
+  def self.squish str
+    str.gsub(/[[:space:]]+/, ' ').strip
+  end # squish
+  
+  singleton_class.send :alias_method, :unblock, :squish
+  
+  
+  def self.common_prefix strings
+    raise ArgumentError.new("argument can't be empty") if strings.empty?
+    
+    sorted = strings.sort
+    
+    i = 0
+    
+    while sorted.first[i] == sorted.last[i] &&
+          i < [sorted.first.length, sorted.last.length].min
+      i = i + 1
+    end
+    
+    sorted.first[0...i]
+  end # .common_prefix
+  
+  
+  def self.filter_repeated_blank_lines str, remove_leading: false
+    out = []
+    lines = str.lines
+    skipping = remove_leading
+    str.lines.each do |line|
+      if line =~ /^\s*$/
+        unless skipping
+          out << line
+        end
+        skipping = true
+      else
+        skipping = false
+        out << line
+      end
+    end
+    out.join
+  end # .filter_repeated_blank_lines
+  
+  
+  def self.lazy_filter_repeated_blank_lines source, remove_leading: false
+    skipping = remove_leading
+    
+    source = source.each_line if source.is_a? String
+    
+    Enumerator::Lazy.new source do |yielder, line|
+      if line =~ /^\s*$/
+        unless skipping
+          yielder << line
+        end
+        skipping = true
+      else
+        skipping = false
+        yielder << line
+      end
+    end
+    
+  end # .lazy_filter_repeated_blank_lines
+  
+
+  # Truncates a given +text+ after a given <tt>length</tt> if +text+ is longer than <tt>length</tt>:
+  #
+  #   'Once upon a time in a world far far away'.truncate(27)
+  #   # => "Once upon a time in a wo..."
+  #
+  # Pass a string or regexp <tt>:separator</tt> to truncate +text+ at a natural break:
+  #
+  #   'Once upon a time in a world far far away'.truncate(27, separator: ' ')
+  #   # => "Once upon a time in a..."
+  #
+  #   'Once upon a time in a world far far away'.truncate(27, separator: /\s/)
+  #   # => "Once upon a time in a..."
+  #
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
+  # for a total length not exceeding <tt>length</tt>:
+  #
+  #   'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')
+  #   # => "And they f... (continued)"
+  # 
+  # adapted from
+  # 
+  # <https://github.com/rails/rails/blob/7847a19f476fb9bee287681586d872ea43785e53/activesupport/lib/active_support/core_ext/string/filters.rb#L46>
+  # 
+  def self.truncate(str, truncate_at, options = {})
+    return str.dup unless str.length > truncate_at
+
+    omission = options[:omission] || '...'
+    length_with_room_for_omission = truncate_at - omission.length
+    stop = \
+      if options[:separator]
+        str.rindex(options[:separator], length_with_room_for_omission) || length_with_room_for_omission
+      else
+        length_with_room_for_omission
+      end
+
+    "#{str[0, stop]}#{omission}"
+  end # .truncate
+  
+  
+  # Cut the middle out of a string and stick an ellipsis in there instead.
+  # 
+  # @param [String] string
+  #   Source string.
+  # 
+  # @param [Fixnum] max
+  #   Max length to allow for the output string.
+  # 
+  # @param [String] omission:
+  #   The string to stick in the middle where original contents were
+  #   removed. Defaults to the unicode ellipsis since I'm targeting the CLI
+  #   at the moment and it saves precious characters.
+  # 
+  # @return [String]
+  #   String of at most `max` length with the middle chopped out if needed
+  #   to do so.
+  def self.ellipsis string, max, omission: UNICODE_ELLIPSIS
+    return string unless string.length > max
+    
+    trim_to = max - omission.length
+    
+    start = string[0, (trim_to / 2) + (trim_to % 2)]
+    finish = string[-( (trim_to / 2) - (trim_to % 2) )..-1]
+    
+    start + omission + finish
+  end # .ellipsis
+  
+  
+  # Try to do "smart" job adding ellipsis to the middle of strings by
+  # splitting them by a separator `split` - that defaults to `, ` - then
+  # building the result up by bouncing back and forth between tokens at the
+  # beginning and end of the string until we reach the `max` length limit.
+  # 
+  # Intended to be used with possibly long single-line strings like
+  # `#inspect` returns for complex objects, where tokens are commonly
+  # separated by `, `, and producing a reasonably nice result that will fit
+  # in a reasonable amount of space, like `rspec` output (which was the
+  # motivation).
+  # 
+  # If `string` is already less than `max` then it is just returned.
+  # 
+  # If `string` doesn't contain `split` or just the first and last tokens
+  # alone would push the result over `max` then falls back to
+  # {NRSER.ellipsis}.
+  # 
+  # If `max` is too small it's going to fall back nearly always... around
+  # `64` has seemed like a decent place to start from screwing around on
+  # the REPL a bit.
+  # 
+  # @pure
+  #   Return value depends only on parameters.
+  # 
+  # @status
+  #   Experimental
+  # 
+  # @param [String] string
+  #   Source string.
+  # 
+  # @param [Fixnum] max
+  #   Max length to allow for the output string. Result will usually be
+  #   *less* than this unless the fallback to {NRSER.ellipsis} kicks in.
+  # 
+  # @param [String] omission:
+  #   The string to stick in the middle where original contents were
+  #   removed. Defaults to the unicode ellipsis since I'm targeting the CLI
+  #   at the moment and it saves precious characters.
+  # 
+  # @param [String] split:
+  #   The string to tokenize the `string` parameter by. If you pass a
+  #   {Regexp} here it might work, it might loop out, maybe.
+  # 
+  # @return [String]
+  #   String of at most `max` length with the middle chopped out if needed
+  #   to do so.
+  # 
+  def self.smart_ellipsis string, max, omission: UNICODE_ELLIPSIS, split: ', '
+    return string unless string.length > max
+    
+    unless string.include? split
+      return ellipsis string, max, omission: omission
+    end
+    
+    tokens = string.split split
+    
+    char_budget = max - omission.length
+    start = tokens[0] + split
+    finish = tokens[tokens.length - 1]
+    
+    if start.length + finish.length > char_budget
+      return ellipsis string, max, omission: omission
+    end
+    
+    next_start_index = 1
+    next_finish_index = tokens.length - 2
+    next_index_is = :start
+    next_index = next_start_index
+    
+    while (
+      start.length +
+      finish.length +
+      tokens[next_index].length +
+      split.length
+    ) <= char_budget do
+      if next_index_is == :start
+        start += tokens[next_index] + split
+        next_start_index += 1
+        next_index = next_finish_index
+        next_index_is = :finish
+      else # == :finish
+        finish = tokens[next_index] + split + finish
+        next_finish_index -= 1
+        next_index = next_start_index
+        next_index_is = :start
+      end
+    end
+    
+    start + omission + finish
+    
+  end # .smart_ellipsis
+  
+  
+  # Get the constant identified by a string.
+  # 
+  # @pure Return value depends only on parameters.
+  # 
+  # @example
+  #   
+  #   SomeClass == NRSER.constantize(SomeClass.name)
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @param [String] camel_cased_word
+  #   The constant's camel-cased, double-colon-separated "name",
+  #   like "NRSER::Types::Array".
+  # 
+  # @return [Object]
+  # 
+  # @raise [NameError]
+  #   When the name is not in CamelCase or is not initialized.
+  # 
+  def self.constantize(camel_cased_word)
+    names = camel_cased_word.split('::')
+
+    # Trigger a built-in NameError exception including the ill-formed constant in the message.
+    Object.const_get(camel_cased_word) if names.empty?
+
+    # Remove the first blank element in case of '::ClassName' notation.
+    names.shift if names.size > 1 && names.first.empty?
+
+    names.inject(Object) do |constant, name|
+      if constant == Object
+        constant.const_get(name)
+      else
+        candidate = constant.const_get(name)
+        next candidate if constant.const_defined?(name, false)
+        next candidate unless Object.const_defined?(name)
+
+        # Go down the ancestors to check if it is owned directly. The check
+        # stops when we reach Object or the end of ancestors tree.
+        constant = constant.ancestors.inject do |const, ancestor|
+          break const    if ancestor == Object
+          break ancestor if ancestor.const_defined?(name, false)
+          const
+        end
+
+        # owner is in Object, so raise
+        constant.const_get(name, false)
+      end
+    end
+  end # .constantize
+  
+  singleton_class.send :alias_method, :to_const, :constantize
+  
+end # module NRSER