gloo 6.7.1 → 7.0

data/lib/gloo/core/pn.rb

@@ -14,6 +14,8 @@ module Gloo
       ERROR = 'error'.freeze
       CONTEXT = '@'.freeze
       NAMED_COLORS = %w[red blue green white black yellow].freeze
+      IT_NOT_AN_OBJECT = "it isn't an object and can't be %s; %s.".freeze
+      IT_HINT = 'put it into an object first (put it into x)'.freeze
 
       attr_reader :src, :elements
 
@@ -61,6 +63,19 @@ module Gloo
         return @src.downcase == IT
       end
 
+      #
+      # it is a read-only result value, not an object, so it can't
+      # be the target of a verb or message. If the path refers to it,
+      # report that (what it can't be: 'sent messages', 'run', ...,
+      # and what to do instead) and return true.
+      #
+      def it_target_err?( what, hint = IT_HINT )
+        return false unless self.it?
+
+        @engine.err format( IT_NOT_AN_OBJECT, what, hint )
+        return true
+      end
+
       #
       # Does the pathname reference refer to error?
       #
@@ -141,19 +156,29 @@ module Gloo
         self.set_to( "#{@engine.heap.context}#{@src[1..-1]}" )
       end
 
+      #
+      # Expand any here (^) or context (@) reference into the
+      # full path, so the lookup below starts from the heap root.
+      #
+      def expand_refs
+        Here.expand_here( @engine, self ) if Here.includes_here_ref?( @elements )
+        expand_context if self.includes_context?
+      end
+
       #
       # Get the parent that contains the object referenced.
       #
+      # This is a lookup, not a use of the object: a missing element
+      # returns nil without reporting an error. A caller that needs the
+      # object reports its own error.
+      #
       def get_parent
         o = @engine.heap.root
 
         if self.includes_path?
           @elements[ 0..-2 ].each do |e|
             o = o.find_child( e )
-            if o.nil?
-              @engine.err "Object '#{e}' was not found."
-              return nil
-            end
+            return nil if o.nil?
           end
         end
 
@@ -162,12 +187,14 @@ module Gloo
 
       #
       # Does the object at the path exist?
+      # A question, so a missing object is an answer, not an error.
       #
       def exists?
         return true if self.root?
         return true if self.it?
         return true if self.error?
 
+        expand_refs
         parent = self.get_parent
         return false unless parent
 
@@ -186,6 +213,7 @@ module Gloo
       #
       # Resolve the pathname reference.
       # Find the object referenced or return nil if it is not found.
+      # Like get_parent, a missing object is not reported here.
       #
       def resolve
         return @engine.heap.root if self.root?
@@ -194,14 +222,7 @@ module Gloo
         return Gloo::Core::GlooSystem.new(
           @engine, self ) if self.gloo_sys?
 
-        if Here.includes_here_ref?( @elements )
-          Here.expand_here( @engine, self )
-        end
-
-        if self.includes_context?
-          expand_context
-        end
-
+        expand_refs
         parent = self.get_parent
         return nil unless parent
 

data/lib/gloo/core/tokens.rb

@@ -18,6 +18,10 @@ module Gloo
 
       QUOTE_CHARS = [ '"', "'" ].freeze
 
+      UNCLOSED_QUOTE_ERR = 'Unclosed quote.'.freeze
+      UNCLOSED_PAREN_ERR = 'Unclosed parenthesis.'.freeze
+      UNMATCHED_PAREN_ERR = "Unmatched ')'.".freeze
+
       attr_reader :cmd, :tokens
 
       # ---------------------------------------------------------------------
@@ -38,6 +42,40 @@ module Gloo
       #    Public functions
       # ---------------------------------------------------------------------
 
+      #
+      # A syntax problem in the command (an unclosed quote, or
+      # parentheses that don't match), or nil. The tokens are still
+      # the best guess: an unclosed quote runs to the end of the line.
+      # Quotes are read the same way tokenize reads them.
+      #
+      def syntax_problem
+        quote = nil
+        depth = 0
+        escaped = false
+        @cmd.each_char do |ch|
+          if quote
+            if escaped
+              escaped = false
+            elsif ch == '\\'
+              escaped = true
+            elsif ch == quote
+              quote = nil
+            end
+          elsif QUOTE_CHARS.include?( ch )
+            quote = ch
+          elsif ch == '('
+            depth += 1
+          elsif ch == ')'
+            depth -= 1
+            return UNMATCHED_PAREN_ERR if depth.negative?
+          end
+        end
+        return UNCLOSED_QUOTE_ERR if quote
+        return UNCLOSED_PAREN_ERR if depth.positive?
+
+        return nil
+      end
+
       #
       # Get the number of tokens
       #

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.