familia 1.0.0.pre.rc2 → 1.0.0.pre.rc4

data/lib/familia/horreum/serialization.rb

@@ -1,30 +1,75 @@
 # rubocop:disable all
 #
 module Familia
-  # InstanceMethods - Module containing instance-level methods for Familia
-  #
-  # This module is included in classes that include Familia, providing
-  # instance-level functionality for Redis operations and object management.
+
+
+  # Familia::Horreum
   #
   class Horreum
-
-    # Methods that call load and dump (InstanceMethods)
+    # Serialization: Where Objects Go to Become Strings (and Vice Versa)!
+    #
+    # This module is chock-full of methods that'll make your head spin (in a
+    # good way)! We've got loaders, dumpers, and refreshers galore. It's like
+    # a laundromat for your data, but instead of quarters, it runs on Redis commands.
+    #
+    # A Note on Our Refreshing Refreshers:
+    # In the wild world of Ruby, '!' usually means "Watch out! I'm dangerous!"
+    # But here in Familia-land, we march to the beat of a different drummer.
+    # Our refresh! method is the real deal, doing all the heavy lifting.
+    # The non-bang refresh? Oh, it's just as rowdy, but it plays nice with
+    # method chaining. It's like the polite twin who still knows how to party.
+    #
+    # Remember: In Familia, refreshing isn't just a chore, it's a chance to
+    # dance with data! Whether you bang(!) or not, you're still invited to
+    # the Redis disco.
+    #
+    # (P.S. If you're reading these docs, lol sorry. I asked Claude 3.5 to
+    # write in the style of _why the lucky stiff today and got this uncanny
+    # valley response. I hope you enjoy reading it as much as I did writing
+    # the prompt for it. - @delano).
+    #
+    # (Ahem! What I meant to say was that if you're reading this, congratulations!
+    # You've stumbled upon the secret garden of documentation. Feel free to smell
+    # the Ruby roses, but watch out for the Redis thorns!)
     #
-    # Note on refresh methods:
-    # In this class, refresh! is the primary method that performs the Redis
-    # query and state update. The non-bang refresh method is provided as a
-    # convenience for method chaining, but still performs the same destructive
-    # update as refresh!. This deviates from common Ruby conventions to better
-    # fit the specific needs of this system.
     module Serialization
-      #include Familia::RedisType::Serialization
 
       attr_writer :redis
 
+      # Summon the mystical Redis connection from the depths of instance or class.
+      #
+      # This method is like a magical divining rod, always pointing to the nearest
+      # source of Redis goodness. It first checks if we have a personal Redis
+      # connection (@redis), and if not, it borrows the class's connection.
+      #
+      # @return [Redis] A shimmering Redis connection, ready for your bidding.
+      #
+      # @example Finding your Redis way
+      #   puts object.redis
+      #   # => #<Redis client v4.5.1 for redis://localhost:6379/0>
+      #
       def redis
         @redis || self.class.redis
       end
 
+      # Perform a sacred Redis transaction ritual.
+      #
+      # This method creates a protective circle around your Redis operations,
+      # ensuring they all succeed or fail together. It's like a group hug for your
+      # data operations, but with more ACID properties.
+      #
+      # @yield [conn] A block where you can perform your Redis incantations.
+      # @yieldparam conn [Redis] A Redis connection in multi mode.
+      #
+      # @example Performing a Redis rain dance
+      #   transaction do |conn|
+      #     conn.set("weather", "rainy")
+      #     conn.set("mood", "melancholic")
+      #   end
+      #
+      # @note This method temporarily replaces your Redis connection with a multi
+      #   connection. Don't worry, it puts everything back where it found it when it's done.
+      #
       def transaction
         original_redis = self.redis
 
@@ -38,34 +83,111 @@ module Familia
         end
       end
 
-      # A thin wrapper around `commit_fields` that updates the timestamps and
-      # returns a boolean.
+      # Save our precious data to Redis, with a sprinkle of timestamp magic!
+      #
+      # This method is like a conscientious historian, not only recording your
+      # object's current state but also meticulously timestamping when it was
+      # created and last updated. It's the record keeper of your data's life story!
+      #
+      # @return [Boolean] true if the save was successful, false if Redis was grumpy.
+      #
+      # @example Preserving your pet rock for posterity
+      #   rocky = PetRock.new(name: "Dwayne")
+      #   rocky.save
+      #   # => true (Dwayne is now immortalized in Redis)
+      #
+      # @note This method will leave breadcrumbs (traces) if you're in debug mode.
+      #   It's like Hansel and Gretel, but for data operations!
+      #
       def save
         Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
 
-        # Update timestamp fields
+        # Update our object's life story
         self.key ||= self.identifier
         self.updated = Familia.now.to_i
         self.created ||= Familia.now.to_i
 
-        # Thr return value of commit_fields is an array of strings: ["OK"].
+        # Commit our tale to the Redis chronicles
         ret = commit_fields # e.g. ["OK"]
 
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
-        # Convert the return value to a boolean
-        ret.all? { |value| value == "OK" }
+        # Did Redis accept our offering?
+        ret.uniq.all? { |value| ["OK", true].include?(value) }
+      end
+
+      # Apply a smattering of fields to this object like fairy dust.
+      #
+      # @param fields [Hash] A magical bag of named attributes to sprinkle onto
+      #   this instance. Each key-value pair is like a tiny spell, ready to
+      #   enchant our object's properties.
+      #
+      # @return [self] Returns the newly bejeweled instance, now sparkling with
+      #   fresh attributes.
+      #
+      # @example Giving your object a makeover
+      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys
+      #   named Jackie")
+      #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire",
+      #   @loves="little boys named Jackie">
+      #
+      def apply_fields(**fields)
+        fields.each do |field, value|
+          # Whisper the new value into the object's ear (if it's listening)
+          send("#{field}=", value) if respond_to?("#{field}=")
+        end
+        self
       end
 
-      # +return: [Array<String>] The return value of the Redis multi command
+      # Commit our precious fields to Redis.
+      #
+      # This method performs a sacred ritual, sending our cherished attributes
+      # on a journey through the ethernet to find their resting place in Redis.
+      #
+      # @return [Array<String>] A mystical array of strings, cryptic messages
+      #   from the Redis gods.
+      #
+      # @note Be warned, young programmer! This method dabbles in the arcane
+      #   art of transactions. Side effects may include data persistence and a
+      #   slight tingling sensation.
+      #
+      # @example Offering your changes to the Redis deities
+      #   unicorn.name = "Charlie"
+      #   unicorn.horn_length = "magnificent"
+      #   unicorn.commit_fields
+      #   # => ["OK", "OK"] (The Redis gods are pleased with your offering)
+      #
       def commit_fields
         Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
         transaction do |conn|
           hmset
+
+          # Only classes that have the expiration ferature enabled will
+          # actually set an expiration time on their keys. Otherwise
+          # this will be a no-op.
           update_expiration
         end
       end
 
+      # Dramatically vanquish this object from the face of Redis! (ed: delete it)
+      #
+      # This method is the doomsday device of our little data world. It will
+      # mercilessly eradicate all traces of our object from Redis, leaving naught
+      # but digital dust in its wake. Use with caution, lest you accidentally
+      # destroy the wrong data-verse!
+      #
+      # @return [void] Returns nothing, for nothing remains after destruction.
+      #
+      # @example Bidding a fond farewell to your pet rock
+      #   rocky = PetRock.new(name: "Dwayne")
+      #   rocky.destroy!
+      #   # => *poof* Rocky is no more. A moment of silence, please.
+      #
+      # @note If debugging is enabled, this method will leave a trace of its
+      #   destructive path, like breadcrumbs for future data archaeologists.
+      #
+      # @see #delete! The actual hitman carrying out the deed.
+      #
       def destroy!
         Familia.trace :DESTROY, redis, redisuri, caller(1..1) if Familia.debug?
         delete!
@@ -98,9 +220,22 @@ module Familia
         self
       end
 
+      # Transform this object into a magical hash of wonders!
+      #
+      # This method performs an alchemical transmutation, turning our noble object
+      # into a more plebeian hash. But fear not, for in this form, it can slip through
+      # the cracks of the universe (or at least, into Redis) with ease.
+      #
+      # @return [Hash] A glittering hash, each key a field name, each value a
+      #   Redis-ready treasure.
+      #
+      # @example Turning your dragon into a hash
+      #   dragon.to_h
+      #   # => {"name"=>"Puff", "breathes"=>"fire", "age"=>1000}
+      #
+      # @note Watch in awe as each field is lovingly prepared for its Redis adventure!
+      #
       def to_h
-        # Use self.class.fields to efficiently generate a hash
-        # of all the fields for this object
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
           prepared = to_redis(val)
@@ -110,6 +245,21 @@ module Familia
         end
       end
 
+      # Line up all our attributes in a neat little array parade!
+      #
+      # This method marshals all our object's attributes into an orderly procession,
+      # ready to march into Redis in perfect formation. It's like a little data army,
+      # but friendlier and less prone to conquering neighboring databases.
+      #
+      # @return [Array] A splendid array of Redis-ready values, in the order of our fields.
+      #
+      # @example Arranging your unicorn's attributes in a line
+      #   unicorn.to_a
+      #   # => ["Charlie", "magnificent", 5]
+      #
+      # @note Each value is carefully disguised in its Redis costume
+      # before joining the parade.
+      #
       def to_a
         self.class.fields.map do |field|
           val = send(field)
@@ -160,34 +310,9 @@ module Familia
         prepared
       end
 
-      def update_expiration(ttl = nil)
-        ttl ||= opts[:ttl]
-        return if ttl.to_i.zero? # nil will be zero
-
-        Familia.ld "#{rediskey} to #{ttl}"
-        expire ttl.to_i
-      end
     end
     # End of Serialization module
 
     include Serialization # these become Horreum instance methods
   end
 end
-
-__END__
-
-# Consider adding a retry mechanism for the refresh operation
-# if it fails to fetch the expected data:
-def refresh_with_retry(max_attempts = 3)
-  attempts = 0
-  base = 2
-  while attempts < max_attempts
-    refresh!
-    return if name == "Jane Doe" # Or whatever condition indicates a successful refresh
-    attempts += 1
-
-    sleep_time = 0.1 * (base ** attempts)
-    sleep(sleep_time) # Exponential backoff
-  end
-  raise "Failed to refresh after #{max_attempts} attempts"
-end

data/lib/familia/horreum/settings.rb

@@ -29,14 +29,6 @@ module Familia
         }
       end
 
-      def ttl=(v)
-        @ttl = v.to_i
-      end
-
-      def ttl
-        @ttl || self.class.ttl
-      end
-
       def db=(v)
         @db = v.to_i
       end

data/lib/familia/horreum/utils.rb

@@ -28,7 +28,6 @@ module Familia
       # from the `identifier` method).
       #
       def rediskey(suffix = nil, ignored = nil)
-        Familia.ld "[#rediskey] #{identifier} for #{self.class}"
         raise Familia::NoIdentifier, "No identifier for #{self.class}" if identifier.to_s.empty?
         suffix ||= self.suffix # use the instance method to get the default suffix
         self.class.rediskey identifier, suffix

data/lib/familia/horreum.rb

@@ -56,7 +56,7 @@ module Familia
     class << self
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
-        Familia.trace :INHERITED, nil, "Inherited by #{member}", caller if Familia.debug?
+        Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
         member.extend(ClassMethods)
         member.extend(Features)
 

data/lib/familia/logging.rb

@@ -126,26 +126,48 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param redis_instance [Object] The Redis instance being used.
+    # @param redis_instance [Redis, Redis::Future, nil] The Redis instance or
+    #   Future being used.
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
     # @param context [Array<String>, String, nil] The calling context, typically
     #   obtained from `caller` or `caller.first`. Default is nil.
     #
     # @example
-    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller if Familia.debug?
-    #
+    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller(1..1) if
+    #   Familia.debug?
     #
     # @return [nil]
     #
+    # @note This method only executes if LoggerTraceRefinement::ENABLED is true.
+    # @note The redis_instance can be a Redis object, Redis::Future (used in
+    #   pipelined and multi blocks), or nil (when the redis connection isn't
+    #   relevant).
+    #
     def trace(label, redis_instance, ident, context = nil)
       return unless LoggerTraceRefinement::ENABLED
-      instance_id = redis_instance&.id
+
+      # Usually redis_instance is a Redis object, but it could be
+      # a Redis::Future which is what is used inside of pipelined
+      # and multi blocks. In some contexts it's nil where the
+      # redis connection isn't relevant.
+      instance_id = if redis_instance
+        case redis_instance
+        when Redis
+          redis_instance.id.respond_to?(:to_s) ? redis_instance.id.to_s : redis_instance.class.name
+        when Redis::Future
+          "Redis::Future"
+        else
+          redis_instance.class.name
+        end
+      end
+
       codeline = if context
                    context = [context].flatten
                    context.reject! { |line| line =~ %r{lib/familia} }
                    context.first
                  end
+
       @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
 

data/lib/familia/redistype/serialization.rb

@@ -4,63 +4,80 @@ class Familia::RedisType
 
   module Serialization
 
-    # Serializes an individual value for storage in Redis.
-    #
-    # This method prepares a value for storage in Redis by converting it to a string representation.
-    # If a class option is specified, it uses that class's serialization method.
-    # Otherwise, it relies on the value's own `to_s` method for serialization.
+    # Serializes a value for storage in Redis.
     #
     # @param val [Object] The value to be serialized.
-    # @param strict_values [Boolean] Whether to enforce strict value serialization (default: true). Only applies when no class option is specified because the class option is assumed to handle its own serialization.
-    # @return [String] The serialized representation of the value.
+    # @param strict_values [Boolean] Whether to enforce strict value
+    #   serialization (default: true).
+    # @return [String, nil] The serialized representation of the value, or nil
+    #   if serialization fails.
     #
-    # @note When no class option is specified, this method attempts to serialize the value directly.
-    #       If the serialization fails, it falls back to the value's own string representation.
+    # @note When a class option is specified, it uses that class's
+    #   serialization method. Otherwise, it relies on Familia.distinguisher for
+    #   serialization.
     #
     # @example With a class option
-    #   to_redis(User.new(name: "John"), strict_values: false) #=> '{"name":"John"}'
-    #   to_redis(nil, strict_values: false) #=> "" (empty string)
-    #   to_redis(true, strict_values: false) #=> "true"
+    #   to_redis(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
     #
-    # @example Without a class option and strict values
-    #   to_redis(123) #=> "123" (which becomes "123" in Redis)
+    # @example Without a class option
+    #   to_redis(123) #=> "123"
     #   to_redis("hello") #=> "hello"
-    #   to_redis(nil) # raises an exception
-    #   to_redis(true) # raises an exception
     #
-    # @raise [Familia::HighRiskFactor]
+    # @raise [Familia::HighRiskFactor] If serialization fails under strict
+    #   mode.
     #
     def to_redis(val, strict_values = true)
-      ret = nil
+      prepared = nil
 
       Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
 
       if opts[:class]
-        ret = Familia.distinguisher(opts[:class], strict_values)
-        Familia.ld "  from opts[class] <#{opts[:class]}>: #{ret||'<nil>'}"
+        prepared = Familia.distinguisher(opts[:class], strict_values)
+        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared||'<nil>'}"
       end
 
-      if ret.nil?
+      if prepared.nil?
         # Enforce strict values when no class option is specified
-        ret = Familia.distinguisher(val, true)
-        Familia.ld "  from value #{val}<#{val.class}>: #{ret}<#{ret.class}>"
+        prepared = Familia.distinguisher(val, true)
+        Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
       end
 
-      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{ret}<#{ret.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
 
-      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if ret.nil?
-      ret
+      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
+      prepared
     end
 
+    # Deserializes multiple values from Redis, removing nil values.
+    #
+    # @param values [Array<String>] The values to deserialize.
+    # @return [Array<Object>] Deserialized objects, with nil values removed.
+    #
+    # @see #multi_from_redis_with_nil
+    #
     def multi_from_redis(*values)
-      # Avoid using compact! here. Using compact! as the last expression in the method
-      # can unintentionally return nil if no changes are made, which is not desirable.
-      # Instead, use compact to ensure the method returns the expected value.
+      # Avoid using compact! here. Using compact! as the last expression in the
+      # method can unintentionally return nil if no changes are made, which is
+      # not desirable. Instead, use compact to ensure the method returns the
+      # expected value.
       multi_from_redis_with_nil(*values).compact
     end
 
+    # Deserializes multiple values from Redis, preserving nil values.
+    #
+    # @param values [Array<String>] The values to deserialize.
+    # @return [Array<Object, nil>] Deserialized objects, including nil values.
+    #
+    # @raise [Familia::Problem] If the specified class doesn't respond to the
+    #   load method.
+    #
+    # @note This method attempts to deserialize each value using the specified
+    #   class's load method. If deserialization fails for a value, it's
+    #   replaced with nil.
+    #
     # NOTE: `multi` in this method name refers to multiple values from
     # redis and not the Redis server MULTI command.
+    #
     def multi_from_redis_with_nil(*values)
       Familia.ld "multi_from_redis: (#{@opts}) #{values}"
       return [] if values.empty?
@@ -89,6 +106,20 @@ class Familia::RedisType
       values
     end
 
+    # Deserializes a single value from Redis.
+    #
+    # @param val [String, nil] The value to deserialize.
+    # @return [Object, nil] The deserialized object, the default value if
+    #   val is nil, or nil if deserialization fails.
+    #
+    # @note If no class option is specified, the original value is
+    #   returned unchanged.
+    #
+    # NOTE: Currently only the RedisType class uses this method. Horreum
+    # fields are a newer addition and don't support the full range of
+    # deserialization options that RedisType supports. It uses to_redis
+    # for serialization since everything becomes a string in Redis.
+    #
     def from_redis(val)
       return @opts[:default] if val.nil?
       return val unless @opts[:class]
@@ -96,15 +127,6 @@ class Familia::RedisType
       ret = multi_from_redis val
       ret&.first # return the object or nil
     end
-
-    def update_expiration(ttl = nil)
-      ttl ||= opts[:ttl]
-      return if ttl.to_i.zero? # nil will be zero
-
-      Familia.ld "#{rediskey} to #{ttl}"
-      expire ttl.to_i
-    end
-
   end
 
 end

data/lib/familia/redistype.rb

@@ -13,31 +13,29 @@ module Familia
   # @abstract Subclass and implement Redis data type specific methods
   class RedisType
     include Familia::Base
+    extend Familia::Features
 
     @registered_types = {}
     @valid_options = %i[class parent ttl default db key redis]
     @db = nil
-    @ttl = nil
+
+    feature :expiration
+    feature :quantization
 
     class << self
       attr_reader :registered_types, :valid_options
       attr_accessor :parent
-      attr_writer :ttl, :db, :uri
+      attr_writer :db, :uri
 
       # To be called inside every class that inherits RedisType
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
       def register(klass, methname)
-        Familia.ld "[#{self}] Registering #{klass} as #{methname}"
+        Familia.ld "[#{self}] Registering #{klass} as #{methname.inspect}"
 
         @registered_types[methname] = klass
       end
 
-      def ttl(val = nil)
-        @ttl = val unless val.nil?
-        @ttl || parent&.ttl
-      end
-
       def db(val = nil)
         @db = val unless val.nil?
         @db || parent&.db
@@ -49,8 +47,9 @@ module Familia
       end
 
       def inherited(obj)
+        Familia.trace :REDISTYPE, nil, "#{obj} is my kinda type", caller(1..1) if Familia.debug?
         obj.db = db
-        obj.ttl = ttl
+        obj.ttl = ttl # method added via Features::Expiration
         obj.uri = uri
         obj.parent = self
         super(obj)
@@ -101,6 +100,12 @@ module Familia
       @opts = opts || {}
       @opts = RedisType.valid_keys_only(@opts)
 
+      # Apply the options to instance method setters of the same name
+      @opts.each do |k, v|
+        Familia.ld " [setting] #{k} #{v}"
+        send(:"#{k}=", v) if respond_to? :"#{k}="
+      end
+
       init if respond_to? :init
     end
 
@@ -110,10 +115,37 @@ module Familia
       parent? ? parent.redis : Familia.redis(opts[:db])
     end
 
-    # Produces the full redis key for this object.
+    # Produces the full Redis key for this object.
+    #
+    # @return [String] The full Redis key.
+    #
+    # This method determines the appropriate Redis key based on the context of the RedisType object:
+    #
+    # 1. If a hardcoded key is set in the options, it returns that key.
+    # 2. For instance-level RedisType objects, it uses the parent instance's rediskey method.
+    # 3. For class-level RedisType objects, it uses the parent class's rediskey method.
+    # 4. For standalone RedisType objects, it uses the keystring as the full Redis key.
+    #
+    # For class-level RedisType objects (parent_class? == true):
+    # - The suffix is optional and used to differentiate between different types of objects.
+    # - If no suffix is provided, the class's default suffix is used (via the self.suffix method).
+    # - If a nil suffix is explicitly passed, it won't appear in the resulting Redis key.
+    # - Passing nil as the suffix is how class-level RedisType objects are created without
+    #   the global default 'object' suffix.
+    #
+    # @example Instance-level RedisType
+    #   user_instance.some_redistype.rediskey  # => "user:123:some_redistype"
+    #
+    # @example Class-level RedisType
+    #   User.some_redistype.rediskey  # => "user:some_redistype"
+    #
+    # @example Standalone RedisType
+    #   RedisType.new("mykey").rediskey  # => "mykey"
+    #
+    # @example Class-level RedisType with explicit nil suffix
+    #   User.rediskey("123", nil)  # => "user:123"
+    #
     def rediskey
-      Familia.ld "[rediskey] #{keystring} for #{self.class} (#{opts})"
-
       # Return the hardcoded key if it's set. This is useful for
       # support legacy keys that aren't derived in the same way.
       return opts[:key] if opts[:key]
@@ -128,7 +160,7 @@ module Familia
         parent.rediskey(keystring, nil)
       else
         # This is a standalone RedisType object where it's keystring
-        # is the full key.
+        # is the full redis key.
         keystring
       end
     end
@@ -153,10 +185,6 @@ module Familia
       @opts[:parent]
     end
 
-    def ttl
-      @opts[:ttl] || self.class.ttl
-    end
-
     def db
       @opts[:db] || self.class.db
     end

data/lib/familia/settings.rb

@@ -5,7 +5,7 @@ module Familia
   @delim = ':'
   @prefix = nil
   @suffix = :object
-  @ttl = nil
+  @ttl = 0 # see update_expiration. Zero is skip. nil is an exception.
   @db = nil
 
   module Settings
@@ -27,6 +27,16 @@ module Familia
       @suffix
     end
 
+    def ttl(v = nil)
+      @ttl = v unless v.nil?
+      @ttl
+    end
+
+    def db(v = nil)
+      @db = v unless v.nil?
+      @db
+    end
+
     # We define this do-nothing method because it reads better
     # than simply Familia.suffix in some contexts.
     def default_suffix