gloo 6.0.1 → 6.2.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, theme, 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,57 @@ 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, the current color ' \
+            'theme, 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, theme, extensions, libraries, docs ' \
+            '(lists — theme also shows a color preview of both palettes), ' \
+            '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> theme
+            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

@@ -3,6 +3,10 @@
 #
 # Invoke a function from a script.
 #
+# Resolution, validation and the actual invoke are all handled by
+# Gloo::Core::Invoker, shared with inline calls inside expressions
+# (see Gloo::Expr::Call) so both go through the same error handling.
+#
 
 module Gloo
   module Verbs
@@ -15,24 +19,10 @@ module Gloo
       # Run the verb.
       #
       def run
-        if @tokens.token_count > 1
-          ob = @tokens.first
-
-          # Get the function object
-          pn = Gloo::Core::Pn.new( @engine, @tokens.second ) 
-          func = pn.resolve
-
-          # Is the object a function?
-          if func&.is_function?
-            params = get_params_arr
-          
-            @engine.log.debug "invoking function: #{func.pn}"
-            result = func.invoke( params ) 
-            @engine.log.debug "function returned: #{result}"
-            @engine.heap.it.set_to result
-            return result
-          end
-        end
+        target = @tokens.token_count > 1 ? @tokens.second : nil
+        arg_tokens = @tokens.token_count > 1 ? @tokens.params[ 1..-1 ] : []
+
+        return Gloo::Core::Invoker.invoke( @engine, target, arg_tokens )
       end
 
       #
@@ -50,29 +40,94 @@ module Gloo
       end
 
       # ---------------------------------------------------------------------
-      #    Private functions
+      #    Verb Documentation
       # ---------------------------------------------------------------------
 
-      private
-
       #
-      # Get params array.
+      # Get the verb's documentation data.
       #
-      def get_params_arr
-        @engine.log.debug "token params: #{@tokens.params}"
-        params = @tokens.params[1..-1]
+      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}',
+            'invoke( {path.to.function} {params} )  — inline, usable inside any expression',
+            '~>( {path.to.function} {params} )      — inline, shortcut spelling'
+          ],
+          :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. The ' \
+            'inline forms (invoke(...), ~>(...)) can be used anywhere ' \
+            'an expression is evaluated - show, put ... into, if, ' \
+            'unless, eval, and more - and evaluate to the result ' \
+            'directly rather than going through it.',
+          :errors => [
+            "#{Gloo::Core::Invoker::NO_TARGET_ERR} — No function reference was given.",
+            "#{Gloo::Core::Invoker::NOT_FOUND_ERR}{path.to.function} — The path doesn't resolve to any object.",
+            "#{Gloo::Core::Invoker::NOT_FUNCTION_ERR}{path.to.function} — The path resolves to an object that isn't a function.",
+            "#{Gloo::Core::Invoker::PARAM_COUNT_ERR}{path.to.function} (expected N, got N) — The number of params given doesn't match what the function declares."
+          ],
+          :notes => 'If the function itself fails during invocation ' \
+            '(its on_invoke script hits an error), it is left ' \
+            'unchanged rather than being set to an unreliable result. ' \
+            'The underlying error is whatever was reported by the ' \
+            'failure inside the function. ' \
+            'Inline call params are space-separated, same as the ' \
+            'standalone verb - each one is evaluated as a single ' \
+            'token (a literal or object reference), not a multi-token ' \
+            "sub-expression, so invoke( f 3+4 ) won't parse 3+4 as " \
+            'one arg.',
+          :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
 
-        @engine.log.info "params: #{params}"
-        evaluated_params = []
+                # Inline, anywhere an expression is evaluated:
+                show invoke( functions.add 3 4 )
+                put ~>( functions.add 3 4 ) into total
+                show "Total: " + invoke( functions.add 3 4 )
 
-        params.each do |p|
-          expr = Gloo::Expr::Expression.new( @engine, [ p ] )
-          evaluated_params << expr.evaluate
-        end
+                show 'done' (white)
 
-        @engine.log.debug "evaluated_params: #{evaluated_params}"
+              #
+              # Say hi to person (name)
+              #
+              greet [ƒ] :
+                on_invoke [script] :
+                  put 'Hi, ' + ^.params.name into ^.result
+                params [container] :
+                  name [string] : none
+                result [string] :
 
-        return evaluated_params
+              #
+              # 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

data/lib/gloo/verbs/list.rb

@@ -73,16 +73,17 @@ module Gloo
       # Show object in standard format.
       #
       def show_obj( obj, indent = '  ' )
+        theme = @engine.theme
         if obj.multiline_value? && obj.value_is_array?
-          str = "#{indent}#{obj.name}".white
-          str << " [#{obj.type_display}] : ".yellow
+          str = theme.emphasis( "#{indent}#{obj.name}" )
+          str << theme.accent( " [#{obj.type_display}] : " )
           @engine.log.show str
           obj.value.each do |line|
             @engine.log.show "#{indent}  #{line}"
           end
         else
-          str = "#{indent}#{obj.name}".white
-          str << " [#{obj.type_display}] : ".yellow
+          str = theme.emphasis( "#{indent}#{obj.name}" )
+          str << theme.accent( " [#{obj.type_display}] : " )
           str << "#{obj.value}"
           @engine.log.show str
         end
@@ -114,6 +115,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