gamefic 3.3.0 → 3.5.0

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.
@@ -117,16 +117,69 @@ module Gamefic
     #   plot = Plot.new
     #   plot.thing #=> #<Gamefic::Entity a thing>
     #
+    # @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
@@ -154,35 +207,13 @@ module Gamefic
     # This can be useful when you need access to the Scriptable's constants and
     # instance methods, but you don't want to duplicate its rules.
     #
-    # @example
-    #   # Plot and Subplot will both include the `info` method, but
-    #   # only Plot will implement the `think` action.
+    # @deprecated Removing script blocks is no longer necessary. This method
+    #   will simply return self until it's removed.
     #
-    #   module Shared
-    #     extend Gamefic::Scriptable
-    #
-    #     def info
-    #       "This method was added by the Shared module."
-    #     end
-    #
-    #     respond :think do |actor|
-    #       actor.tell 'You ponder your predicament.'
-    #     end
-    #   end
-    #
-    #   class Plot < Gamefic::Plot
-    #     include Shared
-    #   end
-    #
-    #   class Subplot < Gamefic::Subplot
-    #     include Shared.no_scripts
-    #   end
-    #
-    # @return [Module]
+    # @return [Module<self>]
     def no_scripts
-      Module.new.tap do |mod|
-        append_features(mod)
-      end
+      Logging.logger.warn 'Calling `no_scripts` on Scriptable modules is no longer necessary.'
+      self
     end
   end
 end

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,24 @@ 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
+      super - plot.included_blocks
     end
 
     def ready
@@ -37,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.
@@ -65,14 +85,18 @@ module Gamefic
     #
     def configure; end
 
-    def inspect
-      "#<#{self.class}>"
+    def concluding?
+      return super unless persistent?
+
+      @concluded
     end
 
-    def hydrate
-      @rulebook = Rulebook.new(self)
-      @rulebook.script
-      @rulebook.freeze
+    def introduce player
+      @concluded ? player : super
+    end
+
+    def inspect
+      "#<#{self.class}>"
     end
   end
 end

data/lib/gamefic/version.rb

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

data/lib/gamefic.rb

@@ -8,6 +8,7 @@ require 'gamefic/core_ext/string'
 require 'gamefic/syntax'
 require 'gamefic/response'
 require 'gamefic/rulebook'
+require 'gamefic/callback'
 require 'gamefic/query'
 require 'gamefic/scanner'
 require 'gamefic/scope'
@@ -16,19 +17,20 @@ require 'gamefic/command'
 require 'gamefic/action'
 require 'gamefic/props'
 require 'gamefic/scene'
+require 'gamefic/proxy'
 require 'gamefic/scriptable'
 require 'gamefic/block'
 require 'gamefic/stage'
 require 'gamefic/vault'
 require 'gamefic/narrative'
 require 'gamefic/plot'
+require 'gamefic/chapter'
 require 'gamefic/subplot'
 require 'gamefic/snapshot'
 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.3.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-01 00:00:00.000000000 Z
+date: 2024-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -135,8 +135,9 @@ files:
 - lib/gamefic/active/take.rb
 - lib/gamefic/actor.rb
 - lib/gamefic/block.rb
+- 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
@@ -154,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
@@ -167,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
@@ -177,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
@@ -185,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