gloo 6.0.1 → 6.2.0

data/lib/gloo/expr/expression.rb

@@ -47,6 +47,7 @@ module Gloo
         end
 
         return @left.value if @left.is_a? Gloo::Core::Literal
+        return @left.value if @left.is_a? Gloo::Expr::Call
         return resolve_ref @left if @left.is_a? Gloo::Core::Pn
 
         return @left
@@ -75,6 +76,7 @@ module Gloo
       #
       def evaluate_sym( sym )
         return sym.value if sym.is_a? Gloo::Core::Literal
+        return sym.value if sym.is_a? Gloo::Expr::Call
         return resolve_ref sym if sym.is_a? Gloo::Core::Pn
 
         return sym
@@ -109,6 +111,7 @@ module Gloo
         return LInteger.new( token ) if LInteger.integer?( token )
         return LString.new( token ) if LString.string?( token )
         return LDecimal.new( token ) if LDecimal.decimal?( token )
+        return Gloo::Expr::Call.new( @engine, token ) if Gloo::Expr::Call.call?( token )
 
         # last chance: an Object reference
         return Gloo::Core::Pn.new( @engine, token )

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

@@ -73,6 +73,59 @@ module Gloo
         return ln.resolve
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A pointer to another object. Normal ' \
+            'path-name references will refer to the aliased object. To ' \
+            'refer to the alias itself, add an * at the end of the ' \
+            'path-name — needed, for example, to set the value of the ' \
+            'alias. The value of the alias is merely the path-name of ' \
+            'the referenced object. Well constructed aliases will ' \
+            'redirect to the referenced object through any number of ' \
+            'steps, and relative references will also work in an alias.',
+          :messages => [
+            'resolve — Check to see if the object referenced exists. Sets it to true or false.'
+          ],
+          :notes => 'The alias also reflects (forwards) the messages of the object it points to.',
+          :examples => <<~EXAMPLES.strip
+            #
+            # Alias object.
+            #
+
+            a [can] :
+              s [string] : a string
+              i [integer] : 13
+              ln [alias] : a.s
+
+              on_load [script] :
+                show a.ln
+                show a.ln*
+                put 'a.i' into a.ln*
+                put 7 into a.ln
+                show a.ln
+                run a.add
+
+              #
+              # Example of creating an object using an alias.
+              #
+              add [script] :
+                put 'x' into a.ln*
+                create a.ln* as string
+                put 'test' into x
+                show a.ln
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -115,6 +115,36 @@ module Gloo
         return false
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A boolean value. Value will be either true or false.',
+          :messages => [
+            'not — Set the boolean to the opposite of what it is now.',
+            'true — Set the boolean to true.',
+            'false — Set the boolean to false.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            b [can] :
+              flag [boolean] : true
+              on_load [script] :
+                show b.flag
+                put false into b.flag
+                show b.flag
+                tell b.flag to not
+                show b.flag
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -75,6 +75,44 @@ module Gloo
         @engine.heap.it.set_to val
         return val
       end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A container of other objects. A container is ' \
+            'similar to a folder in a file system. It can contain any ' \
+            'number of objects including other containers. The ' \
+            'container structure provides direct access to any object ' \
+            'within it through the object.object.object path-name structure.',
+          :children => [
+            'None by default — but any container can have any number of objects added to it, at runtime.'
+          ],
+          :messages => [
+            '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.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            can [can] :
+              data [can] :
+                1 : one
+                2 : two
+                3 : three
+              on_load [script] :
+                tell can.data to show_key_value_table
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -92,6 +92,36 @@ module Gloo
         @engine.heap.it.set_to formatted
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A decimal (numeric) value.',
+          :messages => [
+            'round ({precision}) — Round to the nearest whole value. If ' \
+              '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.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            d [can] :
+              x [decimal] : 100
+              on_load [script] :
+                show d.x
+                put d.x / 3 into d.x
+                show d.x
+                tell d.x to round (1)
+                show d.x
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -118,6 +118,64 @@ module Gloo
         @engine.heap.it.set_to formatted
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'An integer (numeric) value.',
+          :messages => [
+            'inc — Increment the integer value by 1.',
+            'dec — Decrement the integer value by 1.',
+            'randomize ({max}) — Set the value of the integer to a random ' \
+              'number. By default the range is 0..99 inclusive. Use an ' \
+              'optional parameter to set the maximum of the range; the ' \
+              'range always starts at 0. To model a 6-sided die, set the ' \
+              '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.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Integer object.
+            #
+
+            i [can] :
+
+              #
+              # The integer value.
+              #
+              x [integer] : 0
+
+              #
+              # Do some basic tests with it
+              #
+              on_load [script] :
+                show i.x
+                tell i.x to inc
+                show i.x
+                put i.x * 10 into i.x
+                show i.x
+
+                # Show a random number
+                tell ^.x to randomize
+                show 'Random number (up to 100 by default): ' + ^.x
+
+                tell ^.x to randomize(6)
+                tell ^.x to inc
+                show '6-sided dice: ' + ^.x
+
+              # An uninitialized integer.
+              y [integer] :
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -94,6 +94,37 @@ module Gloo
         s.run
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'An executable script — a set of commands to be run.',
+          :messages => [
+            'run — Run the script. The script can be run by telling the ' \
+              'object to run, or via the run verb.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            script [can] :
+              on_load [script] :
+                show "Showing multiple lines..."
+                show script.msg1
+                show script.msg2
+                show script.msg3
+                show "Done."
+              msg1 [string] : one
+              msg2 [string] : two
+              msg3 [string] : three
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

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

@@ -44,10 +44,37 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return super + %w[up down size starts_with? ends_with? substring? sub gsub
-          count_lines count_words count_chars trim
-          format_for_html encode64 decode64 escape unescape
-          gen_alphanumeric gen_uuid gen_hex gen_base64]
+        return super + StringMsgs.messages
+      end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A string value. For string interpolation, ' \
+            'see the erb object type. Shares the same messages as the ' \
+            'text object type; the two differ mainly by convention — ' \
+            'string for a single word or line, text for longer, ' \
+            'multi-line blocks.',
+          :messages => StringMsgs.message_docs,
+          :examples => <<~EXAMPLES.strip
+            s [can] :
+              msg [string] : Hello World!
+              on_load [script] :
+                show s.msg
+                tell s.msg to up
+                show s.msg
+                tell s.msg to size
+                show it
+          EXAMPLES
+        }
       end
 
     end

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

@@ -10,8 +10,57 @@ module Gloo
   module Objs
     module StringMsgs
 
+      #
+      # Get the list of message names this mixin implements, derived
+      # from its own msg_* methods so String/Text don't have to
+      # hand-duplicate the list (and can't drift out of sync with it).
+      #
+      def self.messages
+        return instance_methods( false )
+          .select { |m| m.to_s.start_with?( 'msg_' ) }
+          .map { |m| m.to_s.sub( /\Amsg_/, '' ) }
+      end
 
-      # 
+      #
+      # Documentation for each message this mixin implements, for use
+      # in String and Text's doc_data (see help_shell). Kept here as
+      # the single source, since String and Text share the exact
+      # same message set and would otherwise have to keep two
+      # hand-written copies of this list in sync.
+      #
+      def self.message_docs
+        return [
+          'up — Convert the string to uppercase. This message changes the value of the string.',
+          'down — Convert the string to lowercase. This message changes the value of the string.',
+          'size — Get the size of the string. It will have the string size.',
+          'count_chars — Count the number of characters in the string. It will have the character count.',
+          'count_words — Count the number of words in the string. It will have the word count.',
+          'count_lines — Count the number of lines in the string. It will have the line count.',
+          'starts_with? ({str}) — Check if the string starts with the given string. A parameter is required: the string to look for at the beginning of this string. It will have a boolean.',
+          'ends_with? ({str}) — Check if the string ends with the given string. A parameter is required: the string to look for at the end of this string. It will have a boolean.',
+          'substring? ({str}) — Check if the string includes the given sub-string. A parameter is required: the string to look for in this string. It will have a boolean.',
+          'format_for_html — Format this string for HTML output. Tabs, spaces and returns are converted to HTML elements. The value of the string is changed.',
+          'encode64 — Base64 encode the string. This message changes the value of the string. It will have the encoded string.',
+          'decode64 — Decode the string from Base64. This message changes the value of the string. It will have the decoded string.',
+          'escape — Escape the string to make it URL safe. This message changes the value of the string. It will have the escaped string.',
+          'unescape — Unescape the string (from URL safe format). This message changes the value of the string. It will have the unescaped string.',
+          'gen_uuid — Set the value of the string to a newly generated, random UUID. This message changes the value of the string.',
+          'gen_alphanumeric ({len}) — Set the value of the string to a newly generated, random alphanumeric string. The {len} parameter is optional; the length is 10 if not specified. This message changes the value of the string.',
+          'gen_hex ({len}) — Set the value of the string to a newly generated, random hex string. The {len} parameter is optional; the length is 10 if not specified. This message changes the value of the string.',
+          'gen_base64 ({len}) — Set the value of the string to a newly generated, random base64 string. The {len} parameter is optional; the length is 12 if not specified. This message changes the value of the string.',
+          'trim — Strip whitespace from the beginning and end of the string. This message changes the value of the string. It will have the trimmed string.',
+          'sub ({from} {to}) — Substitute the first occurrence of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
+          'gsub ({from} {to}) — Substitute all occurrences of {from} with {to}. Both parameters are required. This message changes the value of the string. It will have the result.',
+          'split ({from} {to}) — Get the substring from index {from} up to (not including) index {to}. Indexes are 0-based; out-of-range indexes are clamped to the start or end of the string. Both parameters are required. Does not change the value of the string. It will have the substring.',
+          'splitl ({index}) — Get the substring to the left of index {index} (same as split (0, {index})). A parameter is required. Does not change the value of the string. It will have the substring.',
+          'splitr ({index}) — Get the substring from index {index} to the end of the string (same as split ({index}, size)). A parameter is required. Does not change the value of the string. It will have the substring.',
+          'split_list ({delim} {dst.path}) — Split the string by {delim} and put the parts into children of the container at {dst.path} (or an alias that points to one), one part per child, in order. Existing children are matched by position and have their values set; extra parts get new (untyped) children, numbered from 1; extra existing children are left alone. Both parameters are required. Does not change the value of the string. It will have the number of parts.',
+          'page — Show the value in a pager (less), for viewing long content a screen at a time.'
+        ]
+      end
+
+
+      #
       # Strip whitespace from the beginning and end of the string.
       #
       def msg_trim
@@ -109,7 +158,115 @@ module Gloo
         end
       end
 
-      # 
+      #
+      # Get the substring from index {from} up to (not including) index {to}.
+      # Indexes are 0-based. Out-of-range indexes are clamped to the
+      # beginning or end of the string. Does not change the string's value.
+      #
+      def msg_split
+        return '' unless value
+
+        if @params&.token_count&.positive?
+          expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
+          from = expr.evaluate.to_i
+          expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.last ] )
+          to = expr.evaluate.to_i
+
+          result = clamped_substring( from, to )
+          @engine.heap.it.set_to result
+          return result
+        else
+          # Error
+          @engine.log.error MISSING_PARAM_MSG
+          @engine.heap.it.set_to false
+          return false
+        end
+      end
+
+      #
+      # Get the substring to the left of (not including) index {index}.
+      # Same as split( 0, index ). Does not change the string's value.
+      #
+      def msg_splitl
+        return '' unless value
+
+        if @params&.token_count&.positive?
+          expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
+          index = expr.evaluate.to_i
+
+          result = clamped_substring( 0, index )
+          @engine.heap.it.set_to result
+          return result
+        else
+          # Error
+          @engine.log.error MISSING_PARAM_MSG
+          @engine.heap.it.set_to false
+          return false
+        end
+      end
+
+      #
+      # Get the substring from index {index} to the end of the string.
+      # Same as split( index, size ). Does not change the string's value.
+      #
+      def msg_splitr
+        return '' unless value
+
+        if @params&.token_count&.positive?
+          expr = Gloo::Expr::Expression.new( @engine, @params.tokens )
+          index = expr.evaluate.to_i
+
+          result = clamped_substring( index, value.length )
+          @engine.heap.it.set_to result
+          return result
+        else
+          # Error
+          @engine.log.error MISSING_PARAM_MSG
+          @engine.heap.it.set_to false
+          return false
+        end
+      end
+
+      #
+      # Split the string by the given delimiter and put the parts into
+      # children of the target container, one part per child, in order.
+      # The target is a path to a container, or to an alias that points
+      # to one. Existing children are matched by position (not name) and
+      # have their values set; if there are more parts than children,
+      # new (untyped) children are created for the extras, numbered
+      # from 1. Existing children beyond the part count are left alone.
+      # The string's own value is unchanged; the number of parts is put
+      # into 'it'.
+      #
+      def msg_split_list
+        return unless value
+
+        if @params&.token_count.to_i < 2
+          @engine.log.error MISSING_PARAM_MSG
+          @engine.heap.it.set_to false
+          return false
+        end
+
+        expr = Gloo::Expr::Expression.new( @engine, [ @params.tokens.first ] )
+        delim = expr.evaluate
+
+        target = split_list_target( @params.tokens.last )
+        return false unless target
+
+        parts = value.split( delim )
+        existing = target.children
+        parts.each_with_index do |part, index|
+          child = existing[ index ]
+          child ||= target.find_add_child( ( index + 1 ).to_s, 'untyped' )
+          child.set_value part
+        end
+
+        count = parts.count
+        @engine.heap.it.set_to count
+        return count
+      end
+
+      #
       # Does the string contain the given string?
       #
       # This was formerly an overload of obj.contains?
@@ -324,6 +481,59 @@ module Gloo
         return s
       end
 
+      #
+      # Show the value in a pager, for long content.
+      #
+      def msg_page
+        return unless value
+
+        @engine.platform.page( value )
+      end
+
+      private
+
+      #
+      # Resolve the target container path for split_list. The path may
+      # point directly at a container, or at an alias that points to
+      # one. Returns nil (and logs an error, setting 'it' to false)
+      # if the path doesn't exist or doesn't resolve to a container.
+      #
+      def split_list_target( token )
+        pn = Gloo::Core::Pn.new( @engine, token )
+        unless pn&.exists?
+          @engine.log.error 'Target container path does not exist!'
+          @engine.heap.it.set_to false
+          return nil
+        end
+
+        target = pn.resolve
+        target = Gloo::Objs::Alias.resolve_alias( @engine, target )
+        unless target&.is_container?
+          @engine.log.error 'Target for split_list must be a container!'
+          @engine.heap.it.set_to false
+          return nil
+        end
+
+        return target
+      end
+
+      #
+      # Get the substring from index {from} up to (not including) index {to}.
+      # Out-of-range indexes are clamped to the string's own bounds (0 and
+      # its length), rather than raising an error. A degenerate range
+      # (from at or past to) returns an empty string.
+      #
+      def clamped_substring( from, to )
+        len = value.length
+        from = 0 if from.negative?
+        from = len if from > len
+        to = 0 if to.negative?
+        to = len if to > len
+        return '' if from >= to
+
+        return value[ from...to ]
+      end
+
     end
   end
 end

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

@@ -58,10 +58,36 @@ module Gloo
       # Get a list of message names that this object receives.
       #
       def self.messages
-        return super + %w[up down size starts_with? ends_with? substring? sub gsub
-          count_lines count_words count_chars trim
-          format_for_html encode64 decode64 escape unescape
-          gen_alphanumeric gen_uuid gen_hex gen_base64]
+        return super + StringMsgs.messages
+      end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A longer, multi-line text string. Use BEGIN ' \
+            'and END to mark the text range. Shares the same messages ' \
+            'as the string object type; the two differ mainly by ' \
+            'convention — text for longer, multi-line blocks, string ' \
+            'for a single word or line.',
+          :messages => StringMsgs.message_docs,
+          :examples => <<~EXAMPLES.strip
+            t [container] :
+              msg [txt] : BEGIN
+                I will now write a poem
+                of two lines or less
+                END
+              on_load [script] :
+                show t.msg
+          EXAMPLES
+        }
       end
 
     end

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

@@ -36,6 +36,27 @@ module Gloo
         return super
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'An untyped object. If no type is specified ' \
+            'when an object is created it will be of this type.',
+          :examples => <<~EXAMPLES.strip
+            > create x
+            > put 1 into x
+            > put 'string' into x
+          EXAMPLES
+        }
+      end
+
     end
   end
 end