cardname 0.15.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09f8f18762c861c7f86ba80f9b3f880c4eed7b44b469d01db78433fbe50db63f'
-  data.tar.gz: 32b9b34f0b2bf444ce301876703f7cb0a45822e64cbf7142731828b09d282f98
+  metadata.gz: 31233d7951221846f2898d40721963a9fe71614d08e5c395faae832546066b61
+  data.tar.gz: b3bbaf9b81dac6212c3434604204d700eb99dfa684dcb13bd6503892ac6219a9
 SHA512:
-  metadata.gz: e9dbdb672ab542bdbf618cd72ed6819f72d469a0a1a0f0ba1d1799977dd66ef21b46e0034b9846948585696ecdca7abbe94811ad18cd9e9d69fe106840c6e6ea
-  data.tar.gz: 840efe97c1f02b061445c9ed8b82b01f04be25c95fe3cdd90da46d3acf5d111be9090ba24d8cc499808d17f762c87a5c3100ee4440e4bb94e7f2f3fb7f094184
+  metadata.gz: 1c30f90fb867e3fb83279c46b55976fdcd96301b744517a56e9aee4427e3562e45ff3fda00b28c416913312e9a1b02008299b6958aaad09bcdc5fa1dcea2e8ee
+  data.tar.gz: 8482990c4776c0fa2529309d5116fefd28f03a3f32561335c09c3581b8dac5355240c72507a788903cec46eb4884285d790696abd3775136fac54c863acd316c

data/lib/cardname/class_methods.rb

@@ -0,0 +1,60 @@
+class Cardname
+  # methods for the Cardname class.
+  module ClassMethods
+    # #new skips installation and returns a cached Cardname object when possible
+    # @return [Cardname]
+    def new obj
+      return obj if obj.is_a? self.class
+
+      str = stringify(obj)
+      cache[str] ||= super(str)
+    end
+
+    # Cardname cache. keys are strings, values are corresponding Cardname objects
+    # Note that unlike most decko/card caches, the cardname cache is process-specific
+    # and should not need to be reset even with data changes, because Cardname objects
+    # are not data-aware.
+    #
+    # @return [Hash]
+    def cache
+      @cache ||= {}
+    end
+
+    # reset Cardname cache
+    # @see #cache
+    # @return [Hash]
+    def reset
+      @cache = {}
+    end
+
+    # true if there are no banned characters
+    # @return [Boolean]
+    def nothing_banned?
+      return @nothing_banned unless @nothing_banned.nil?
+
+      @nothing_banned = banned_array.empty?
+    end
+
+    # regular expression for detecting banned characters
+    # @return [Regexp]
+    def banned_re
+      @banned_re ||= /[#{Regexp.escape((banned_array + [joint])).join}]/
+    end
+
+    # split string on joint into parts
+    # @return [Array]
+    def split_parts str
+      str.split(/\s*#{JOINT_RE}\s*/, -1)
+    end
+
+    private
+
+    def stringify obj
+      if obj.is_a?(Array)
+        obj.map(&:to_s) * joint
+      else
+        obj.to_s
+      end
+    end
+  end
+end

data/lib/cardname/contextual.rb

@@ -1,8 +1,9 @@
 class Cardname
+  # contextual (or relative) names are names that vary by context
   module Contextual
     RELATIVE_REGEXP = /\b_(left|right|whole|self|user|main|\d+|L*R?)\b/
 
-    # @return true if name is left or right of context
+    # @return [Boolean] true if name is left or right of context
     def child_of? context
       return false unless compound?
 
@@ -10,22 +11,31 @@ class Cardname
       absolute_name(context).parent_keys.include? context_key
     end
 
+    # @return [Boolean]
     def relative?
       starts_with_joint? || (s =~ RELATIVE_REGEXP).present?
     end
 
+    # starts with joint, no other contextual element
+    # @return [Boolean]
     def simple_relative?
       starts_with_joint? && (s =~ RELATIVE_REGEXP).nil?
     end
 
+    # not relative
+    # @return [Boolean]
     def absolute?
       !relative?
     end
 
+    # contextual elements removed
+    # @return [String]
     def stripped
       s.gsub RELATIVE_REGEXP, ""
     end
 
+    # +X
+    # @return [Boolean]
     def starts_with_joint?
       compound? && parts.first.empty?
     end
@@ -44,22 +54,46 @@ class Cardname
       key == compressed.absolute_name(from).key ? compressed : self
     end
 
-    def remove_context *from
-      return false unless from.compact.present?
+    # @return [String]
+    def absolute context
+      context = (context || "").to_name
+      new_parts = absolutize_contextual_parts context
+      return "" if new_parts.empty?
 
-      remaining = parts_excluding(*from)
-      return false if remaining.compact.empty? || # all name parts in context
-                      remaining == parts          # no name parts in context
+      absolutize_extremes new_parts, context.s
+      new_parts.join self.class.joint
+    end
 
-      remaining
+    # @return [Cardname]
+    def absolute_name *args
+      absolute(*args).to_name
+    end
+
+    # 1 = left; 2= left of left; 3 = left of left of left....
+    # @return [Cardname]
+    def nth_left_name n
+      (n >= length ? parts[0] : parts[0..-n - 1]).to_name
     end
 
+    private
+
     def parts_excluding *string
       exclude_name = string.to_name
       exclude_keys = exclude_name ? exclude_name.part_names.map(&:key) : []
       parts_minus exclude_keys
     end
 
+    def remove_context *from
+      return false unless from.compact.present?
+
+      remaining = parts_excluding(*from)
+      return false if remaining.compact.empty? || # all name parts in context
+                      remaining == parts          # no name parts in context
+
+      remaining
+    end
+
+    # @return [Array <String>]
     def parts_minus keys_to_ignore
       parts.map do |part|
         next if part.empty?
@@ -70,26 +104,6 @@ class Cardname
       end
     end
 
-    def absolute context
-      context = (context || "").to_name
-      new_parts = absolutize_contextual_parts context
-      return "" if new_parts.empty?
-
-      absolutize_extremes new_parts, context.s
-      new_parts.join self.class.joint
-    end
-
-    def absolute_name *args
-      absolute(*args).to_name
-    end
-
-    def nth_left n
-      # 1 = left; 2= left of left; 3 = left of left of left....
-      (n >= length ? parts[0] : parts[0..-n - 1]).to_name
-    end
-
-    private
-
     def absolutize_contextual_parts context
       parts.map do |part|
         case part
@@ -118,7 +132,7 @@ class Cardname
     def partmap_part match, context
       l_s = match[1].size
       r_s = !match[2].empty?
-      l_part = context.nth_left l_s
+      l_part = context.nth_left_name l_s
       r_s ? l_part.tag : l_part.s
     end
 

data/lib/cardname/manipulate.rb

@@ -1,52 +1,47 @@
 class Cardname
+  # methods for altering name
   module Manipulate
-    # swap a subname
-    # keys are used for comparison
-    def swap old, new
-      old_name = old.to_name
-      new_name = new.to_name
-      return self if old_name.num_parts > num_parts
-      return swap_part(old_name, new_name) if old_name.simple?
-      return self unless include? old_name
-
-      swap_all_subsequences(old_name, new_name).to_name
+    # alter cardname based on card index
+    # @return [Cardname]
+    def []= index, val
+      p = parts
+      p[index] = val
+      replace self.class.new(p)
     end
 
-    def swap_part oldpart, newpart
-      ensure_simpleness oldpart, "Use 'swap' to swap junctions"
-
-      oldpart = oldpart.to_name
-      newpart = newpart.to_name
-
-      parts.map do |p|
-        oldpart == p ? newpart : p
-      end.to_name
+    # append part to cardname
+    # @return [Cardname]
+    def << val
+      replace self.class.new(parts << val)
     end
 
-    def swap_piece oldpiece, newpiece
-      oldpiece = oldpiece.to_name
-      newpiece = newpiece.to_name
-
-      return swap_part oldpiece, newpiece if oldpiece.simple?
-      return self unless starts_with_parts?(oldpiece)
-      return newpiece if oldpiece.num_parts == num_parts
-
-      self.class.new [newpiece, self[oldpiece.num_parts..-1]].flatten
-    end
-
-    def num_parts
-      parts.length
-    end
+    # swap one name for another (keys are used for comparison)
+    # @return [Cardname]
+    def swap old, new
+      old_name = old.to_name
+      new_name = new.to_name
 
-    def [] *args
-      self.class.new part_names[*args]
+      if old_name.num_parts > num_parts
+        self
+      elsif old_name.simple?
+        swap_part old_name, new_name
+      elsif include? old_name
+        swap_all_subsequences(old_name, new_name).to_name
+      else
+        self
+      end
     end
 
+    # add a joint to name's beginning (if it doesn't already start with one)
+    # @return [String]
     def prepend_joint
       joint = self.class.joint
       self =~ /^#{Regexp.escape joint}/ ? self : (joint + self)
     end
+    alias_method :to_field, :prepend_joint
 
+    # substitute name, where it appears in str, with new string
+    # @return [String]
     def sub_in str, with:
       %i[capitalize downcase].product(%i[pluralize singularize])
                              .inject(str) do |s, (m1, m2)|
@@ -54,10 +49,12 @@ class Cardname
       end
     end
 
-    alias_method :to_field, :prepend_joint
-
     private
 
+    def swap_part oldpart, newpart
+      parts.map { |p| oldpart == p ? newpart : p }.to_name
+    end
+
     def swap_all_subsequences oldseq, newseq
       res = []
       i = 0
@@ -75,11 +72,5 @@ class Cardname
       res += parts[i..-1] if i < num_parts
       res
     end
-
-    def ensure_simpleness part, msg=nil
-      return if part.to_name.simple?
-
-      raise StandardError, "'#{part}' has to be simple. #{msg}"
-    end
   end
 end

data/lib/cardname/parts.rb

@@ -1,82 +1,156 @@
 class Cardname
   # naming conventions:
-  # methods that end with _name return name objects
-  # the same methods without _name return strings
+  #
+  #   - methods that end with _name return {Cardname} objects
+  #   - methods that end with _key return {Cardname#key case/space keys}
+  #   - methods without _name or _key return Strings
+  #
   module Parts
-    # PARTS
-    def part_names
-      @part_names ||= generate_part_names
+    # the part of a compound name to the left of the rightmost joint.
+    # @example
+    #     "A".cardname.left -> nil
+    #     "A+B".cardname.left -> "A"
+    #     "A+B+C".cardname.left -> "A+B"
+    #     "A+B+C+D".cardname.left -> "A+B+C"
+    # @see #trunk
+    # @return [String]
+    def left
+      left_name&.s
+    end
+
+    # @see #left
+    # @return [String]
+    def left_key
+      left_name&.key
+    end
+
+    # @see #left
+    # @return [Cardname]
+    def left_name
+      simple? ? nil : self.class.new(part_names[0..-2])
+    end
+
+    # for compound cards, an array of the left and right
+    # @example
+    #     "A".cardname.parents -> []
+    #     "A+B".cardname.parents -> ["A", "B"]
+    #     "A+B+C".cardname.parents -> ["A+B", "C"]
+    #     "A+B+C+D".cardname.parents -> ["A+B+C", "D"]
+    # @see #parts
+    # @return [Array <String>]
+    def parents
+      parent_names.map(&:s)
     end
 
+    # @see #parents
+    # @return [Array <String>]
+    def parent_keys
+      parent_names.map(&:key)
+    end
+
+    # @see #parents
+    # @return [Array <Cardname>]
+    def parent_names
+      simple? ? [] : [left_name, right_name]
+    end
+
+    # for compound cards, each joint separated part
+    # @example
+    #     "A".cardname.parts -> []
+    #     "A+B".cardname.parts -> ["A", "B"]
+    #     "A+B+C".cardname.parts -> ["A", "B", "C"]
+    #     "A+B+C+D".cardname.parts -> ["A", "B", C", "D"]
+    # @see #parents
+    # @return [Array <String>]
     def parts
       part_names.map(&:s)
     end
     alias_method :to_a, :parts
 
+    # @see #parts
+    # @return [Array <String>]
     def part_keys
       part_names.map(&:key)
     end
 
-    def trunk_name
-      simple? ? self : left_name
+    # @see #parts
+    # @return [Array <Cardname>]
+    def part_names
+      @part_names ||= generate_part_names
     end
 
+    # like #left, but returns self for simple cards
+    # @example
+    #     "A".cardname.trunk -> "A"
+    #     "A+B".cardname.trunk -> "A"
+    #     "A+B+C".cardname.trunk -> "A+B"
+    #     "A+B+C+D".cardname.trunk -> "A+B+C"
+    # @see #left
+    # @return [String]
     def trunk
       trunk_name.s
     end
 
+    # @see #trunk
+    # @return [String]
     def trunk_key
       trunk_name.key
     end
 
-    def tag_name
-      simple? ? self : right_name
+    # @see #trunk
+    # @return [Cardname]
+    def trunk_name
+      simple? ? self : left_name
     end
 
+    # like #right, but returns self for simple cards
+    # @see #right
+    # @example
+    #     "A".cardname.tag -> "A"
+    #     "A+B".cardname.tag -> "B"
+    #     "A+B+C".cardname.tag -> "C"
+    #     "A+B+C+D".cardname.tag -> "D"
+    # @return [String]
     def tag
       tag_name.s
     end
 
+    # @see #tag
+    # @return [String]
     def tag_key
       tag_name.key
     end
 
-    def parent_names
-      simple? ? [] : [left_name, right_name]
-    end
-
-    def parents
-      parent_names.map(&:s)
-    end
-
-    def parent_keys
-      parent_names.map(&:key)
-    end
-
-    def left_name
-      simple? ? nil : self.class.new(part_names[0..-2])
-    end
-
-    def left
-      left_name&.s
-    end
-
-    def left_key
-      left_name&.key
-    end
-
-    def right_name
-      simple? ? nil : part_names[-1]
+    # @see #tag
+    # @return [Cardname]
+    def tag_name
+      simple? ? self : right_name
     end
 
+    # the part of a compound name to the left of the rightmost joint.
+    #
+    #     "A".cardname.right -> nil
+    #     "A+B".cardname.right -> "B"
+    #     "A+B+C".cardname.right -> "C"
+    #     "A+B+C+D".cardname.right -> "D"
+    # @see #tag
+    # @return [String]
     def right
       right_name&.s
     end
 
+    # @see #right
+    # @return [String]
     def right_key
       right_name&.key
     end
 
+    # @see #right
+    # @return [Cardname]
+    def right_name
+      simple? ? nil : part_names[-1]
+    end
+
     private
 
     def generate_part_names

data/lib/cardname/pieces.rb

@@ -5,23 +5,35 @@ class Cardname
   module Pieces
     # self and all ancestors (= parts and recursive lefts)
     # @example
-    #   "A+B+C+D".to_name.pieces
-    #   # => ["A", "B", "C", "D", "A+B", "A+B+C", "A+B+C+D"]
+    #   "A+B+C+D".to_name.pieces => ["A", "B", "C", "D", "A+B", "A+B+C", "A+B+C+D"]
+    # @return [Array <String>]
     def pieces
-      simple? ? [self] : (parts + junction_pieces)
+      simple? ? [self] : (parts + compound_pieces)
     end
 
+    # @see #pieces
+    # @return [Array <Cardname>]
     def piece_names
       pieces.map(&:to_name)
     end
 
+    # parents, parents' parents, etc
+    # @example
+    #   "A+B+C+D".to_name.ancestors => ["A", "B", "C", "D", "A+B", "A+B+C"]
+    # @return [Array <String>]
     def ancestors
       pieces.reject { |p| p == self }
     end
 
+    # @see #ancestors
+    # @return [Array <Cardname>]
+    def ancestor_pieces
+      ancestors.map(&:to_name)
+    end
+
     private
 
-    def junction_pieces
+    def compound_pieces
       [].tap do |pieces|
         parts[1..-1].inject parts[0] do |left, right|
           piece = [left, right] * self.class.joint

data/lib/cardname/predicates.rb

@@ -1,16 +1,18 @@
 class Cardname
+  # name methods returning true/false
   module Predicates
-    # @return true if name has only one part
+    # @return [Boolean] true if name has only one part
     def simple?
       part_names if @simple.nil?
       @simple
     end
 
-    # @return true if name has more than one part
+    # @return [Boolean] true if name has more than one part
     def compound?
       !simple?
     end
 
+    # @return [Boolean] true unless name contains banned characters
     def valid?
       return true if self.class.nothing_banned?
 
@@ -19,21 +21,21 @@ class Cardname
       end
     end
 
-    # @return true if name starts with the same parts as `prefix`
+    # @return [Boolean] true if name starts with the same parts as `prefix`
     def starts_with_parts? *prefix
       start_name = prefix.to_name
       start_name == self[0, start_name.num_parts]
     end
     alias_method :start_with_parts?, :starts_with_parts?
 
-    # @return true if name ends with the same parts as `prefix`
+    # @return [Boolean] true if name ends with the same parts as `prefix`
     def ends_with_parts? *suffix
       end_name = suffix.to_name
       end_name == self[-end_name.num_parts..-1]
     end
     alias_method :end_with_parts?, :ends_with_parts?
 
-    # @return true if name has a chain of parts that equals `subname`
+    # @return [Boolean] true if name has a chain of parts that equals `subname`
     def include? subname
       subkey = subname.to_name.key
       key =~ /(^|#{JOINT_RE})#{Regexp.quote subkey}($|#{JOINT_RE})/

data/lib/cardname/variants.rb

@@ -2,6 +2,7 @@ require "htmlentities"
 
 class Cardname
   module Variants
+    # @return [String]
     def simple_key
       return "" if empty?
 
@@ -14,6 +15,8 @@ class Cardname
         .join("_")
     end
 
+    # URI-friendly version of name. retains case, underscores for space
+    # @return [String]
     def url_key
       part_names.map do |part_name|
         stripped = part_name.decoded.gsub(/[^#{OK4KEY_RE}]+/, " ").strip
@@ -24,18 +27,16 @@ class Cardname
     # safe to be used in HTML as id ('*' and '+' are not allowed),
     # but the key is no longer unique.
     # For example "A-XB" and "A+*B" have the same safe_key
+    # @return [String]
     def safe_key
       key.tr("*", "X").tr self.class.joint, "-"
     end
 
+    # @return [String]
     def decoded
       @decoded ||= s.index("&") ? HTMLEntities.new.decode(s) : s
     end
 
-    def to_sym
-      s.to_sym
-    end
-
     private
 
     def uninflect_method

data/lib/cardname.rb

@@ -3,6 +3,10 @@
 require "active_support/inflector"
 require "htmlentities"
 
+# The Cardname class generalizes the core naming concepts of Decko/Card. The most central
+# of these is the idea that compound names can be formed by combining simple names.
+#
+#
 class Cardname < String
   require "cardname/parts"
   require "cardname/pieces"
@@ -11,6 +15,7 @@ class Cardname < String
   require "cardname/predicates"
   require "cardname/manipulate"
   require "cardname/fields"
+  require "cardname/class_methods"
 
   include Parts
   include Pieces
@@ -19,8 +24,7 @@ class Cardname < String
   include Predicates
   include Manipulate
   include Fields
-
-  OK4KEY_RE = '\p{Word}\*'
+  extend ClassMethods
 
   cattr_accessor :joint, :banned_array, :var_re, :uninflect, :params, :session, :stabilize
 
@@ -30,49 +34,9 @@ class Cardname < String
   self.uninflect      = :singularize
   self.stabilize      = false
 
+  OK4KEY_RE = '\p{Word}\*'
   JOINT_RE = Regexp.escape joint
 
-  class << self
-    def new obj
-      return obj if obj.is_a? self.class
-
-      str = stringify(obj)
-      cache[str] ||= super(str)
-    end
-
-    def reset
-      @cache = {}
-    end
-
-    def nothing_banned?
-      return @nothing_banned unless @nothing_banned.nil?
-
-      @nothing_banned = banned_array.empty?
-    end
-
-    def banned_re
-      @banned_re ||= /[#{Regexp.escape((banned_array + [joint])).join}]/
-    end
-
-    def split_parts str
-      str.split(/\s*#{JOINT_RE}\s*/, -1)
-    end
-
-    def cache
-      @cache ||= {}
-    end
-
-    private
-
-    def stringify obj
-      if obj.is_a?(Array)
-        obj.map(&:to_s) * joint
-      else
-        obj.to_s
-      end
-    end
-  end
-
   # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   # ~~~~~~~~~~~~~~~~~~~~~~ INSTANCE ~~~~~~~~~~~~~~~~~~~~~~~~~
   attr_reader :key
@@ -87,31 +51,32 @@ class Cardname < String
     freeze
   end
 
+  # simple string version of name
+  # @return [String]
   def s
     String.new self
   end
   alias_method :to_s, :s
   alias_method :to_str, :s
-  # alias_method :dup, :clone
 
+  # @return [Cardname]
   def to_name
     self
   end
 
-  def []= index, val
-    p = parts
-    p[index] = val
-    replace self.class.new(p)
-  end
-
-  def << val
-    replace self.class.new(parts << val)
+  # @return [Symbol]
+  def to_sym
+    s.to_sym
   end
 
+  # the key defines the namespace
+  # @return [String]
   def key
     @key ||= generate_key.freeze
   end
 
+  # test for same key
+  # @return [Boolean]
   def == other
     key ==
       case
@@ -121,6 +86,18 @@ class Cardname < String
       end
   end
 
+  # cardname based on part index
+  # @return [Cardname]
+  def [] *args
+    self.class.new part_names[*args]
+  end
+
+  # @see #parts
+  # @return [Integer]
+  def num_parts
+    parts.length
+  end
+
   private
 
   def generate_key

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cardname
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Ethan McCutchen
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-04 00:00:00.000000000 Z
+date: 2023-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -50,6 +50,7 @@ files:
 - README.md
 - Rakefile
 - lib/cardname.rb
+- lib/cardname/class_methods.rb
 - lib/cardname/contextual.rb
 - lib/cardname/fields.rb
 - lib/cardname/manipulate.rb