nrser 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 736ee433c6078e250b89ebbc65455ff157888b6e
-  data.tar.gz: a99e836e91a873ea4b06767376a6c38e30c2fe5a
+  metadata.gz: 1518d7452a93418bee72c151693e9f6499a41d6a
+  data.tar.gz: 5139a61976788fb0bb8c397a40eec24d20c695d7
 SHA512:
-  metadata.gz: ffed557cf2652d5d9b9af71c4eb65cda37a0a165cacb7f419d9e6717cbb810ab224e3a6710e6e762c72948707e7424180faafd6acd2ab3a310aa2a326422d794
-  data.tar.gz: 3b5307fc1dca415cb54a56ed32799b472c625c8a8d33d2dcef98e74e6ae85e21916cf2df5a211de3c4251c5e5828e5cb842942cf490cd10da8c5ad535ad8693b
+  metadata.gz: eb32f1311827dc0190db71434a798953282e3d258b3059aea03b86f6e56b57f871b7c5e8dcfe4b99844db1ec65b8782bf0c7ef3a099f1423ceeddcdf8b5ea16b
+  data.tar.gz: 67aad6c06d72fb6123dc74294e113bd9f2862a9eca317e64277aae9fb68169e9c48dc5e9248788ca475e1d30f2314b7cdd6958ee12792880be4ccc859c5fa6b8

data/lib/nrser.rb

@@ -56,15 +56,26 @@ module NRSER
   
 end
 
+# 1.  Load up extension mixins first - they don't invoke anything, just define
+#     methods
 require_relative './nrser/ext'
-require_relative './nrser/errors'
+
+# 2.  Then load up the refinements, which either include the extension mixins
+#     or directly define proxies and methods (but don't execute them).
+#     
+#     This way everything else should be able to use them.
+#     
+require_relative './nrser/refinements'
+
+# 3.  Then everything else...
 require_relative './nrser/version'
+require_relative './nrser/char'
+require_relative './nrser/errors'
 require_relative './nrser/no_arg'
 require_relative './nrser/message'
 require_relative './nrser/env'
 require_relative './nrser/collection'
 require_relative './nrser/functions'
 require_relative './nrser/types'
-require_relative './nrser/refinements'
 require_relative './nrser/meta'
 require_relative './nrser/mean_streak'

data/lib/nrser/char.rb

@@ -0,0 +1,155 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+
+
+# Declarations
+# ============================================================================
+
+module NRSER::Char; end
+
+
+# Namespace Requires
+# ============================================================================
+
+require_relative './char/special'
+
+
+# Definitions
+# =======================================================================
+
+# A place to put things that work with characters.
+# 
+# **_This is ALL based around UTF-8 by default_**
+# 
+module NRSER::Char
+  
+  # Constants
+  # ============================================================================
+  
+  # {Regexp} that matches a control character.
+  # 
+  # @return [Regexp]
+  # 
+  CONTROL_RE = /[[:cntrl:]]/
+  
+  
+  # {Regexp} that matches when *all* characters are control characters.
+  # 
+  # NOTE This will match the empty string.
+  # 
+  # @return [Regexp]
+  # 
+  ALL_CONTROL_RE = /\A[[:cntrl:]]*\z/
+  
+  
+  HEX_RE = /\A[0-9a-f]+\z/i
+  
+  
+  # Special Characters
+  # ----------------------------------------------------------------------------
+  
+  # Special character info for the NULL character (zero byte in string).
+  # 
+  # @return [NRSER::Char::Special]
+  # 
+  NULL = Special.new \
+    char:         "\u0000",
+    names:         ['NULL', 'NUL', '<control-0000>'],
+    caret:        '^@',
+    symbol:       '␀'
+  
+  
+  # Module Methods
+  # ============================================================================
+  
+  # Tests
+  # ----------------------------------------------------------------------------
+  
+  # Test if string is a control character (returns `false` if length > 1).
+  # 
+  # @param [String] char
+  #   String to test.
+  # 
+  # @return [Boolean]
+  #   `true` if `char` is a control character.
+  # 
+  def self.control? char
+    char.length == 1 && CONTROL_RE.match( char )
+  end # .control?
+  
+  
+  # Conversions
+  # ----------------------------------------------------------------------------
+  
+  # Convert integer to UTF-8 character (length 1 string).
+  # 
+  # @param [Integer] int
+  #   Integer (decimal/base-10) representation of the character.
+  # 
+  # @return [String]
+  #   UTF-8 character.
+  # 
+  # @raise
+  #   When conversion can't be performed.
+  # 
+  def self.from_i int
+    int.chr Encoding::UTF_8
+  end # .from_i
+  
+  singleton_class.send :alias_method, :from_ord, :from_i
+  singleton_class.send :alias_method, :from_dec, :from_i
+  
+  
+  # Convert hex string to UTF-8 character (length 1 string).
+  # 
+  # @param [String] hex
+  #   Hexadecimal (base-16) number represented as a string.
+  # 
+  # @return [String]
+  #   UTF-8 character.
+  # 
+  # @raise
+  #   When conversion can't be performed.
+  # 
+  def self.from_hex hex
+    from_i hex.to_i( 16 )
+  end # .from_hex
+  
+  
+  # Convert hex string to UTF-8 character (length 1 string).
+  # 
+  # @param [String | Integer] source
+  #   Hexadecimal (base-16) number represented as a string or a non-negative
+  #   integer.
+  # 
+  # @return [String]
+  #   UTF-8 character.
+  # 
+  # @raise (see .from_hex)
+  # 
+  def self.from source
+    case source
+    when HEX_RE
+      from_hex source
+    when Integer
+      from_i source
+    else
+      raise ArgumentError.new binding.erb <<-END
+        Expected hex String like '12AB' or Integer, got <%= source.class %>
+        
+        Found:
+        
+            <%= source.pretty_inspect %>
+        
+      END
+    end
+  end # .from_hex
+  
+  
+end # module NRSER::Char

data/lib/nrser/char/special.rb

@@ -0,0 +1,196 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Definitions
+# =======================================================================
+
+# Lil' structure with useful info and methods for special characters.
+# 
+class NRSER::Char::Special
+
+  # Attributes
+  # ======================================================================
+  
+  # The character as a length-one string (UTF-8 encoding).
+  # 
+  # @return [String]
+  #     
+  attr_reader :char
+  
+  
+  # Zero or more strings names for the character.
+  # 
+  # @return [Array<String>]
+  #     
+  attr_reader :names
+  
+  
+  # If the character is a control character, the "caret" (`^X`) style
+  # replacement for it.
+  # 
+  # @example
+  #   NRSER::Char::NULL.caret
+  #   # => '^@'
+  # 
+  # @return [nil]
+  #   If we don't have a caret replacement for it.
+  # 
+  # @return [String]
+  #   If we have a caret replacement for it.
+  #     
+  attr_reader :caret
+  
+  
+  # A printable Unicode "control picture" character that can be used as a
+  # replacement character for control characters.
+  # 
+  # @see http://www.unicode.org/charts/PDF/U2400.pdf
+  # 
+  # The nice things about these is they:
+  # 
+  # 1.  *Should* allow for replacement without changing the Ruby string
+  #     length\*.
+  #     
+  #     > \* I say *should* because lengths of unicode strings can get funky
+  #     > across different platforms due to bytes and code points and glyphs
+  #     > and a bunch of other stuff it seems like only about three people
+  #     > fully understand.. it often *will* change the *byte length*, and
+  #     > who knows how that will go if you start handing it back and forth
+  #     > to C or something else.
+  #     
+  # 2.  Visually represent the replaced character. You know what it was
+  #     without having to remember caret or hex representations.
+  # 
+  # 3.  Have a far lower chance of ambiguity versus {#carat}, {#esc_seq}, etc.
+  #     (is a control character or did the string really have a `^X` in it?).
+  # 
+  # Drawbacks:
+  # 
+  # 1.  They're all gonna be outside the ASCII range, so if you are for some
+  #     reason stuck with something that can't Unicode you're gonna get some
+  #     gibberish at best, if not outright breakage.
+  # 
+  # 2.  They require font support, or you're going to probably get one of those
+  #     little box things that we used to see all over the web before browsers
+  #     and operating systems managed to get their shit together.
+  # 
+  # @return [nil]
+  #   If we don't have an printable symbol for this character.
+  # 
+  # @return [String]
+  #   Length 1 printable unicode string.
+  #     
+  attr_reader   :symbol
+  alias_method  :picture, :symbol
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `Special`.
+  # 
+  # @param [String] char:
+  #   The actual character as a length 1 UTF-8 string.
+  # 
+  # @param [nil | String] caret:
+  #   Optional `^X` replacement for control characters, see {#caret} for
+  #   details.
+  # 
+  # @param [Array<#to_s>] names:
+  #   Optional names this character goes by.
+  # 
+  # @param [nil | String] symbol:
+  #   Optional printable unicode character replacement, see {#symbol} for
+  #   details.
+  # 
+  def initialize char:, names: [], caret: nil, symbol: nil
+    unless char.is_a?( String ) && char.length == 1
+      raise ArgumentError,
+        "char must be string of length 1"
+    end
+    
+    @char = char.freeze
+    @names = names.map { |n| n.to_s.freeze }.freeze
+    @caret = caret.freeze
+    @symbol = symbol.freeze
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # The first of {#names} (if any).
+  # 
+  # @return [nil]
+  #   When {#names} is empty.
+  # 
+  # @return [String]
+  #   When {#names} is not empty.
+  # 
+  def name
+    names[0]
+  end
+  
+  
+  # Decimal encoding of the character (with respect to UTF-8).
+  # 
+  # Equivalent to `.char.ord`.
+  # 
+  # @return [Fixnum]
+  # 
+  def dec
+    char.ord
+  end
+  
+  alias_method :ord, :dec
+  
+  
+  # @return [String]
+  #   Hex string as it would appear in `\uXXXX`.
+  def hex
+    @hex ||= ("%04X" % char.ord).freeze
+  end
+  
+  
+  # @return [Boolean]
+  #   `true` if the character is a control character.
+  def control?
+    @control ||= NRSER::Char.control?( char )
+  end
+  
+  
+  def esc_seq
+    @esc_seq ||= char.inspect[1..-2].freeze
+  end
+  
+  
+  # @return [Boolean]
+  #   `true` if the character code-point is in the ASCII range.
+  def ascii?
+    char.ascii_only?
+  end
+  
+  
+  # Replace all occurrences of {#char} in the string.
+  # 
+  # @param [String] string
+  #   String to replace this character in.
+  # 
+  # @param [Symbol | #to_s] with:
+  #   What to replace the character with:
+  #   
+  #   1.  {Symbol} - this method will be called on the instance and the
+  #       `#to_s` of the response will be used.
+  #       
+  #   2.  `#to_s` - string value will be used.
+  # 
+  # @return [String]
+  #   String with {#char} replaced.
+  # 
+  def replace string, with: :symbol
+    with = public_send( with ) if with.is_a?( Symbol )
+    string.gsub char, with.to_s
+  end
+  
+end # class NRSER::Char::Special

data/lib/nrser/functions.rb

@@ -16,3 +16,4 @@ require_relative './functions/open_struct'
 require_relative './functions/merge_by'
 require_relative './functions/tree'
 require_relative './functions/path'
+require_relative './functions/git'

data/lib/nrser/functions/git.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+require 'pathname'
+require 'open3'
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  def self.git_root from
+    path = Pathname.new( from ).expand_path
+    path = path.dirname unless path.directory?
+    
+    out, err, status = Open3.capture3 \
+      'git rev-parse --show-toplevel',
+      chdir: path.to_s
+    
+    if status != 0
+      message = \
+        "#{ path.to_s.inspect } does not appear to be in a Git repo\n\n" +
+        NRSER::Char::NULL.replace( err ) + "\n"
+      
+      raise SystemCallError.new message, status.exitstatus
+    end
+    
+    out.chomp
+  end
+end

data/lib/nrser/refinements/object.rb

@@ -1,17 +1,3 @@
-# Requirements
-# =======================================================================
-
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
-# Project / Package
-# -----------------------------------------------------------------------
-require 'nrser/functions/object'
-
-
 # Definitions
 # =======================================================================
 

data/lib/nrser/refinements/string.rb

@@ -1,8 +1,3 @@
-require 'pathname'
-
-require_relative '../functions/string'
-require_relative '../functions/text'
-
 module NRSER
   refine String do
     def squish

data/lib/nrser/version.rb

@@ -1,5 +1,5 @@
 module NRSER
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
   
   module Version
     

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nrser
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-29 00:00:00.000000000 Z
+date: 2018-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -214,6 +214,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/nrser.rb
+- lib/nrser/char.rb
+- lib/nrser/char/special.rb
 - lib/nrser/collection.rb
 - lib/nrser/env.rb
 - lib/nrser/env/path.rb
@@ -233,6 +235,7 @@ files:
 - lib/nrser/functions/enumerable/find_all_map.rb
 - lib/nrser/functions/enumerable/find_map.rb
 - lib/nrser/functions/exception.rb
+- lib/nrser/functions/git.rb
 - lib/nrser/functions/hash.rb
 - lib/nrser/functions/hash/bury.rb
 - lib/nrser/functions/hash/deep_merge.rb