gloo 6.0 → 6.1.0

data/lib/gloo/verbs/files.rb

@@ -43,6 +43,28 @@ module Gloo
 
       private
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Show a list of all loaded files and their ' \
+            'associated objects.',
+          :syntax => [ 'files' ],
+          :result => 'The list of files and associated objects is shown ' \
+            'in output. It is set to the number of files that have been loaded.',
+          :examples => <<~EXAMPLES.strip
+            > files
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/help.rb

@@ -10,41 +10,18 @@ module Gloo
 
       KEYWORD = 'help'.freeze
       KEYWORD_SHORT = '?'.freeze
-      DEFAULT_HELP = 'default_help'.freeze
-      HELP_NOT_FOUND_ERR = 'Help command could not be found:'.freeze
 
-      DISPATCH = {
-        s: 'show_settings',
-        settings: 'show_settings',
-        verb: 'show_verbs',
-        verbs: 'show_verbs',
-        v: 'show_verbs',
-        o: 'show_objs',
-        obj: 'show_objs',
-        object: 'show_objs',
-        objects: 'show_objs',
-        e: 'show_ext',
-        ext: 'show_ext',
-        l: 'show_lib',
-        lib: 'show_lib',
-        library: 'show_lib',
-        libraries: 'show_lib',
-        extension: 'show_ext',
-        extensions: 'show_ext'
-      }.freeze
+      BANNER = "Entering the gloo help shell. Type 'quit' to exit.\n" \
+        "Try: verbs, objects, settings, extensions, libraries, docs, " \
+        "verb {name}, object {name}, doc {name}, library {name}, extension {name}\n".freeze
 
       #
       # Run the verb.
+      # Takes no arguments - always enters the interactive help shell.
       #
       def run
-        opts = @tokens.second if @tokens
-        opts = opts.strip.downcase if opts
-
-        if opts
-          dispatch opts
-        else
-          show_default_help
-        end
+        @engine.log.show BANNER
+        build_shell.start
       end
 
       #
@@ -62,166 +39,54 @@ module Gloo
       end
 
       # ---------------------------------------------------------------------
-      #    Private functions
+      #    Verb Documentation
       # ---------------------------------------------------------------------
 
-      private
-
-      #
-      # Write output to it and show it unless we are in
-      # silent mode.
-      #
-      def show_output( out )
-        @engine.heap.it.set_to out
-        puts out unless @engine.args.quiet?
-      end
-
-      #
-      # Show application settings.
-      #
-      def show_settings
-        @engine.settings.show
-      end
-
-      #
-      # Show default help.
-      # No parameters were given.
-      # 
-      def show_default_help
-        data = "\n"
-        data << " Help Options:\n"
-        data << "   ? objects (obj, o) \n"
-        data << "   ? verbs (v) \n"
-        data << "   ? ext (e) \n"
-        data << "   ? lib (l) \n"
-        data << "   ? settings (s) \n"
-        data << "\n For detailed documentation use the gloo website. \n"
-        data << "\n     https://gloo.ecrane.us/doc/. \n\n"
-        @engine.log.show data
-      end
-
-      #
-      # Dispatch the help to the right place.
-      #
-      def dispatch( opts )
-        @engine.log.debug 'looking for help topic'
-        cmd = DISPATCH[ opts.to_sym ]
-        if cmd
-          @engine.log.debug 'found help command'
-          send cmd
-        else
-          report_help_error opts
-        end
-      end
-
-      #
-      # Report an error with the inline help.
-      #
-      def report_help_error( opts )
-        @engine.err "#{HELP_NOT_FOUND_ERR} '#{opts}'"
-      end
-
-      #
-      # List the verbs
-      #
-      def show_verbs
-        data = "\n"
-        data << " Verbs (shortcut, name)\n".blue
-        data << "#{get_verbs}\n\n"
-        @engine.log.show data
-      end
-
-      #
-      # List the object types
       #
-      def show_objs
-        data = "\n"
-        data << " Objects \n".blue
-        data << "#{get_objects}\n\n"
-        @engine.log.show data
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Enter the interactive help shell. From there, ' \
+            'look up verbs, object types, settings, extensions, libraries, ' \
+            'and narrative doc pages, or get detailed help for a specific ' \
+            'verb, object, doc page, loaded library, or loaded extension.',
+          :syntax => [ 'help' ],
+          :result => "Enters the help shell, prompt \"help> \". Commands: " \
+            'verbs, objects, settings, extensions, libraries, docs (lists), ' \
+            'verb {name}, object {name}, doc {name}, library {name}, ' \
+            'extension {name} (detail for one, tab-completable — library ' \
+            '{name} / extension {name} show the README for a loaded core ' \
+            "library / user extension). Type 'quit' to leave the shell.",
+          :examples => <<~EXAMPLES.strip
+            > help
+            help> verbs
+            help> verb put
+            help> object container
+            help> docs
+            help> doc getting_started
+            help> library db
+            help> extension alert
+            help> quit
+          EXAMPLES
+        }
       end
 
-      #
-      # Get the text for the list of verbs.
-      #
-      def get_verbs
-        str = ''
-        verbs = @engine.dictionary.get_verbs.sort_by( &:keyword )
-        verbs.each_with_index do |v, i|
-          cut = v.keyword_shortcut.ljust( 5, ' ' ).yellow
-          name = v.keyword.ljust( 20, ' ' ).white
-          str << "   #{cut}  #{name} \n"
-        end
-
-        return str
-      end
-
-      #
-      # Get the text for the list of objects.
-      #
-      def get_objects
-        str = ''
-        objs = @engine.dictionary.get_obj_types.sort_by( &:typename )
-        objs.each_with_index do |o, i|          
-          if o.short_typename != o.typename
-            short = "(#{o.short_typename})".yellow
-            name = "#{o.typename.white}  #{short}"
-          else
-            name = o.typename.white
-          end
-          str << "   #{name.ljust( 30, ' ' )}\n"
-        end
-
-        return str
-      end
-
-      #
-      # List the extensions
-      #
-      def show_ext
-        data = "\n"
-        data << " Extensions\n".blue
-        data << "#{get_extensions}\n\n"
-        @engine.log.show data
-      end
-
-      #
-      # Get the text for the list of extensions.
-      #
-      def get_extensions
-        str = ''
-        exts = @engine.ext_manager.loaded_extensions.sort
-        exts.each do |name, ext|
-          str << "   #{name.white} \n"
-        end
-
-        return str
-      end
+      # ---------------------------------------------------------------------
+      #    Private functions
+      # ---------------------------------------------------------------------
 
-      #
-      # List the libraries
-      #
-      def show_lib
-        data = "\n"
-        data << " Libraries\n".blue
-        data << "#{get_libraries}\n\n"
-        @engine.log.show data
-      end
+      private
 
       #
-      # Get the text for the list of libraries.
+      # Build the help shell for this run.
       #
-      def get_libraries
-        str = ''
-        libs = @engine.lib_manager.loaded_libraries.sort
-        libs.each do |name, lib|
-          str << "   #{name.white} \n"
-        end
-
-        return str
+      def build_shell
+        return Gloo::Docs::HelpShell.new( @engine )
       end
 
-
     end
   end
 end

data/lib/gloo/verbs/if.rb

@@ -101,6 +101,58 @@ module Gloo
 
         i.run
       end
+
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'If an expression is true then do something.',
+          :syntax => [
+            'if {true} then {do}',
+            'if {true} then {do} else {do else}'
+          ],
+          :parameters => [
+            '{true} — Does the expression evaluate to true?',
+            '{do} — Execute command if the expression is true.',
+            '{do else} — The else command is optional. Execute command if the expression is false.'
+          ],
+          :result => 'Unchanged if the expression is not true. If true, ' \
+            'then the result will be based on the command specified ' \
+            'after the then keyword.',
+          :errors => [
+            "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
+            'Other errors depend on the command that is run.'
+          ],
+          :examples => <<~EXAMPLES.strip
+            #
+            # If statement example
+            #
+
+            if [container] :
+
+              x [bool] : false
+              true_msg [string] : It is true!
+
+              on_load [script] :
+                if if.x then show "first time: " + if.true_msg
+                if ^.x then show 'T' else show 'F'
+
+                put true into if.x
+                if if.x \\
+                  then show "second time: " + if.true_msg
+                if ^.x \\
+                  then show 'T' \\
+                  else show 'F'
+          EXAMPLES
+        }
+      end
     end
   end
 end

data/lib/gloo/verbs/invoke.rb

@@ -75,6 +75,68 @@ module Gloo
         return evaluated_params
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Invoke a function. Set it to the result of the function.',
+          :syntax => [ 'invoke {path.to.function} {params}' ],
+          :parameters => [
+            '{path.to.function} — The function we want to invoke.',
+            '{params} — The list of parameters to the function.'
+          ],
+          :result => 'The result of the function is put into it.',
+          :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/verbs/list.rb

@@ -114,6 +114,38 @@ module Gloo
         return '  '
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'List out objects (and children) at the ' \
+            'current context. When a path is provided, it will be ' \
+            'listed instead of the current context. When using context, ' \
+            'the current context will be shown, but when context has ' \
+            'not been set, the root will be shown.',
+          :syntax => [ 'list {path.to.object}' ],
+          :parameters => [
+            '{path.to.object} — Optional path to object that will be listed. When no path is provided, the current context is used.'
+          ],
+          :result => 'Object and children are listed out in the CLI.',
+          :errors => [
+            "#{TARGET_MISSING_ERR}{path.to.object} — The object specified that is to be listed could not be found."
+          ],
+          :examples => <<~EXAMPLES.strip
+            > list
+            > list my.container
+            > list root
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/load.rb

@@ -77,13 +77,66 @@ module Gloo
         @engine.ext_manager.load_ext name
       end
 
-      # 
+      #
       # Load a library
-      # 
+      #
       def load_library( name )
         @engine.log.debug "Getting ready to load library: #{name}"
         @engine.lib_manager.load_lib name
       end
+
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Load an object file. There are two ways to ' \
+            'specify the file. Give either the full path and file name ' \
+            'or use a relative path from the gloo project folder. For ' \
+            'the latter, the extension is not needed. For the former, ' \
+            'the file extension is necessary. Using * instead of a file ' \
+            'name will load all gloo files in the folder. When using the ' \
+            '--app option, the file is loaded from the application ' \
+            'folder, but if not found there, the loader will also look ' \
+            'in the gloo root folder. The load verb is also used to ' \
+            'import an extension or library at runtime.',
+          :syntax => [
+            'load {file_name}',
+            'load ext {my_ext}',
+            'load lib {lib_name}'
+          ],
+          :parameters => [
+            '{file_name} — Name of the object file that is to be loaded.',
+            'reference type — By default, the type is file. File can be ' \
+              'specified, but does not need to be. Use ext to load a ' \
+              'User Extension. Use lib to load a Core Library.'
+          ],
+          :result => 'Objects are loaded into the heap. on_load scripts ' \
+            'are run within the loaded objects.',
+          :errors => [
+            "#{MISSING_EXPR_ERR} — No expression is provided as parameter to the verb.",
+            "#{UNKNOWN_OPT_ERR} — The reference type given isn't file, ext, or lib.",
+            "#{WRONG_NUM_ARGS_ERR} — load expects 2 or 3 arguments (the verb, an optional reference type, and the file/ext/lib name)."
+          ],
+          :examples => <<~EXAMPLES.strip
+            > load my/project/file
+            > load my/app/*
+            > load ~/.my_app/settings.gloo
+
+            # Load a User Extension
+            > load ext my_ext
+
+            # Load a Core Library
+            > load lib db
+          EXAMPLES
+        }
+      end
     end
   end
 end

data/lib/gloo/verbs/log.rb

@@ -85,6 +85,50 @@ module Gloo
         return Gloo::App::Log::LEVELS[0]
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Write to the standard gloo log, or to the gloo error log.',
+          :syntax => [ 'log {target} ({level})' ],
+          :parameters => [
+            '{target} — The message that will be written to the log. ' \
+              'The target might be the path to an object, a literal or ' \
+              'an expression to be evaluated. Level options are: DEBUG, ' \
+              'INFO, WARN, ERROR. Level is an optional parameter — if ' \
+              'not specified, the message is written as DEBUG level.'
+          ],
+          :result => 'The message is written to the log at the ' \
+            'specified level. It will contain the log message.',
+          :notes => "Use `log clear` from the CLI to clear out both the " \
+            "standard log and the error log.\n\n" \
+            "> log clear",
+          :examples => <<~EXAMPLES.strip
+            #
+            # Show multiple messages in loggers
+            #
+
+            log [can] :
+              level [string] : info
+              msg [string] : info from var
+              on_load [script] :
+                log "debug implicit"
+                log "debug explicit" (debug)
+                log "info" (info)
+                log "warn" (warn)
+                log "error" (error)
+                log log.msg (log.level)
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/move.rb

@@ -13,7 +13,7 @@ module Gloo
       TO = 'to'.freeze
       MISSING_SRC_ERR = 'Object to move was not specified!'.freeze
       MISSING_SRC_OBJ_ERR = 'Could not find object to move: '.freeze
-      MISSING_DST_ERR = "Move' must include 'to' parent object!".freeze
+      MISSING_DST_ERR = "'Move' must include 'to' parent object!".freeze
       MISSING_DST_OBJ_ERR = 'Could not resolve target: '.freeze
 
       #
@@ -84,6 +84,41 @@ module Gloo
         return o
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Move an object to a new parent.',
+          :syntax => [ 'move {path.to.object} to {new.parent}' ],
+          :parameters => [
+            '{path.to.object} — The object that we want to move.',
+            '{new.parent} — The new location for the object.'
+          ],
+          :result => 'The object will now be in the new location.',
+          :errors => [
+            "#{MISSING_SRC_ERR} The {path.to.object} is not specified.",
+            "#{MISSING_SRC_OBJ_ERR}{path.to.object} — The {path.to.object} cannot be resolved.",
+            "#{MISSING_DST_ERR} The {new.parent} is not specified.",
+            "#{MISSING_DST_OBJ_ERR}{new.parent} — The {new.parent} cannot be resolved."
+          ],
+          :examples => <<~EXAMPLES.strip
+            can [can] :
+              two [string] : def
+              data [can] :
+                one [string] : abc
+              on_load [script] :
+                move can.two to can.data
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/put.rb

@@ -89,6 +89,41 @@ module Gloo
         end
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Put a value into an object. ' \
+            'The value is the result of an expression.',
+          :syntax => [ 'put {expression} into {dst.path}' ],
+          :parameters => [
+            '{expression} — The expression that is evaluated.',
+            '{dst.path} — The path to the destination object.'
+          ],
+          :result => 'The destination object has the result of the ' \
+            'evaluated expression. It will also be set into it.',
+          :errors => [
+            "#{MISSING_EXPR_ERR} — The into keyword is missing, or no source expression is provided.",
+            "#{INTO_MISSING_ERR} — The destination is not specified.",
+            "#{TARGET_ERR}{dst.path} — The destination of the put cannot be resolved."
+          ],
+          :examples => <<~EXAMPLES.strip
+            > put 'one' into str
+            > put "two" into str
+            > put 123 into x
+            > put 3 + 5 into x
+            > put TRUE into flag
+          EXAMPLES
+        }
+      end
+
     end
   end
 end

data/lib/gloo/verbs/quit.rb

@@ -35,6 +35,25 @@ module Gloo
         return KEYWORD_SHORT
       end
 
+      # ---------------------------------------------------------------------
+      #    Verb Documentation
+      # ---------------------------------------------------------------------
+
+      #
+      # Get the verb's documentation data.
+      #
+      def self.doc_data
+        {
+          :name => KEYWORD,
+          :shortcut => KEYWORD_SHORT,
+          :description => 'Stop running the gloo application. Cleanup and shutdown.',
+          :syntax => [ 'quit' ],
+          :examples => <<~EXAMPLES.strip
+            > quit
+          EXAMPLES
+        }
+      end
+
     end
   end
 end