gamefic 3.4.0 → 3.5.0

data/lib/gamefic/scriptable/proxies.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Methods for referencing entities from proxies.
+    #
+    module Proxies
+      # Convert a proxy into its referenced entity.
+      #
+      # This method can receive any kind of object. If it's a proxy, its entity
+      # will be returned. If it's an array, each of its elements will be
+      # unproxied. If it's a hash, each of its values will be unproxied. Any
+      # other object will be returned unchanged.
+      #
+      # @param object [Object]
+      # @return [Object]
+      def unproxy object
+        case object
+        when Proxy
+          object.fetch self
+        when Array
+          object.map { |obj| unproxy obj }
+        when Hash
+          object.transform_values { |val| unproxy val }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/queries.rb

@@ -5,14 +5,14 @@ module Gamefic
     # Scriptable methods related to creating action queries.
     #
     module Queries
-      include Proxy
+      include Proxies
 
       # Define a query that searches the entire plot's entities.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::General]
       def anywhere *args, ambiguous: false
-        Query::General.new -> { entities }, *unproxy(args), ambiguous: ambiguous
+        Query::General.new -> { entities }, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's family of entities. The
@@ -22,7 +22,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def available *args, ambiguous: false
-        Query::Scoped.new Scope::Family, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Family, *args, ambiguous: ambiguous
       end
       alias family available
 
@@ -31,7 +31,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def parent *args, ambiguous: false
-        Query::Scoped.new Scope::Parent, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Parent, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's children.
@@ -39,7 +39,15 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def children *args, ambiguous: false
-        Query::Scoped.new Scope::Children, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Children, *args, ambiguous: ambiguous
+      end
+
+      # Define a query that searches an actor's descendants.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Scoped]
+      def descendants *args, ambiguous: false
+        Query::Scoped.new Scope::Descendants, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's siblings.
@@ -47,7 +55,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def siblings *args, ambiguous: false
-        Query::Scoped.new Scope::Siblings, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Siblings, *args, ambiguous: ambiguous
       end
 
       # Define a query that returns the actor itself.
@@ -55,7 +63,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def myself *args, ambiguous: false
-        Query::Scoped.new Scope::Myself, *unproxy(args), ambiguous: ambiguous
+        Query::Scoped.new Scope::Myself, *args, ambiguous: ambiguous
       end
 
       # Define a query that performs a plaintext search. It can take a String

data/lib/gamefic/scriptable/scenes.rb

@@ -36,7 +36,6 @@ module Gamefic
         rulebook.scenes.add klass.new(name, self, on_start: on_start, on_finish: on_finish, &blk)
         name
       end
-      alias scene block
 
       def preface name, klass = Scene::Activity, &start
         rulebook.scenes.add klass.new(name, self, on_start: start)
@@ -160,9 +159,16 @@ module Gamefic
               on_start: start
       end
 
+      # @return [Array<Symbol>]
       def scenes
         rulebook.scenes.names
       end
+
+      # @param name [Symbol]
+      # @return [Scene::Default, nil]
+      def scene(name)
+        rulebook.scenes[name]
+      end
     end
   end
 end

data/lib/gamefic/scriptable.rb

@@ -23,14 +23,14 @@ module Gamefic
   #   end
   #
   module Scriptable
-    autoload :Actions,   'gamefic/scriptable/actions'
-    autoload :Entities,  'gamefic/scriptable/entities'
-    autoload :Events,    'gamefic/scriptable/events'
-    autoload :Queries,   'gamefic/scriptable/queries'
-    autoload :Proxy,     'gamefic/scriptable/proxy'
-    autoload :Scenes,    'gamefic/scriptable/scenes'
-
-    include Proxy
+    autoload :Actions,     'gamefic/scriptable/actions'
+    autoload :Entities,    'gamefic/scriptable/entities'
+    autoload :Events,      'gamefic/scriptable/events'
+    autoload :Queries,     'gamefic/scriptable/queries'
+    autoload :Proxies,     'gamefic/scriptable/proxies'
+    autoload :Scenes,      'gamefic/scriptable/scenes'
+    autoload :PlotProxies, 'gamefic/scriptable/plot_proxies'
+
     include Queries
     # @!parse
     #   include Scriptable::Actions
@@ -101,10 +101,10 @@ module Gamefic
     #   make_seed Gamefic::Entity, name: 'thing'
     #
     # @param klass [Class<Gamefic::Entity>]
+    # @return [void]
     def make_seed klass, **opts
-      @count ||= 0
       seed { make(klass, **opts) }
-      Proxy::Agent.new(@count.tap { @count += 1 })
+      nil
     end
 
     # Seed an entity with an attribute method.
@@ -119,15 +119,67 @@ module Gamefic
     #
     # @param name [Symbol] The attribute name
     # @param klass [Class<Gamefic::Entity>]
+    # @return [Proxy]
     def attr_seed name, klass, **opts
-      @count ||= 0
-      seed do
-        instance_variable_set("@#{name}", make(klass, **opts))
-        self.class.define_method(name) { instance_variable_get("@#{name}") }
+      ivname = "@#{name}"
+      define_method(name) do
+        return instance_variable_get(ivname) if instance_variable_defined?(ivname)
+
+        instance_variable_set(ivname, make(klass, **opts))
+      end
+      seed { send name }
+      Proxy.new(:attr, name)
+    end
+
+    # @param symbol [Symbol]
+    # @return [Proxy]
+    def proxy symbol
+      Logging.logger.warn "#proxy is deprecated. Use lazy_attr, lazy_ivar, or lazy_pick instead"
+      if symbol.to_s.start_with?('@')
+        lazy_ivar(symbol)
+      else
+        lazy_attr(symbol)
       end
-      Proxy::Agent.new(@count.tap { @count += 1 })
     end
 
+    # Lazy reference an entity by its instance variable.
+    #
+    # @example
+    #   lazy_ivar(:@variable)
+    #
+    # @param key [Symbol]
+    # @return [Proxy]
+    def lazy_ivar key
+      Proxy.new(:ivar, key)
+    end
+    alias _ivar lazy_ivar
+
+    # Lazy reference an entity by its attribute or method.
+    #
+    # @example
+    #   lazy_attr(:method)
+    #
+    # @param key [Symbol]
+    # @return [Proxy]
+    def lazy_attr key
+      Proxy.new(:attr, key)
+    end
+    alias _attr lazy_attr
+
+    # Lazy reference an entity by its description.
+    #
+    # @example
+    #   lazy_pick('the red box')
+    #
+    # @raise [RuntimeError] if a unique match could not be found.
+    #
+    # @param description [String]
+    # @return [Proxy]
+    def lazy_pick description
+      Proxy.new(:pick, description)
+    end
+    alias _pick lazy_pick
+
     if RUBY_ENGINE == 'opal'
       # :nocov:
       def method_missing method, *args, &block

data/lib/gamefic/stage.rb

@@ -14,7 +14,7 @@ module Gamefic
 
     OVERWRITEABLE_CLASSES = [String, Numeric, Symbol].freeze
 
-    SWAPPABLE_VALUES = [true, false, nil].freeze
+    SWAPPABLE_VALUES = [true, false].freeze
 
     class << self
       private
@@ -37,7 +37,7 @@ module Gamefic
       end
 
       def overwriteable? cval, nval
-        return true if swappable?(cval, nval)
+        return true if cval.nil? || swappable?(cval, nval)
 
         allowed = OVERWRITEABLE_CLASSES.find { |klass| cval.is_a?(klass) }
         allowed && cval.is_a?(allowed)

data/lib/gamefic/subplot.rb

@@ -7,6 +7,8 @@ module Gamefic
   # started and concluded at any time during the parent plot's runtime.
   #
   class Subplot < Narrative
+    extend Scriptable::PlotProxies
+
     # @return [Hash]
     attr_reader :config
 
@@ -22,7 +24,20 @@ module Gamefic
       configure
       @config.freeze
       super()
-      [introduce].flatten.each { |pl| self.introduce pl }
+      @concluded = false
+      [introduce].flatten.each { |plyr| self.introduce plyr }
+    end
+
+    def self.persist!
+      @persistent = true
+    end
+
+    def self.persistent?
+      @persistent ||= false
+    end
+
+    def persistent?
+      self.class.persistent?
     end
 
     def included_blocks
@@ -41,6 +56,7 @@ module Gamefic
         uncast plyr
       end
       entities.each { |ent| destroy ent }
+      @concluded = true
     end
 
     # Make an entity that persists in the subplot's parent plot.
@@ -69,6 +85,16 @@ module Gamefic
     #
     def configure; end
 
+    def concluding?
+      return super unless persistent?
+
+      @concluded
+    end
+
+    def introduce player
+      @concluded ? player : super
+    end
+
     def inspect
       "#<#{self.class}>"
     end

data/lib/gamefic/version.rb

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

data/lib/gamefic.rb

@@ -17,6 +17,7 @@ require 'gamefic/command'
 require 'gamefic/action'
 require 'gamefic/props'
 require 'gamefic/scene'
+require 'gamefic/proxy'
 require 'gamefic/scriptable'
 require 'gamefic/block'
 require 'gamefic/stage'
@@ -30,7 +31,6 @@ require 'gamefic/node'
 require 'gamefic/describable'
 require 'gamefic/messenger'
 require 'gamefic/entity'
-require 'gamefic/composer'
 require 'gamefic/dispatcher'
 require 'gamefic/active'
 require 'gamefic/active/cue'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-10 00:00:00.000000000 Z
+date: 2024-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -138,7 +138,6 @@ files:
 - lib/gamefic/callback.rb
 - lib/gamefic/chapter.rb
 - lib/gamefic/command.rb
-- lib/gamefic/composer.rb
 - lib/gamefic/core_ext/array.rb
 - lib/gamefic/core_ext/string.rb
 - lib/gamefic/describable.rb
@@ -156,6 +155,7 @@ files:
 - lib/gamefic/props/output.rb
 - lib/gamefic/props/pause.rb
 - lib/gamefic/props/yes_or_no.rb
+- lib/gamefic/proxy.rb
 - lib/gamefic/query.rb
 - lib/gamefic/query/base.rb
 - lib/gamefic/query/general.rb
@@ -169,6 +169,12 @@ files:
 - lib/gamefic/rulebook/hooks.rb
 - lib/gamefic/rulebook/scenes.rb
 - lib/gamefic/scanner.rb
+- lib/gamefic/scanner/base.rb
+- lib/gamefic/scanner/fuzzy.rb
+- lib/gamefic/scanner/fuzzy_nesting.rb
+- lib/gamefic/scanner/nesting.rb
+- lib/gamefic/scanner/result.rb
+- lib/gamefic/scanner/strict.rb
 - lib/gamefic/scene.rb
 - lib/gamefic/scene/activity.rb
 - lib/gamefic/scene/conclusion.rb
@@ -179,6 +185,7 @@ files:
 - lib/gamefic/scope.rb
 - lib/gamefic/scope/base.rb
 - lib/gamefic/scope/children.rb
+- lib/gamefic/scope/descendants.rb
 - lib/gamefic/scope/family.rb
 - lib/gamefic/scope/myself.rb
 - lib/gamefic/scope/parent.rb
@@ -187,7 +194,8 @@ files:
 - lib/gamefic/scriptable/actions.rb
 - lib/gamefic/scriptable/entities.rb
 - lib/gamefic/scriptable/events.rb
-- lib/gamefic/scriptable/proxy.rb
+- lib/gamefic/scriptable/plot_proxies.rb
+- lib/gamefic/scriptable/proxies.rb
 - lib/gamefic/scriptable/queries.rb
 - lib/gamefic/scriptable/scenes.rb
 - lib/gamefic/snapshot.rb

data/lib/gamefic/composer.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Gamefic
-  # A function module for creating commands from expressions.
-  #
-  module Composer
-    # Create a command from the first expression that matches a response.
-    #
-    # @param actor [Actor]
-    # @param expressions [Array<Expression>]
-    # @return [Command]
-    def self.compose actor, expressions
-      %i[strict fuzzy].each do |method|
-        result = match_expressions_to_response actor, expressions, method
-        return result if result
-      end
-      Command.new(nil, [])
-    end
-
-    class << self
-      private
-
-      def match_expressions_to_response actor, expressions, method
-        expressions.each do |expression|
-          result = match_response_arguments actor, expression, method
-          return result if result
-        end
-        nil
-      end
-
-      def match_response_arguments actor, expression, method
-        actor.epic.responses_for(expression.verb).each do |response|
-          next unless response.queries.length >= expression.tokens.length
-
-          result = match_query_arguments(actor, expression, response, method)
-          return result if result
-        end
-        nil
-      end
-
-      def match_query_arguments actor, expression, response, method
-        remainder = response.verb ? '' : expression.verb.to_s
-        arguments = []
-        response.queries.each_with_index do |query, idx|
-          result = Scanner.send(method, query.select(actor), "#{remainder} #{expression.tokens[idx]}".strip)
-          break unless valid_result_from_query?(result, query)
-
-          if query.ambiguous?
-            arguments.push result.matched
-          else
-            arguments.push result.matched.first
-          end
-          remainder = result.remainder
-        end
-
-        return nil if arguments.length != response.queries.length || remainder != ''
-
-        Command.new(response.verb, arguments)
-      end
-
-      # @param result [Scanner::Result]
-      # @param query [Query::Base]
-      def valid_result_from_query? result, query
-        return false if result.matched.empty?
-
-        result.matched.length == 1 || query.ambiguous?
-      end
-    end
-  end
-end

data/lib/gamefic/scriptable/proxy.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Gamefic
-  module Scriptable
-    # Functions that provide proxies for referencing a narrative's entities
-    # from class-level scripts.
-    #
-    module Proxy
-      # The object that fetches a proxied entity.
-      #
-      class Agent
-        attr_reader :symbol
-
-        # @param symbol [Symbol, Integer]
-        def initialize symbol
-          @symbol = symbol
-        end
-
-        def fetch container
-          result = safe_fetch(container)
-          raise ArgumentError, "Unable to fetch entity from proxy agent symbol `#{symbol}`" unless result
-
-          result
-        end
-
-        private
-
-        def safe_fetch container
-          if symbol.to_s =~ /^\d+$/
-            Stage.run(container, symbol) { |sym| entities[sym] }
-          elsif symbol.to_s.start_with?('@')
-            Stage.run(container, symbol) { |sym| instance_variable_get(sym) }
-          else
-            Stage.run(container, symbol) { |sym| send(sym) }
-          end
-        rescue NoMethodError
-          nil
-        end
-      end
-
-      # Proxy a method or instance variable.
-      #
-      # @example
-      #   proxy(:method_name)
-      #   proxy(:@instance_variable_name)
-      #
-      # @param symbol [Symbol]
-      # @return [Agent]
-      def proxy symbol
-        Agent.new(symbol)
-      end
-
-      # @param object [Object]
-      # @return [Object]
-      def unproxy object
-        case object
-        when Agent
-          object.fetch self
-        when Array
-          object.map { |obj| unproxy obj }
-        when Hash
-          object.transform_values { |val| unproxy val }
-        else
-          object
-        end
-      end
-    end
-  end
-end