gamefic 4.1.2 → 4.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e90aabf8b81551f127b57f7a70f62aa0cc92c0bc8e346ffe5056260678b0ae86
-  data.tar.gz: 7607b66f7927acd8310ba3a0be94834102c8fcf1d7458c3bbd950de44cabd9b0
+  metadata.gz: 9800fd3de4b72b22f083edb20b4c9b74b58f306ce70266a1a9c2aa6b40b02d1e
+  data.tar.gz: 0ba0352e45dd1609d2070e915d6fcf3e41175fd7e52dafcdb4ed5151967241d9
 SHA512:
-  metadata.gz: c84cc7bf2a99438d3b61a11197b43c51d3577413f0249ad44360bb7b97520b3c1fec48e39f833c0bd999ae5de3a1b934e2d4b17983544840bccb861504207eca
-  data.tar.gz: 3c512256a34fa09048e79216a1defdc8fa076d89d2bb4549b1bbe35fbaae5c272eb156b84d5daa7f310a800d64217c49cb74c351115e7de8cd8ca25fd57382d5
+  metadata.gz: 1350f7c939581714ba21108e8376faf4091905a5a85e15ec2d7b4fdc0e44de9c6057698117b04abcf763cf4b3cc74d807383c609c23814973cca58b0a318a59e
+  data.tar.gz: fc2464dbfc163a53742af0e286623a08f67c70472acabd8bfb0176aadfd18431b3f7c41a340264cbf79c9b493b8cda0fcf4b13b91be086cf9442ec9b971f3a4e

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 4.2.1 - February 1, 2026
+- Correct Scenes#introduction documentation
+- Fix parsing of piped verbs
+- Binding documentation
+
+## 4.2.0 - November 27, 2025
+- Syntaxes support variable (piped) words
+- Props::MultipleChoice#index_of
+
 ## 4.1.2 - May 25, 2025
 - Seed unreferenced entities
 - Ensure seed uniqueness

data/lib/gamefic/binding.rb

@@ -1,29 +1,54 @@
 # frozen_string_literal: true
 
 module Gamefic
+  # A lightweight wrapper around a `Proc` that executes it in the context of a
+  # specific narrative.
+  #
+  # Gamefic stores most author-written blocks (responses, callbacks, etc.) as
+  # plain Ruby procs. Those blocks are intended to run within the context of
+  # their parent narrative so they can call the narrative's methods.
+  # Gamefic::Binding pairs the proc with its narrative and provides a safe way
+  # to execute it.
+  #
   class Binding
     class << self
+      # A map of objects and the stack of narratives in which they're currently
+      # involved.
+      #
       def registry
         @registry ||= {}
       end
 
+      # Push a narrative to the top of an object's stack.
+      #
+      # @param object [Object]
+      # @param narrative [Narrative]
       def push(object, narrative)
         registry[object] ||= []
         registry[object].push narrative
       end
 
+      # Remove a narrative from the top of an object's stack.
+      #
+      # @param object [Object]
       def pop(object)
         registry[object].pop
         registry.delete(object) if registry[object].empty?
       end
 
+      # Fetch the narrative at the top of an object's stack.
+      #
+      # @param object [Object]
+      # @return [Narrative, nil]
       def for(object)
         registry.fetch(object, []).last
       end
     end
 
+    # @return [Narrative]
     attr_reader :narrative
 
+    # @return [Proc]
     attr_reader :code
 
     # @param narrative [Narrative]
@@ -33,6 +58,9 @@ module Gamefic
       @code = code
     end
 
+    # Execute the binding's code within the context of the narrative.
+    #
+    # @return [void]
     def call(*args)
       args.each { |arg| Binding.push arg, @narrative }
       @narrative.instance_exec(*args, &@code)

data/lib/gamefic/describable.rb

@@ -142,10 +142,10 @@ module Gamefic
     #
     # @param text [String]
     def description=(text)
-      @description = (text if text != (format(Describable.default_description, name: definitely, Name: definitely.capitalize_first)))
+      @description = (text if text != format(Describable.default_description, name: definitely, Name: definitely.capitalize_first))
     end
 
-    def synonyms= text
+    def synonyms=(text)
       @synonyms = text
     end
 

data/lib/gamefic/narrative.rb

@@ -62,7 +62,7 @@ module Gamefic
     #
     # In the base Narrative class, this method runs all applicable player
     # conclude blocks and the narrative's own conclude blocks.
-    # 
+    #
     # @return [void]
     def turn
       players.select(&:concluding?).each { |plyr| player_conclude_blocks.each { |blk| blk[plyr] } }
@@ -77,6 +77,7 @@ module Gamefic
     # @param snapshot [String]
     # @return [self]
     def self.restore(snapshot)
+      # @sg-ignore
       Marshal.load(snapshot)
     end
 

data/lib/gamefic/order.rb

@@ -20,9 +20,9 @@ module Gamefic
     def to_actions
       Action.sort(
         actor.narratives
-            .responses_for(verb)
-            .map { |response| match_arguments(response) }
-            .compact
+             .responses_for(verb)
+             .map { |response| match_arguments(response) }
+             .compact
       )
     end
 

data/lib/gamefic/props/multiple_choice.rb

@@ -5,9 +5,6 @@ module Gamefic
     # Props for MultipleChoice scenes.
     #
     class MultipleChoice < Default
-      # A message to send the player for an invalid choice. A formatting
-      # token named %<input>s can be used to inject the user input.
-      #
       # @return [String]
       attr_writer :invalid_message
 
@@ -18,6 +15,13 @@ module Gamefic
         @options ||= []
       end
 
+      # A message to send the player for an invalid choice. A formatting
+      # token named `%<input>s` can be used to inject the user input.
+      #
+      # @example
+      #   props.invalid_message = '"%<input>s" is not a valid choice.'
+      #
+      # @return [String]
       def invalid_message
         @invalid_message ||= '"%<input>s" is not a valid choice.'
       end
@@ -28,7 +32,7 @@ module Gamefic
       def index
         return nil unless input
 
-        @index ||= index_by_number || index_by_text
+        @index ||= index_of(input)
       end
 
       # The one-based index of the selected option.
@@ -53,15 +57,36 @@ module Gamefic
         !!index
       end
 
+      # Get the index of an option using input criteria, e.g., a one-based
+      # number or the text of the option. The return value is the option's
+      # zero-based index or nil.
+      #
+      # @example
+      #   props = Gamefic::Props::MultipleChoice.new
+      #   props.options.push 'First choice', 'Second choice'
+      #
+      #   props.index_of(1)               # => 0
+      #   props.index_of('Second choice') # => 1
+      #
+      # @param option [String, Integer]
+      # @return [Integer, nil]
+      def index_of(option)
+        index_by_number(option) || index_by_text(option)
+      end
+
       private
 
-      def index_by_number
-        return input.to_i - 1 if input.match(/^\d+$/) && options[input.to_i - 1]
+      # @param [String, Integer]
+      # @return [Integer, nil]
+      def index_by_number(input)
+        return input.to_i - 1 if input.to_s.match(/^\d+$/) && options[input.to_i - 1]
 
         nil
       end
 
-      def index_by_text
+      # @param [String]
+      # @return [Integer, nil]
+      def index_by_text(input)
         options.find_index { |opt| opt.casecmp?(input) }
       end
     end

data/lib/gamefic/props/multiple_partial.rb

@@ -7,7 +7,7 @@ module Gamefic
     class MultiplePartial < MultipleChoice
       private
 
-      def index_by_text
+      def index_by_text(input)
         matches = options.map.with_index { |text, idx| next idx if text.downcase.start_with?(input.downcase) }.compact
         matches.first if matches.one?
       end

data/lib/gamefic/scriptable/scenes.rb

@@ -52,15 +52,12 @@ module Gamefic
       end
 
       # Add a block to be executed when a player is added to the game.
-      # Each Plot should only have one introduction.
       #
       # @example Welcome the player to the game
       #   introduction do |actor|
       #     actor.tell "Welcome to the game!"
       #   end
       #
-      # @raise [ArgumentError] if an introduction already exists
-      #
       # @yieldparam [Gamefic::Actor]
       # @yieldparam [Props::Default]
       # @yieldreceiver [Object<self>]

data/lib/gamefic/scriptable/syntaxes.rb

@@ -17,8 +17,15 @@ module Gamefic
       # @param command [String] The format of the original command
       # @param translation [String] The format of the translated command
       # @return [Syntax] the Syntax object
-      def interpret command, translation
-        syntaxes.push(Syntax.new(command, translation)).last
+      def interpret(command, translation)
+        parts = Syntax.split(command)
+        additions = if parts.first.include?('|')
+                      parts.first.split('|').map { |verb| Syntax.new("#{verb} #{parts[1..].join(' ')}", translation) }
+                    else
+                      [Syntax.new(command, translation)]
+                    end
+        syntaxes.concat additions
+        additions
       end
 
       def syntaxes

data/lib/gamefic/scripting/hooks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scripting
     # Scripting hook methods are instance methods that return callbacks for

data/lib/gamefic/scripting/responses.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scripting
     module Responses

data/lib/gamefic/scripting/scenes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scripting
     module Scenes

data/lib/gamefic/scripting/seeds.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scripting
     module Seeds

data/lib/gamefic/scripting/syntaxes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Scripting
     module Syntaxes

data/lib/gamefic/scripting.rb

@@ -35,7 +35,7 @@ module Gamefic
                       .map { |blk| Binding.new(self, blk) }
     end
 
-    def self.included other
+    def self.included(other)
       super
       other.extend Scriptable
     end

data/lib/gamefic/syntax.rb

@@ -82,9 +82,10 @@ module Gamefic
     #
     # @param text [String]
     # @return [Boolean]
-    def accept?(text)
+    def match?(text)
       !!text.match(regexp)
     end
+    alias accept? match?
 
     # Get a signature that identifies the form of the Syntax.
     # Signatures are used to compare Syntaxes to each other.
@@ -118,6 +119,48 @@ module Gamefic
       string.start_with?(':') ? nil : string.to_sym
     end
 
+    # Split a syntax template by words and expressions.
+    #
+    # @param template [String]
+    # @return [Array<String>]
+    def self.split(template)
+      parens = 0
+      result = template.normalize.chars.each.with_object(['']) do |char, result|
+        parens = parse_token(char, parens, result)
+      end
+      raise "Unbalanced parentheses in syntax '#{template}'" unless parens.zero?
+
+      result.pop if result.last.empty?
+
+      result
+    end
+
+    class << self
+      private
+
+      # @param char [String]
+      # @param parens [Integer]
+      # @param result [Array<String>]
+      def parse_token(char, parens, result)
+        case char
+        when /[()]/
+          parens += (char == '(' ? 1 : -1)
+        when /\s/
+          return parens if result.last.empty?
+
+          if parens.positive?
+            result.push(result.pop + char)
+          else
+            result.push ''
+          end
+        else
+          result.push(result.pop + char)
+        end
+
+        parens
+      end
+    end
+
     private
 
     # @return [String]
@@ -142,9 +185,9 @@ module Gamefic
 
     # @return [Array<String>]
     def make_tokens
-      template.keywords.map.with_index do |word, idx|
+      Syntax.split(template).map.with_index do |word, idx|
+        next "(?:\\b#{word.gsub('|', '|\\b')})" if word.include?('|')
         next word unless word.match?(PARAM_REGEXP)
-
         next nil if idx.positive? && template.keywords[idx - 1].match?(PARAM_REGEXP)
 
         '([\w\W\s\S]*?)'

data/lib/gamefic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gamefic
-  VERSION = '4.1.2'
+  VERSION = '4.2.1'
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 4.1.2
+  version: 4.2.1
 platform: ruby
 authors:
 - Fred Snyder
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-25 00:00:00.000000000 Z
+date: 2026-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -240,7 +239,6 @@ homepage: https://gamefic.com
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -255,8 +253,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Gamefic
 test_files: []