gloo 6.0.1 → 6.2.0

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

@@ -161,23 +161,36 @@ module Gloo
       #    Messages
       # ---------------------------------------------------------------------
 
-      # 
+      #
       # Invoke the function, run the script and return the result.
-      # 
+      #
+      # If on_invoke itself hits an error, it is left alone rather
+      # than being clobbered with an unreliable result - callers can
+      # tell this happened because the engine is left in an error
+      # state (@engine.heap.error), same as any other failed verb.
+      #
       def invoke args
         @engine.log.debug "Invoking function: #{name}"
 
         set_params args if args
+
+        @engine.heap.error.start_tracking
         run_on_invoke
+        failed = @engine.heap.error.error_count.positive?
+
+        if failed
+          run_after_invoke
+          return nil
+        end
 
-        if @engine.running_app&.obj&.embedded_renderer 
+        if @engine.running_app&.obj&.embedded_renderer
           return_value = @engine.running_app.obj.embedded_renderer.render result, params_hash
         else
           return_value = result
         end
         @engine.heap.it.set_to return_value
         run_after_invoke
-        
+
         return return_value
       end
 
@@ -194,6 +207,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

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

@@ -159,6 +159,62 @@ module Gloo
         @engine.heap.it.set_to result
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'A password object that can be generated, hashed, and compared.',
+          :children => [
+            'salt (string) — Optional salt to use when hashing and checking passwords.',
+            'password (string) — The password. generate puts a new random password here. Used in the hash and check messages.',
+            'hash (string) — The hashed value of the password. Created when the hash message is called, and compared when the check message is called.'
+          ],
+          :messages => [
+            'generate ({len}) — Generate a new password, put in the password child object. The {len} parameter is optional; the length is 7 if not specified.',
+            'hash — Hash the password in the child object. Put it in the hash child object.',
+            'check — Check the password in the child object. Is it the same as the hash?'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # Password Hashing and checking.
+            #
+            password [can] :
+
+              pwd [password] :
+                salt [string] : MySalt
+                password [string] :
+                hash [string] :
+
+              on_load [script] :
+                show
+                show 'Generating a new password' (white)
+                tell ^.pwd to generate
+                show 'Password: ' + ^.pwd.password
+                show
+                show 'hashing the password' (white)
+                tell ^.pwd to hash
+                show ^.pwd.hash (red)
+                show
+                show 'checking with the correct password' (white)
+                tell ^.pwd to check
+                show 'Result of check: ' + it (green)
+                show
+                show 'checking with the wrong password' (white)
+                tell ^.pwd to generate(23)
+                tell ^.pwd to check
+                show 'Result of check: ' + it (red)
+                show
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/objs/system/erb.rb

@@ -110,6 +110,45 @@ module Gloo
         set_result render.result_with_hash( param_hash )
       end
 
+      # ---------------------------------------------------------------------
+      #    Object Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the object's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Use the ERB templating system to generate ' \
+            'content. For example, you can use the ERB object for ' \
+            'string interpolation.',
+          :children => [
+            'template (text) — The template that will be used when the ERB object is run.',
+            'params (container) — The collection of children values used when the template is rendered.',
+            'result (text) — The result of the template rendering.'
+          ],
+          :messages => [
+            'run — Render the result based on the template and the parameter values.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            e [can] :
+              erb [erb] :
+                template [text] : BEGIN
+                  Hello <%= first %> <%= last %>!
+                  END
+                params [container] :
+                  first [string] : Eric
+                  last [string] : Crane
+                result [text] :
+              on_load [script] :
+                run e.erb
+                show e.erb.result
+          EXAMPLES
+        }
+      end
+
     end
   end
 end