gloo 6.0 → 6.1.0

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

@@ -10,6 +10,17 @@ 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
+
 
       # 
       # Strip whitespace from the beginning and end of the string.
@@ -324,6 +335,15 @@ 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
+
     end
   end
 end

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

@@ -58,10 +58,57 @@ 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.',
+          :messages => [
+            'Same messages as the string object type:',
+            '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.',
+            'page — Show the value in a pager (less), for viewing long content a screen at a time.'
+          ],
+          :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

data/lib/gloo/objs/ctrl/each.rb

@@ -104,11 +104,73 @@ module Gloo
           EachDir.new( @engine, self ).run
         # elsif EachRepo.use_for?( self )
         #   EachRepo.new( @engine, self ).run
-        else 
+        else
           @engine.err "Not set up to run each for that target."
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Perform an action for each item in a ' \
+            'collection. There are several variations on this object ' \
+            'type, determined by which named child is present: each ' \
+            'child object in a container, each word in a string, each ' \
+            'line in a block of text, each file in a folder, or each ' \
+            'directory in a folder.',
+          :children => [
+            'in — The collection or source to iterate over (a container, string, or folder path, depending on variation).',
+            'do (script) — The action to perform for each item in the loop.',
+            'One of the following, whose presence determines which kind of loop this is:',
+            'child (alias) — iterate a container\'s children.',
+            'word (string) — iterate the words in a string.',
+            'line (string) — iterate the lines in a block of text.',
+            'file (file) — iterate the files in a folder; an optional ext (string) child limits to files of that extension.',
+            'dir (file) — iterate the directories in a folder.'
+          ],
+          :messages => [
+            'run — Run the loop for each item in the collection.'
+          ],
+          :notes => 'When iterating a container\'s children, an ' \
+            'optional group_by feature is available: add a group_by ' \
+            '(string) child naming a property of each child, plus ' \
+            'on_group_start / on_group_end (script) children — those ' \
+            'scripts run whenever the group_by value changes, letting ' \
+            'you aggregate results in groups.',
+          :examples => <<~EXAMPLES.strip
+            #
+            # Show each child in a container.
+            #
+            each_child [can] :
+
+            # Iterator on children of a container.
+              for [each] :
+                child [alias] :
+                in [alias] : each_child.objs
+                do [script] : show ^.child
+
+              # Data
+              objs [can] :
+                1 [string] : one
+                2 [string] : two
+                3 [string] : three
+
+              # Run the iterator.
+              on_load [script] :
+                show 'showing children in container' (white)
+                tell each_child.for to run
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/ctrl/function.rb

@@ -194,6 +194,75 @@ module Gloo
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Define a function that will be performed ' \
+            'somewhere else. When the function is invoked, the ' \
+            'parameter values are set, the on_invoke script is run, the ' \
+            'result is determined, the after_invoke script is run, and ' \
+            'the result is returned.',
+          :children => [
+            'on_invoke (script) — Script to run when the function is invoked.',
+            'after_invoke (optional script) — Script to run after the function has been invoked and before the value is returned. Can be used to clean up and reset the object state.',
+            'params (container) — The collection of parameters to the function. Parameter values are used as defaults if no value is passed in during invocation.',
+            'result (string) — The result of the function to return to the caller.'
+          ],
+          :messages => [
+            'invoke — Invoke the function, set it and return the result. The function result is put into it as well as being returned to the caller.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Function examples
+            #
+
+            functions [can] :
+
+              name [string] : Jasper
+
+              on_load [script] :
+                show 'running function examples' (white)
+
+                invoke functions.greet ^.name
+                show it
+
+                invoke functions.add 3 4
+                show it
+
+                show 'done' (white)
+
+              #
+              # Say hi to person (name)
+              #
+              greet [ƒ] :
+                on_invoke [script] :
+                  put 'Hi, ' + ^.params.name into ^.result
+                params [container] :
+                  name [string] : none
+                result [string] :
+
+              #
+              # Add 2 numbers
+              #
+              add [ƒ] :
+                on_invoke [script] :
+                  put ^.params.x and ^.params.y into ^.result
+                params [container] :
+                  x [int] :
+                  y [int] :
+                result [string] :
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/ctrl/repeat.rb

@@ -102,6 +102,47 @@ module Gloo
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Run a script a given number of times.',
+          :children => [
+            'times (integer) — Default: 0. The number of times to run the script.',
+            'index (integer) — Default: 0. The current iteration when the repeat loop is running.',
+            'do (script) — The action to perform for each iteration of the loop.'
+          ],
+          :messages => [
+            'run — Run the script for the given number of times.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            repeat [can] :
+              s [string] :
+              on_load [script] :
+                put $.screen_cols / 2 into repeat.x.times
+                tell repeat.x to run
+                show repeat.s
+                tell repeat.y to run
+                show repeat.s
+              x [repeat] :
+                times [integer] : 30
+                index [integer] : 0
+                do [script] : put repeat.s + '-' into repeat.s
+              y [repeat] :
+                times [integer] : 10
+                index [integer] : 0
+                do [script] : show repeat.y.index
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/dt/date.rb

@@ -149,6 +149,49 @@ module Gloo
         dt = Chronic.parse( self.value )
         @engine.heap.it.set_to dt.strftime( format )
       end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A reference to a date, but without time. The ' \
+            "default format is: #{DEFAULT_FORMAT}. Note that you can " \
+            'put a date into a datetime object. You can also put a ' \
+            'Chronic phrase into the date.',
+          :messages => [
+            'now — Set to the current system date.',
+            'add ({amount}) — Add the amount to the date. The amount will be in the form of "1 day" or "3 months".',
+            'sub ({amount}) — Subtract the amount from the date. The amount will be in the form of "1 day" or "2 weeks".',
+            'dd — Get the day portion of the date. Put the day number into it.',
+            'mm — Get the month portion of the date. Put the month number into it.',
+            'yy — Get the 2 digit year portion of the date. Put the 2 digit year into it.',
+            'yyyy — Get the 4 digit year portion of the date. Put the 4 digit year into it.',
+            'format ({fmt}) — Format the date using a strftime-style format string. Default if none given: %Y-%m-%d. It will have the formatted string.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Show the current date.
+            #
+
+            date [can] :
+              d [date] :
+              on_load [script] :
+                tell date.d to now
+                show date.d
+              next [script] :
+                put 'tomorrow' into date.d
+                show date.d
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/dt/datetime.rb

@@ -249,6 +249,56 @@ module Gloo
         @engine.heap.it.set_to dt.strftime( format )
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A reference to a date and time. The default ' \
+            "format is: #{DEFAULT_FORMAT}. Note that you can put a " \
+            'datetime into a date or time object. You can also put a ' \
+            'Chronic phrase into the datetime.',
+          :messages => [
+            'now — Set to the current system date and time.',
+            'add ({amount}) — Add the amount to the date. The amount will be in the form of "1 day" or "3 hours".',
+            'sub ({amount}) — Subtract the amount from the date. The amount will be in the form of "1 day" or "2 weeks".',
+            'is_today — Is the datetime today? It will be true or false.',
+            'is_past — Is the datetime in the past? It will be true or false.',
+            'is_future — Is the datetime in the future? It will be true or false.',
+            'is_yesterday — Is the datetime yesterday? It will be true or false.',
+            'is_tomorrow — Is the datetime tomorrow? It will be true or false.',
+            'is_this_week — Is the datetime during this week? It will be true or false.',
+            'begin_day — Set the datetime to the start of the day.',
+            'end_day — Set the datetime to the end of the day.',
+            'begin_week — Set the datetime to the start of the week.',
+            'end_week — Set the datetime to the end of the week.',
+            'begin_month — Set the datetime to the start of the month.',
+            'end_month — Set the datetime to the end of the month.',
+            'begin_year — Set the datetime to the start of the year.',
+            'end_year — Set the datetime to the end of the year.',
+            'format ({fmt}) — Format the date and time using a strftime-style format string. Default if none given: %Y-%m-%d %H:%M:%S. It will have the formatted string.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Show the current date and time.
+            #
+
+            dt [can] :
+              d [datetime] :
+              on_load [script] :
+                tell dt.d to now
+                show dt.d
+              next [script] : put '1 week from now' into dt.d
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/dt/time.rb

@@ -149,6 +149,49 @@ module Gloo
         dt = Chronic.parse( self.value )
         @engine.heap.it.set_to dt.strftime( format )
       end
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A reference to a time, but without a date. ' \
+            "The default format is: #{DEFAULT_FORMAT}. Note that you " \
+            'can put a time into a datetime object. You can also put a ' \
+            'Chronic phrase into the time.',
+          :messages => [
+            'now — Set to the current system time.',
+            'add ({amount}) — Add the amount to the date. The amount will be in the form of "1 day" or "3 months".',
+            'sub ({amount}) — Subtract the amount from the date. The amount will be in the form of "1 day" or "2 weeks".',
+            'hh — Get the hour portion of the time. Put the hour into it.',
+            'mm — Get the minute portion of the time. Put the minute into it.',
+            'ss — Get the second portion of the time. Put the second into it.',
+            'am — Get the am/pm portion of the time. Put "am" or "pm" into it.',
+            'format ({fmt}) — Format the time using a strftime-style format string. Default if none given: %H:%M:%S. It will have the formatted string.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Show the current time.
+            #
+
+            time [can] :
+              t [time] :
+              on_load [script] :
+                tell time.t to now
+                show time.t
+              next [script] :
+                put '1 hour from now' into time.t
+                show time.t
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/str_utils/cipher.rb

@@ -185,6 +185,65 @@ module Gloo
         return cipher.update( data ) + cipher.final
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Tool to encrypt and decrypt data.',
+          :children => [
+            'key (string) — The encryption key. Base64 encoded.',
+            'init_vector (string) — The initialization vector. Base64 encoded.',
+            'data (string) — The encrypted or decrypted data.'
+          ],
+          :messages => [
+            'generate_keys — Generate an encryption key and initialization vector. The keys are base64 encoded.',
+            'encrypt — Encrypt the data.',
+            'decrypt — Decrypt the data.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Encrypt and Decrypt a string.
+            #
+
+            encrypt [can] :
+
+              str [string] : Encrypt your data for better security!
+
+              cipher [cipher] :
+                key [string] :
+                init_vector [string] :
+                data [string] :
+
+              on_load [script] :
+                show
+                show 'Original string' (white)
+                show ^.str
+                show
+                show 'Generating Key' (white)
+                tell ^.cipher to generate_keys
+                show ^.cipher.key
+                show ^.cipher.init_vector
+                show
+                show 'Encrpting the string' (white)
+                put ^.str into ^.cipher.data
+                tell ^.cipher to encrypt
+                show ^.cipher.data
+                show
+                show 'Decrypting the string' (white)
+                tell ^.cipher to decrypt
+                show ^.cipher.data
+                show
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/str_utils/outline.rb

@@ -249,7 +249,71 @@ module Gloo
           end
         end
       end
-    
+
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Convert strings with a path to a hierarchical outline.',
+          :children => [
+            'object_source (alias) — Points to the data source. Should be a container with objects, each of which has a name and optionally an id.',
+            'entity_path (string) — The path to the entity, used to generate links to entities that have IDs.',
+            "separator_char (string) — Optional. If not specified, the '/' character is used. The character used to separate the path elements.",
+            'data (string) — The generated outline: a hierarchical outline of OL and LI elements. For children with IDs, links to entities are included.'
+          ],
+          :messages => [
+            'generate — Generate the outline from the list of strings.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Convert flat elements to hierarchal outline.
+            #
+
+            outline [container] :
+
+              on_load [script] :
+                tell outline.util to generate
+                show outline.util.data
+
+              src_data [container] :
+                1 [container] :
+                  id [int] : 1
+                  name [string] : a/b/c
+                2 [container] :
+                  id [int] : 2
+                  name [string] : a/b/d
+                3 [container] :
+                  id [int] : 3
+                  name [string] : a/b/e
+                4 [container] :
+                  id [int] : 4
+                  name [string] : x
+                5 [container] :
+                  id [int] : 5
+                  name [string] : x/y
+                6 [container] :
+                  id [int] : 6
+                  name [string] : x/y/z
+                7 [container] :
+                  id [int] : 7
+                  name [string] : last
+
+              util [outline] :
+                object_source [alias] : outline.src_data
+                entity_path [string] : /entity/
+                separator_char [string] : /
+                data [string] :
+          EXAMPLES
+        }
+      end
+
     end
   end
 end