gloo 6.7.2 → 7.0

data/lib/gloo/core/verb.rb

@@ -29,6 +29,60 @@ module Gloo
         Dictionary.instance.register_verb( subclass )
       end
 
+      #
+      # Report any syntax problem in the command's tokens or params
+      # (see Tokens#syntax_problem) as a syntax error. The verb still
+      # runs afterward, with the tokens' best guess.
+      #
+      def check_syntax
+        [ @tokens, @params ].each do |t|
+          problem = t.syntax_problem if t.respond_to?( :syntax_problem )
+          @engine.syntax_err problem if problem
+        end
+      end
+
+      #
+      # For a verb that takes no object: whatever was written after it,
+      # as one string (empty if nothing was).
+      #
+      def extra_words
+        words = @tokens.respond_to?( :params ) ? @tokens.params.to_a : []
+        words += @params.tokens.to_a if @params.respond_to?( :tokens )
+        return words.join( ' ' )
+      end
+
+      #
+      # The verb as written in the command (keyword or shortcut).
+      #
+      def written_verb
+        written = @tokens.verb if @tokens.respond_to?( :verb )
+        return written || self.class.keyword
+      end
+
+      #
+      # For a harmless verb that takes no object: warn if anything was
+      # written after it. The verb still runs.
+      #
+      def warn_extra_words
+        extra = extra_words
+        return if extra.empty?
+
+        @engine.warn "#{written_verb} takes no object; ignoring '#{extra}'."
+      end
+
+      #
+      # For a destructive verb that takes no object: if anything was
+      # written after it, report an error and return true; the verb
+      # should not run. The detail says what didn't happen and what to
+      # do instead.
+      #
+      def extra_words_err?( detail )
+        return false if extra_words.empty?
+
+        @engine.err "#{written_verb} takes no object, so #{detail}."
+        return true
+      end
+
       #
       # Run the verb.
       #

data/lib/gloo/exec/dispatch.rb

@@ -12,7 +12,6 @@ module Gloo
   module Exec
     class Dispatch
 
-      OBJ_NOT_FOUND_ERR = 'Object was not found: '.freeze
 
       # 
       # Send a message to an object of a given name (and path).
@@ -20,10 +19,14 @@ module Gloo
       # 
       def self.send_message( engine, msg, to_obj_pn, params = nil )
         pn = Gloo::Core::Pn.new( engine, to_obj_pn )
+        return if pn.it_target_err?( 'sent messages' )
+
         target_obj = pn.resolve
 
         unless target_obj
-          engine.err "#{OBJ_NOT_FOUND_ERR} #{to_obj_pn}"
+          # The message never ran, so there is no result.
+          engine.err Gloo::Core::NotFound.object( to_obj_pn )
+          engine.heap.it.set_to false
           return
         end
         Gloo::Exec::Dispatch.message( engine, msg, target_obj, params )
@@ -44,10 +47,6 @@ module Gloo
       # Dispatch an action.
       #
       def self.action( engine, action )
-        unless action.valid?
-          engine.log.warn "Object #{action.to.name} does not respond to #{action.msg}"
-        end
-
         engine.exec_env.push_action action
         engine.log.debug "Sending message #{action.msg} to #{action.to.name}"
         action.dispatch

data/lib/gloo/exec/exec_env.rb

@@ -12,6 +12,9 @@ module Gloo
       attr_accessor :verbs, :actions, :scripts, :here
       attr_reader :running_script
 
+      # The file and line being loaded, if a file is being loaded.
+      attr_accessor :load_location
+
       VERB_STACK = 'verbs'.freeze
       ACTION_STACK = 'actions'.freeze
       SCRIPT_STACK = 'scripts'.freeze
@@ -31,6 +34,16 @@ module Gloo
         @here = Gloo::Exec::Stack.new( @engine, HERE_STACK )
       end
 
+      #
+      # Where the line now running is, for error messages: the running
+      # script and its line, or the file and line being loaded.
+      #
+      def current_location
+        return @running_script.location if @running_script
+
+        return @load_location
+      end
+
       #
       # Get the here object.
       #

data/lib/gloo/exec/runner.rb

@@ -20,8 +20,12 @@ module Gloo
         engine.heap.error.start_tracking
         engine.exec_env.verbs.push verb
         begin
+          verb&.check_syntax
           verb&.run
-        rescue => ex
+        rescue StandardError, ScriptError => ex
+          # ScriptError (a SyntaxError from eval'd code, a LoadError
+          # from a missing gem) isn't a StandardError, and would
+          # otherwise stop gloo altogether.
           engine.handle_exception( ex )
         ensure
           engine.exec_env.verbs.pop
@@ -36,12 +40,16 @@ module Gloo
       def self.run( engine, path_name )
         engine.log.debug "running script at #{path_name}"
         pn = Gloo::Core::Pn.new( engine, path_name )
+        return if pn.it_target_err?( 'run' )
+
         o = pn.resolve
 
         if o
           o.send_message 'run'
         else
-          engine.err "Could not send message to object.  Bad path: #{path_name}"
+          # The message never ran, so there is no result.
+          engine.err Gloo::Core::NotFound.object( path_name )
+          engine.heap.it.set_to false
         end
       end
 

data/lib/gloo/exec/script.rb

@@ -16,6 +16,7 @@ module Gloo
         @engine = engine
         @obj = obj
         @break_out = false
+        @line = 0
       end
 
       #
@@ -27,10 +28,13 @@ module Gloo
         @engine.exec_env.push_script self
 
         if @obj.value.is_a? String
+          @line = 1
           @engine.parser.run @obj.value
         elsif @obj.value.is_a? Array
-          @obj.value.each do |line|
+          @obj.value.each_with_index do |line, i|
             break if @break_out
+
+            @line = i + 1
             @engine.parser.run line
           end
         end
@@ -38,6 +42,14 @@ module Gloo
         @engine.exec_env.pop_script
       end
 
+      #
+      # Where this script is in its run: its path and the line now
+      # running (counting from 1), for error messages.
+      #
+      def location
+        return "#{@obj.pn}, line #{@line}"
+      end
+
       #
       # Generic function to get display value.
       # Can be used for debugging, etc.

data/lib/gloo/expr/expression.rb

@@ -8,6 +8,8 @@ module Gloo
   module Expr
     class Expression
 
+      DIVIDE_BY_ZERO_ERR = 'Division by zero.'.freeze
+
       # ---------------------------------------------------------------------
       #    Constructor
       # ---------------------------------------------------------------------
@@ -36,6 +38,7 @@ module Gloo
 
         @symbols.each do |sym|
           if sym.is_a? Gloo::Core::Op
+            missing_value( @op ) if @op
             @op = sym
           elsif @left.nil?
             @left = sym
@@ -45,6 +48,7 @@ module Gloo
 
           perform_op if @left && @right
         end
+        missing_value( @op ) if @op
 
         return @left.value if @left.is_a? Gloo::Core::Literal
         return @left.value if @left.is_a? Gloo::Expr::Call
@@ -66,11 +70,39 @@ module Gloo
         @op ||= Gloo::Core::Op.default_op
         l = evaluate_sym @left
         r = evaluate_sym @right
-        @left = @op.perform l, r
+        @left = apply_op( @op, l, r )
         @right = nil
         @op = nil
       end
 
+      #
+      # Apply the operator. An operator that can't be used with the value
+      # (eg. 'a' / 2), or a division by zero, is a runtime error, and the
+      # result is no value. A missing value (nil) was already reported.
+      #
+      def apply_op( op, left, right )
+        result = op.perform( left, right )
+        if op.is_a?( Gloo::Expr::OpDiv ) && result.is_a?( Float ) &&
+           ( result.nan? || result.infinite? )
+          raise ZeroDivisionError
+        end
+        return result unless result.nil? && !left.nil?
+
+        @engine.err "Operator '#{op.class::SYMBOL}' can't be used with '#{left}'."
+        return nil
+      rescue ZeroDivisionError
+        @engine.err DIVIDE_BY_ZERO_ERR
+        return nil
+      end
+
+      #
+      # An operator without a value on one side (eg. 'show 1 +') is a
+      # syntax error; the best guess is to leave the operator out.
+      #
+      def missing_value( op )
+        @engine.syntax_err "Operator '#{op.class::SYMBOL}' is missing a value."
+      end
+
       #
       # Evaluate the symbol and get a simple value.
       #
@@ -88,8 +120,14 @@ module Gloo
       def resolve_ref( ref )
         return ref.src if ref.named_color?
 
+        name = ref.src
         ob = ref.resolve
         return ob.value if ob
+
+        # The object is being used as a value, so a missing object is
+        # a runtime error (the lookup itself doesn't report it).
+        @engine.err Gloo::Core::NotFound.object( name )
+        return nil
       end
 
       #

data/lib/gloo/expr/op_plus.rb

@@ -9,6 +9,9 @@ module Gloo
     class OpPlus < Gloo::Core::Op
 
       SYMBOL = '+'.freeze
+      # An alternate spelling that reads better when joining strings:
+      # put first and ' ' and last into full_name
+      ALT_SYMBOL = 'and'.freeze
 
       #
       # Perform the operation and return the result.

data/lib/gloo/objs/basic/boolean.rb

@@ -12,6 +12,7 @@ module Gloo
       KEYWORD_SHORT = 'bool'.freeze
       TRUE = 'true'.freeze
       FALSE = 'false'.freeze
+      BOOLEAN_STRINGS = [ TRUE, FALSE, 't', 'f' ].freeze
 
       #
       # The name of the object type.
@@ -32,6 +33,20 @@ module Gloo
       #
       def set_value( new_value )
         self.value = Gloo::Objs::Boolean.coerse_to_bool( new_value )
+        return unless Gloo::Objs::Boolean.bad_value?( new_value )
+
+        @engine.warn "'#{new_value}' is not true or false; using #{self.value}."
+      end
+
+      #
+      # Is the value a string that isn't a boolean? A blank value is
+      # no value (false).
+      #
+      def self.bad_value?( new_value )
+        return false unless new_value.is_a?( ::String )
+        return false if new_value.strip.empty?
+
+        return !BOOLEAN_STRINGS.include?( new_value.strip.downcase )
       end
 
       #
@@ -132,6 +147,7 @@ module Gloo
             'true — Set the boolean to true.',
             'false — Set the boolean to false.'
           ],
+          :notes => 'Recognized values are true, false, t and f (in any case), and integers (0 is false). Any other string is false, with a warning: "\'maybe\' is not true or false; using false." A blank value is false.',
           :examples => <<~EXAMPLES.strip
             b [can] :
               flag [boolean] : true

data/lib/gloo/objs/basic/container.rb

@@ -10,6 +10,8 @@ module Gloo
 
       KEYWORD = 'container'.freeze
       KEYWORD_SHORT = 'can'.freeze
+      MISSING_INDEX_MSG = 'Missing index!'.freeze
+      MISSING_NAME_MSG = 'Missing child name!'.freeze
 
       #
       # The name of the object type.
@@ -33,7 +35,8 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return super + %w[count delete_children child_exists show_key_value_table]
+        return super + %w[count delete_children child_exists show_key_value_table
+                          child_value_at child_path_at random_child_value random_child_path]
       end
 
       #
@@ -65,17 +68,138 @@ module Gloo
       # Check to see if there is a child with the given name.
       # 
       def msg_child_exists
-        if @params&.token_count&.positive?
-          expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
-          data = expr.evaluate
+        unless @params&.token_count&.positive?
+          @engine.syntax_err MISSING_NAME_MSG
+          return put_it( false )
         end
-        return unless data
+
+        expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
+        data = expr.evaluate
+        return put_it( false ) if data.nil?
 
         val = self.contains_child?( data )
         @engine.heap.it.set_to val
         return val
       end
 
+      #
+      # Get the value of the child at the given 0-based index.
+      #
+      def msg_child_value_at
+        child = child_at_param
+        return child if child == false
+
+        return put_child_value( child )
+      end
+
+      #
+      # Get the path of the child at the given 0-based index.
+      #
+      def msg_child_path_at
+        child = child_at_param
+        return child if child == false
+
+        return put_it( child.pn )
+      end
+
+      #
+      # Get the value of a random child.
+      #
+      def msg_random_child_value
+        child = random_child
+        return child if child == false
+
+        return put_child_value( child )
+      end
+
+      #
+      # Get the path of a random child.
+      #
+      def msg_random_child_path
+        child = random_child
+        return child if child == false
+
+        return put_it( child.pn )
+      end
+
+      # ---------------------------------------------------------------------
+      #    Child Access Helpers
+      # ---------------------------------------------------------------------
+
+      #
+      # Find the child at the index given as the message parameter.
+      # Reports the problem, puts false into it, and returns false
+      # if there is no index or no child at that index.
+      #
+      def child_at_param
+        unless @params&.token_count&.positive?
+          @engine.syntax_err MISSING_INDEX_MSG
+          return put_it( false )
+        end
+
+        expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
+        data = expr.evaluate
+        index = Container.to_index( data )
+        if index.nil?
+          @engine.err "Index '#{data}' is not a number!"
+          return put_it( false )
+        end
+
+        if index.negative? || index >= child_count
+          @engine.err "Index #{index} is out of range (0 to #{child_count - 1})!"
+          return put_it( false )
+        end
+
+        return children[ index ]
+      end
+
+      #
+      # Get a whole number index from an evaluated parameter.
+      # Returns nil if it isn't one.
+      #
+      def self.to_index( data )
+        return data if data.is_a?( ::Integer )
+        return data.strip.to_i if data.is_a?( ::String ) && data.strip.match?( /\A-?\d+\z/ )
+
+        return nil
+      end
+
+      #
+      # Pick a random child.
+      # Reports the problem, puts false into it, and returns false
+      # if the container is empty.
+      #
+      def random_child
+        if child_count.zero?
+          @engine.err "Container '#{pn}' is empty!"
+          return put_it( false )
+        end
+
+        return children.sample
+      end
+
+      #
+      # Put the value of the child into it.
+      # A container child has no value of its own; use its path instead.
+      #
+      def put_child_value( child )
+        child = Gloo::Objs::Alias.resolve_alias( @engine, child )
+        if child.is_container?
+          @engine.err "Child '#{child.pn}' is a container, not a value! Use its path instead."
+          return put_it( false )
+        end
+
+        return put_it( child.value )
+      end
+
+      #
+      # Put the value into it and return it.
+      #
+      def put_it( val )
+        @engine.heap.it.set_to val
+        return val
+      end
+
       # ---------------------------------------------------------------------
       #    Object Documentation
       # ---------------------------------------------------------------------
@@ -99,8 +223,17 @@ module Gloo
             'count — Count the number of children objects in the container. The result is put in it.',
             'delete_children — Delete all children objects from the container.',
             'show_key_value_table — Show a table with key (name) and values for all children in the container.',
-            'child_exists ({name}) — Check to see if there is a child with the given name. A parameter is required. It will have a boolean.'
+            'child_exists ({name}) — Check to see if there is a child with the given name. A parameter is required. It will have a boolean.',
+            'child_value_at ({index}) — Get the value of the child at position {index}. Positions are 0-based and in the order the children were added, so after split_list, index 0 is the child named 1. A parameter is required. It will have the value; an out-of-range or non-numeric index, or a child that is a container, is an error, and it will have false.',
+            'child_path_at ({index}) — Get the path (from root) of the child at position {index}, 0-based. Works for any child, including a container; put it into an alias (put it into ptr*) to reach the child and its fields. A parameter is required. It will have the path; an out-of-range or non-numeric index is an error, and it will have false.',
+            'random_child_value — Get the value of a randomly chosen child. It will have the value; an empty container, or picking a child that is a container, is an error, and it will have false.',
+            'random_child_path — Get the path (from root) of a randomly chosen child. It will have the path; an empty container is an error, and it will have false.'
           ],
+          :notes => 'The random_child messages pick with replacement: two ' \
+            'calls can pick the same child. For distinct picks, pick a ' \
+            'random index with an integer\'s randomize message, keep the ' \
+            'indexes already used as children of another container, and ' \
+            'check it with child_exists before using child_path_at.',
           :examples => <<~EXAMPLES.strip
             can [can] :
               data [can] :
@@ -109,6 +242,21 @@ module Gloo
                 3 : three
               on_load [script] :
                 tell can.data to show_key_value_table
+
+            #
+            # Reach a container child's fields through an alias.
+            #
+            books [can] :
+              list [can] :
+                a [can] :
+                  title [string] : Walden
+                b [can] :
+                  title [string] : Emma
+              ptr [alias] :
+              on_load [script] :
+                tell books.list to child_path_at (1)
+                put it into books.ptr*
+                show books.ptr.title
           EXAMPLES
         }
       end

data/lib/gloo/objs/basic/decimal.rb

@@ -109,6 +109,7 @@ module Gloo
               'an optional parameter is included, round to the precision specified.',
             'format ({fmt}) — With no parameter, adds comma separators to the whole part (e.g. 1000.5 -> 1,000.5). With a parameter, uses it as a sprintf-style format string (e.g. \'%.2f\'). It will have the formatted string.'
           ],
+          :notes => 'A value that isn\'t a number (eg. \'x\' or \'1,5\') is used as a best guess, with a warning: "\'1,5\' is not a decimal number; using 1.0." A blank value is 0.0.',
           :examples => <<~EXAMPLES.strip
             d [can] :
               x [decimal] : 100

data/lib/gloo/objs/basic/integer.rb

@@ -140,6 +140,7 @@ module Gloo
               'range to 6 and add 1 to the result.',
             'format ({fmt}) — With no parameter, adds comma separators (e.g. 1000 -> 1,000). With a parameter, uses it as a sprintf-style format string (e.g. \'%05d\'). It will have the formatted string.'
           ],
+          :notes => 'A value that isn\'t a whole number (eg. \'x\', \'12abc\' or \'3.7\') is used as a best guess, with a warning: "\'x\' is not an integer; using 0." A blank value is 0.',
           :examples => <<~EXAMPLES.strip
             #
             # Integer object.

data/lib/gloo/objs/basic/string.rb

@@ -13,7 +13,6 @@ module Gloo
 
       KEYWORD = 'string'.freeze
       KEYWORD_SHORT = 'str'.freeze
-      MISSING_PARAM_MSG = 'Missing parameter!'.freeze
 
       #
       # The name of the object type.