inform-runtime 1.0.4

data/lib/runtime/grammar_parser.rb

@@ -0,0 +1,553 @@
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2023 but freely usable (see license)
+#
+# This file is part of the Inform Runtime.
+#
+# The Inform Runtime is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The Inform Runtime is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the Inform Runtime.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'set'
+
+# In-file Grammar support implementation follows.
+#
+# Usage example:
+#
+#   Inform::Grammar <<~EOT
+#   Verb meta 'example'
+#       *                                           -> Example;
+#   Verb 'smile'
+#       *                                           -> Smile;
+#   EOT
+module Inform
+  def Grammar(src)
+    source_location = caller_locations(1, 1).first
+    mod_name = File.basename(source_location.path, '.*').gsub(/\W+/, '_').to_sym
+    Inform::Grammar::Parser.new.parse_grammar(mod_name, src.each_line,
+      origin_path: source_location.path, origin_line: source_location.lineno)
+    self
+  end
+  module_function :Grammar
+end
+
+# The Inform module
+module Inform
+  Dictionary = Set.new
+
+  ### Verbs
+  class Verb < Set
+    attr_reader   :meta, :emote
+    attr_accessor :grammars, :source
+
+    def initialize(verbs, source, meta = nil, emote = nil)
+      super()
+      merge(verbs)
+      @meta = meta unless meta.nil?
+      @emote = emote unless emote.nil?
+      @grammars = []
+      @source = source
+    end
+
+    def ==(other)
+      !other.nil? && include?(other.to_s) &&
+        meta? == other.meta? && grammars == other.grammars && super
+    end
+
+    def <=>(other)
+      !other.nil? && include?(other.to_s) &&
+        meta? == other.meta? && grammars == other.grammars && super
+    end
+
+    def eql?(other)
+      !other.nil? && include?(other.to_s) &&
+        meta? == other.meta? && grammars == other.grammars && super
+    end
+
+    def verb
+      first
+    end
+
+    def meta?
+      !meta.nil?
+    end
+
+    def emote?
+      !emote.nil?
+    end
+
+    SpaceString = ' '.freeze
+    VerbString = 'Verb'.freeze
+    MetaString = 'meta'.freeze
+    EmoteString = 'emote'.freeze
+    Newline = "\n".freeze
+
+    def to_s
+      VerbString + SpaceString +
+        if meta?
+          MetaString + SpaceString
+        elsif emote?
+          EmoteString + SpaceString
+        else
+          ''
+        end +
+        map { |verb| "'#{verb}'" }.join(SpaceString) + Newline +
+        grammars.map(&:to_s).join(Newline)
+    end
+    alias to_str to_s
+
+    def hash
+      [super, meta, emote, grammars].hash
+    end
+
+    #### Grammars
+    class Grammar < Array
+      MultipleEnquotedPrepositionPattern = %r{^'(.*)'/'(.*)'+$}.freeze
+      SingleEnquotedPrepositionPattern = %r{^'(.*)'$}.freeze
+      CustomScopePattern = %r{^(.*)=(.*)$}.freeze
+      attr_reader :source, :action, :expected_tokens
+
+      def initialize(grammar, source, action, reverse = nil)
+        super()
+        concat(symbolize_grammar(grammar)) unless grammar.empty?
+        push(:end)
+        @action = action
+        @expected_tokens = grammar.map { |a| a =~ CustomScopePattern ? a.to_s.split('=').first.to_sym : a }
+        @reverse = reverse.nil? ? false : reverse
+        @source = source
+      end
+
+      def empty?
+        length == (include?(:end) ? 1 : 0)
+      end
+
+      SpaceString = ' '.freeze
+      Indention = SpaceString * 4
+      AsteriskString = '*'.freeze
+      ReverseString = 'reverse'.freeze
+      ArrowString = '->'.freeze
+      GrammarTokenPadding = 40
+
+      def to_s
+        Indention + AsteriskString + SpaceString +
+          tokens_sans_end.ljust(GrammarTokenPadding) +
+          ArrowString + SpaceString + action +
+          if reverse?
+            SpaceString + ReverseString
+          else
+            ''
+          end
+      end
+      alias to_str to_s
+
+      def parameters
+        @parameters ||= []
+      end
+
+      def reversed_parameters
+        @reversed_parameters ||= [parameters[1], parameters[0]] + parameters[2..]
+      end
+
+      def expected_parameters
+        reverse? ? reversed_parameters : parameters
+      end
+
+      def reverse?
+        @reverse
+      end
+      alias reversed? reverse?
+
+      private
+
+      def tokens_sans_end
+        self[0..-2].join(SpaceString)
+      end
+
+      def symbolize_grammar(grammar)
+        grammar.map { |token| symbolize_token(token) }
+      end
+
+      def when_matching(regexp, str, &block)
+        match_data = regexp.match(str)
+        return false if match_data.nil?
+        block.call(match_data.captures) if block_given?
+        true
+      end
+
+      def prepositions?(token)
+        when_matching(MultipleEnquotedPrepositionPattern, token) do |matches|
+          Inform::Dictionary.merge(matches.map(&:to_sym))
+        end
+      end
+
+      def preposition?(token)
+        when_matching(SingleEnquotedPrepositionPattern, token) do |matches|
+          Inform::Dictionary << matches.first.to_sym
+        end
+      end
+
+      def custom_scope?(token)
+        when_matching(CustomScopePattern, token) do |matches|
+          parameters << matches.first.to_sym
+        end
+      end
+
+      def symbolize_token(token)
+        return token if prepositions?(token) || preposition?(token) || custom_scope?(token)
+        parameters << token.to_sym
+        token.to_sym
+      end
+    end
+    # class Grammar
+  end
+  # class Verb
+end
+# module Inform
+
+# The Inform module to implement additional Grammar parsing
+module Inform
+  # The DuplicateVerb error class
+  class DuplicateVerb < StandardError
+    UnknownString = 'unknown'.freeze
+
+    attr_writer :file, :line
+
+    def initialize(verb)
+      super()
+      @verb = verb
+      @file = UnknownString
+      @line = UnknownString
+    end
+
+    def to_s
+      "(#{@file}):#{@line}: verb error, verb '#{@verb}', already defined"
+    end
+  end
+
+  # The UnexpectedToken error class
+  class UnexpectedToken < StandardError
+    UnknownString = 'unknown'.freeze
+    attr_writer :file, :line
+
+    def initialize(expected, found)
+      super()
+      @expected = expected
+      @found = found
+      @file = UnknownString
+      @line = UnknownString
+    end
+
+    def to_s
+      "(#{@file}):#{@line}: token error, unexpected '#{@found}', expecting '#{@expected}'"
+    end
+  end
+
+  def self.load_grammar(module_name)
+    Inform::Grammar.load_by_name(module_name)
+  end
+
+  def self.load_grammar_by_path(module_path)
+    Inform::Grammar.load_by_path(module_path)
+  end
+
+  def self.unload_grammars!
+    log.debug "Unloading all grammars"
+    Inform::Grammar::Verbs.clear
+  end
+
+  def self.prime_dictionary
+    Inform::Object.select_map(:name).compact.each do |n|
+      Inform::Dictionary.merge(n.split(/[,\s]+/).grep_v(/[^a-z]/i).map(&:downcase).map(&:to_sym))
+    end
+  end
+
+  ### Grammar
+  module Grammar
+    # The Inform::Grammar::Index class
+    class Index < Hash
+      AdminPattern = %r{admin}.freeze
+      BuilderPattern = %r{builder}.freeze
+      Profanity = %w[shit damn fuck sod].freeze
+      ValidModes = %i[admin builder player].freeze
+      ModePatterns = ValidModes.each_with_object({}) { |key, memo| memo[key] = Regexp.new(key.to_s) }
+
+      def lookup(key, actor = nil, grammar_index = self)
+        return nil if key.nil? || !grammar_index.include?(key)
+        verb = grammar_index[key].dup
+        return verb if actor.nil?
+        return nil if guarded?(verb, actor)
+        filter_by_permission(verb, actor)
+        verb
+      end
+
+      def all(actor = nil, grammar_index = self)
+        return grammar_index.map(&:keys).flatten.sort if actor.nil?
+        mode = role(actor)
+        init_all_verbs_by_mode(mode, grammar_index, actor) unless Inform::Grammar.partitions.include?(mode)
+        Inform::Grammar.partitions[mode]
+      end
+
+      def by_mode(mode = nil, grammar_index = self)
+        mode = validate(mode)
+        init_verbs_filtered_by_mode(mode, grammar_index) unless Inform::Grammar.selections.include?(mode)
+        Inform::Grammar.selections[mode]
+      end
+
+      private
+
+      def init_all_verbs_by_mode(mode, grammar_index, actor, set = verbs_set_instance)
+        verbs = grammar_index.each_with_object(set) do |(key, verb), memo|
+          memo.add(key) unless Profanity.include?(key) || guarded?(verb, actor)
+        end
+        Inform::Grammar.partitions[mode] = verbs.to_a
+      end
+
+      def init_verbs_filtered_by_mode(mode, grammar_index, set = verbs_set_instance)
+        verbs = grammar_index.each_with_object(set) do |(key, verb), memo|
+          memo.add(key) if ModePatterns[mode].match?(verb.source)
+        end
+        Inform::Grammar.selections[mode] = verbs.to_a
+      end
+
+      def verbs_set_instance
+        defined?(Java) ? java.util.TreeSet.new : Set.new
+      end
+
+      def filter_by_permission(verb, actor)
+        verb.grammars.delete_if do |grammar|
+          guarded?(grammar, actor)
+        end
+      end
+
+      def guarded?(resource, obj)
+        (AdminPattern.match?(resource.source) && !obj.admin?) ||
+          (BuilderPattern.match?(resource.source) && !obj.builder?)
+      end
+
+      def role(obj)
+        return :builder if obj.builder?
+        return :admin if obj.admin?
+        :player
+      end
+
+      def validate(mode)
+        return mode.to_sym if ValidModes.include?(mode.to_sym)
+        :player
+      end
+    end
+
+    Verbs = Inform::Grammar::Index.new
+
+    def self.partitions
+      @partitions ||= defined?(Java) ? java.util.concurrent.ConcurrentHashMap.new : {}
+    end
+
+    def self.selections
+      @selections ||= defined?(Java) ? java.util.concurrent.ConcurrentHashMap.new : {}
+    end
+
+    VALID_EXTENSIONS = ['h.inf.rb', '.inf.rb', '.rb', ''].freeze
+
+    def self.absolute_basename(file_path)
+      File.basename(file_path, File.extname(file_path)).split(/\./).first
+    end
+
+    SUPPORT_DIR_PATH = File.expand_path(__dir__) unless defined?(SUPPORT_DIR_PATH)
+    def self.get_path_for_best_match(str)
+      VALID_EXTENSIONS.each do |ext|
+        grammar_guess = str + ext
+        guess = File.expand_path(
+          File.join(
+            Inform::Library.inform_gem_lib_path,
+            Inform::Runtime.inform_dir_path,
+            grammar_guess))
+        return guess if File.exist?(guess)
+      end
+      nil
+    end
+
+    def self.load_by_name(module_name)
+      module_path = get_path_for_best_match(module_name)
+      load_by_path(module_path, module_name)
+    end
+
+    def self.load_by_path(module_path, module_name = nil)
+      raise ArgumentError, 'Parameter may not be nil: module_path' if module_path.nil?
+      raise LoadError, 'No such file: ' + module_path unless File.exist?(module_path)
+      module_name ||= absolute_basename(module_path)
+      log.debug "Loading grammar file: #{module_path}"
+      Inform::Grammar::Parser.new.parse_grammar(
+        module_name.to_sym, File.foreach(module_path), origin_path: module_path)
+    end
+
+    # The Inform::Grammar::Parser class will parse inform-style
+    # grammar files
+    # rubocop: disable Metrics/ClassLength
+    class Parser
+      CommentedOrBlankLine = %r{^\s*[^\#\n]}.freeze
+      TerminalLinePattern = %r{;$}.freeze
+      TokenPattern = %r{'[^\s']+'}.freeze
+      ArrowPattern = %r{->}.freeze
+      def initialize
+        # Base state for block comment toggling
+        @block_comment = false
+      end
+
+      # rubocop: disable Metrics/MethodLength
+      def parse_grammar(grammar_module, lines, origin_path: nil, origin_line: 0)
+        line_index = Integer(origin_line || 0)
+        lines.each do |line|
+          line_index += 1
+          next unless /^\s*[^\#\n]/.match?(line)
+          begin
+            parse(grammar_module, line)
+          rescue DuplicateVerb => e
+            e.file = File.basename(origin_path)
+            e.line = line_index
+            log.warn e
+          rescue UnexpectedToken => e
+            e.file = File.basename(origin_path)
+            e.line = line_index
+            raise e
+          end
+        end
+        true
+      end
+      # rubocop: enable Metrics/MethodLength
+
+      # rubocop: disable Metrics/AbcSize
+      # rubocop: disable Metrics/CyclomaticComplexity
+      # rubocop: disable Metrics/MethodLength
+      # rubocop: disable Metrics/PerceivedComplexity
+      # rubocop: disable Style/RaiseArgs
+      def parse(source, line)
+        return if block_comment?(line)
+        terminal = /;$/.match(line)
+        # terminal = TerminalLinePattern.match?(line)
+        line.gsub!(/\#.*/, '')
+        line.gsub!(/;$/, '')
+        tokens = line.split
+        return if tokens.empty?
+        token = tokens.first
+        @grammars ||= []
+        case token
+        when /^Verb/
+          raise UnexpectedToken.new('*', 'Verb') unless @grammars.empty?
+          tokens.shift
+          meta  = tokens.delete 'meta'
+          emote = tokens.delete 'emote'
+          @first = false
+          @last = true
+          synonym = tokens.delete '='
+          replace = tokens.delete 'replace' # rubocop: disable Lint/UselessAssignment
+          tokens.delete_if { |a| !/'[^\s']+'/.match?(a) }
+          # tokens.delete_if { |a| !TokenPattern.match?(a) }
+          keys = tokens.map { |a| a[1..-2] }
+          key = synonym ? keys.last : keys.first
+          log.debug "Loading verb: #{key}"
+          @verb = Inform::Grammar::Verbs.lookup(key)
+          if @verb
+            raise DuplicateVerb.new(key) unless synonym
+            @verb.merge keys
+          else
+            @verb = Verb.new(keys, source, meta, emote)
+          end
+          keys.each do |k|
+            Inform::Grammar::Verbs[k] = @verb
+          end
+        when /^Extend/
+          raise UnexpectedToken.new('*', 'Extend') unless @grammars.empty?
+          tokens.shift
+          meta = tokens.delete('meta')
+          emote = tokens.delete('emote')
+          only = tokens.delete('only')
+          @first = tokens.delete('first')
+          @last = tokens.delete('last')
+          replace = tokens.delete('replace')
+          tokens.delete_if { |verb_token| !/'[^\s']+'/.match?(verb_token) }
+          # tokens.delete_if { |token| !TokenPattern.match?(token) }
+          keys = tokens.map { |verb_token| verb_token[1..-2] }
+          key = keys.first
+          existing_verb = Inform::Grammar::Verbs.lookup(key)
+          if existing_verb.nil?
+            @verb = Verb.new(keys, source, meta, emote)
+          elsif only.nil?
+            existing_verb.merge(keys)
+            @verb = existing_verb
+            unless replace.nil?
+              @verb.source = source
+              @verb.grammars.clear
+            end
+          else
+            keys.each do |existing_key|
+              Inform::Grammar::Verbs.delete(existing_key)
+              existing_verb.delete(existing_key)
+            end
+            @verb = Verb.new(keys, source, meta, emote)
+            @verb.grammars = existing_verb.grammars if replace.nil?
+            keys.each do |new_key|
+              Inform::Grammar::Verbs[new_key] = @verb
+            end
+          end
+          Inform::Grammar::Verbs[key] = @verb
+        when /\*/
+          tokens, action = line.split(ArrowPattern)
+          tokens = tokens.split
+          tokens.shift
+          reverse = false; reverse = true if /reverse/.match?(action)
+          action = action.gsub(/;/, '').split.first.to_sym
+          grammar = Verb::Grammar.new(tokens, source, action, reverse)
+          @grammars.push(grammar)
+        else
+          unless @verb.nil?
+            new_keys = tokens.map { |verb_token| verb_token[1..-2] }
+            @verb.merge(new_keys) # Set#merge modifies in-place
+            new_keys.each do |new_key|
+              Inform::Grammar::Verbs[new_key] = @verb
+            end
+          end
+        end
+
+        return if terminal.nil?
+
+        if @first.nil?
+          @verb.grammars.concat(@grammars)
+        else
+          @verb.grammars.unshift(*@grammars)
+        end
+        @grammars.clear
+      end
+      # rubocop: enable Metrics/AbcSize
+      # rubocop: enable Metrics/CyclomaticComplexity
+      # rubocop: enable Metrics/MethodLength
+      # rubocop: enable Metrics/PerceivedComplexity
+      # rubocop: enable Style/RaiseArgs
+      # def parse
+
+      def block_comment?(line)
+        if line[/^=begin/]
+          @block_comment = true
+        elsif line[/^=end/]
+          @block_comment = false
+          true
+        else
+          @block_comment
+        end
+      end
+    end
+    # rubocop: enable Metrics/ClassLength
+    # class Parser
+  end
+  # module Grammar
+end
+# module Inform