RubyGems - gloo - Versions diffs - 6.1.0 → 6.2.0 - Mend

gloo 6.1.0 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

checksums.yaml +4 -4
data/CLAUDE.md +1 -1
data/README.md +1 -0
data/docs/application.md +24 -4
data/docs/getting_started.md +2 -4
data/docs/language_objects.md +1 -1
data/docs/language_syntax.md +29 -2
data/docs/plugins.md +325 -3
data/docs/web_app.md +211 -0
data/lib/VERSION +1 -1
data/lib/VERSION_NOTES +6 -0
data/lib/gloo/app/engine.rb +17 -2
data/lib/gloo/app/log.rb +5 -4
data/lib/gloo/app/platform.rb +5 -0
data/lib/gloo/app/prompt.rb +2 -1
data/lib/gloo/app/settings.rb +25 -15
data/lib/gloo/app/table.rb +7 -3
data/lib/gloo/app/theme.rb +144 -0
data/lib/gloo/core/invoker.rb +102 -0
data/lib/gloo/core/parser.rb +48 -7
data/lib/gloo/core/tokens.rb +81 -1
data/lib/gloo/docs/help_shell.rb +67 -20
data/lib/gloo/docs/markdown_renderer.rb +7 -7
data/lib/gloo/expr/call.rb +54 -0
data/lib/gloo/expr/expression.rb +3 -0
data/lib/gloo/objs/basic/string.rb +5 -25
data/lib/gloo/objs/basic/string_msgs.rb +192 -2
data/lib/gloo/objs/basic/text.rb +5 -26
data/lib/gloo/objs/ctrl/function.rb +17 -4
data/lib/gloo/verbs/help.rb +8 -5
data/lib/gloo/verbs/invoke.rb +39 -46
data/lib/gloo/verbs/list.rb +5 -4
data/test.gloo/objs/string.test.gloo +54 -0
data/test.gloo/verbs/invoke.test.gloo +73 -0
metadata +5 -3
data/.DS_Store +0 -0
data/.travis.yml +0 -5

data/docs/web_app.md ADDED Viewed

@@ -0,0 +1,211 @@
+# A Trivial Web App
+**Contents**
+- Overview
+- File and Folder Layout
+- start.gloo
+- app/app.gloo
+- layout/primary.gloo
+- shared/nav.gloo
+- page/home.gloo
+- page/about.gloo
+- Running It
+- Where To Go From Here
+## Overview
+This walks through the smallest complete gloo web app: a "Hello World" with two pages (`home` and `about`) sharing a common layout and nav bar. It uses the `gloo-web` core library — see Plugins for how core libraries are installed and loaded in general.
+The app runs in App Mode (`gloo --app {path}`, see Application) — gloo looks for a `start.gloo` file at the root of the app folder and runs it. That file loads everything else and starts the web server.
+## File and Folder Layout
+```
+hello/
+  start.gloo
+  app/
+    app.gloo
+  layout/
+    primary.gloo
+  shared/
+    nav.gloo
+  page/
+    home.gloo
+    about.gloo
+```
+- `start.gloo` — the entry point. Loads the `web` core library, then everything under `app/`, `layout/`, `shared/`, and `page/`, then starts the server.
+- `app/app.gloo` — the `app` object: the app's URL and its `svr` (web server), including server config and the default routes (layout, home page).
+- `layout/primary.gloo` — the page layout shared by every page: the HTML shell, the nav bar, and where a page's own head/body content gets inserted.
+- `shared/nav.gloo` — a partial (reusable fragment) for the nav bar, included by the layout.
+- `page/home.gloo`, `page/about.gloo` — the two pages. Every `[page]` object loaded under the root `page` container automatically becomes a route: `page.home` answers `/`, `page.about` answers `/about`. Routes are wired up by the router when the server starts — there's no separate routing table to maintain by hand.
+## start.gloo
+```gloo
+#
+# Start the hello app.
+#
+# Run it:
+#   gloo --app ~/gloo/projects/apps/hello
+#
+start [container] :
+  on_load [script] :
+    # Load the web core library.
+    load lib web
+    # Load the app's own objects.
+    load app/*
+    load layout/*
+    load shared/*
+    load page/*
+    # Start the server and open it in a browser.
+    tell app.svr to start
+    tell app.url to open
+```
+## app/app.gloo
+```gloo
+#
+# The hello app: web server config and default routes.
+#
+app [can] :
+  # The app's URL.
+  url [uri] : http://localhost:8080/
+  # The web server for the app.
+  svr [svr] :
+    config [container] :
+      scheme [string] : http
+      host [string] : localhost
+      port [string] : 8080
+    on_start [script] : show 'hello app started'
+    on_stop [script] : show 'hello app stopped'
+    # Default layout and home page.
+    layout [alias] : layout.primary
+    home [alias] : page.home
+```
+`svr` is a `gloo-web` object type (see Plugins — Core Libraries). `layout` and `home` are conventional aliases: `layout` points at the partial used to wrap every page that doesn't specify its own, and `home` points at the page served for `/`. A real app would also set `error [alias] : page.err` to control the page shown on a server error, but it's optional — gloo falls back to a generic message if it's not set.
+## layout/primary.gloo
+```gloo
+#
+# The shared page layout: HTML shell + nav bar.
+# Every page renders inside this unless it specifies its own layout.
+#
+layout [can] :
+  primary [part] :
+    content [can] :
+      html_open [text] : BEGIN
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <%= head %>
+</head>
+<body>
+END
+      nav [alias] : shared.nav
+      body [string] : <%= body %>
+      html_close [text] : BEGIN
+</body>
+</html>
+END
+```
+`primary` is a `[part]` (partial) — see Plugins for the `gloo-web` object list. `<%= head %>` and `<%= body %>` are filled in automatically by the page being rendered: whatever that page defines under its own `head` and `body` children. `nav` is an alias to the shared nav partial below, rendered inline wherever it appears in the layout's content.
+## shared/nav.gloo
+```gloo
+#
+# The shared nav bar, included by the layout.
+#
+shared [can] :
+  nav [part] :
+    content [text] : BEGIN
+<nav>
+  <a href="/">Home</a>
+  <a href="/about">About</a>
+</nav>
+END
+```
+## page/home.gloo
+```gloo
+#
+# The home page ("/").
+#
+page [can] :
+  home [page] :
+    params [can] :
+      msg [string] : Hello, World!
+    head [e] :
+      content [can] :
+        title [e] : Hello
+    body [e] :
+      content [can] :
+        h1 [e] : <%= msg %>
+        p [e] : This is the home page.
+```
+`page.home` is what `app.svr.home` points to, so it answers requests to `/`. `params` declares values the page's content can reference — here just `msg`, used in the `<h1>` via `<%= msg %>`. `head` and `title` and `body`, `h1`, `p` are `[e]` (element) objects — see Plugins — the building blocks the layout's `<%= head %>`/`<%= body %>` render.
+## page/about.gloo
+```gloo
+#
+# The about page ("/about"), reached by name automatically —
+# no routing table entry required.
+#
+page [can] :
+  about [page] :
+    head [e] :
+      content [can] :
+        title [e] : About
+    body [e] :
+      content [can] :
+        h1 [e] : About
+        p [e] : A trivial two-page gloo web app.
+```
+Because this page is named `about` and lives directly under the root `page` container, it's automatically routed to `/about` the moment the server starts — see File and Folder Layout above.
+## Running It
+```shell
+ gloo --app ~/gloo/projects/apps/hello
+```
+This runs `start.gloo`, which starts the server and opens `http://localhost:8080/` in a browser. Visit `/about` to see the second page. Stop the app the same way as any other gloo app (`q` at the prompt, or `Ctrl-C`).
+Once the app is running, `gloo-web`'s objects (`page`, `part`, `e`, `svr`, `form`, `field`) are all documented in-app — `help> object page`, etc. — see Plugins.
+## Where To Go From Here
+This example deliberately leaves out most of what `gloo-web` supports: forms and fields (`form`, `field`), page parameters populated from query strings, sessions, static assets (images/CSS/JS served from an `asset/` folder, with `image_tag`/`css_tag`/`js_tag` layout helpers), a database-backed page (`gloo-db` plus a `sqlite`/`mysql`/`postgres` driver — see Plugins), and a dedicated error page. Each of those follows the same shape shown here: an object type from `gloo-web` (or another core library), loaded the same way, documented the same way in `help`.

data/lib/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 6.1.0
1	+ 6.2.0

data/lib/VERSION_NOTES CHANGED Viewed

@@ -1,3 +1,9 @@
+6.2.0 - 2026.08.18
+ - Adds light | dark mode option for terminal output.
+ - Adds inline function invocation.
+ - Adds split messages for strings and text objects.
 6.1.0 - 2026.08.04
  - Adds narrative documentation: 10 pages in `docs/`, covering getting started, application, language objects/syntax/scripting, operators, iterators, objects, verbs, and plugins
  - Adds an in-app interactive help shell (`help`/`?`) to look up verbs, objects, settings, libraries, extensions, and doc pages, with tab completion

data/lib/gloo/app/engine.rb CHANGED Viewed

@@ -31,10 +31,14 @@ module Gloo
         @args = Args.new( self, context.params )
         @settings = Settings.new( self, context.user_root )
+        # Platform (and its theme) needs to be ready before Log is
+        # constructed - Log reads engine.theme, which reads through
+        # to platform.theme, in its own initialize.
+        @platform = context.platform
+        @platform.theme = Gloo::App::Theme.new( @settings.theme )
         @log = context.log.new( self, @args.quiet? )
         @log.debug "log (class: #{@log.class.name}) in use ..."
-        @platform = context.platform
         @log.debug "platform (class: #{@platform.class.name}) in use ..."
         @handling_exception = false
@@ -42,6 +46,17 @@ module Gloo
         @log.debug 'engine intialized...'
       end
+      #
+      # Get the active theme. Platform is the single source of
+      # truth for it (Prompt/Table only hold a @platform reference,
+      # not an @engine one) - this just reads through to that,
+      # rather than keeping a second ivar that could drift out of
+      # sync if something reassigns platform.theme directly.
+      #
+      def theme
+        return @platform.theme
+      end
       #
       # Start the engine.
       # Load object and verb definitions and setup engine elements.

data/lib/gloo/app/log.rb CHANGED Viewed

@@ -38,6 +38,7 @@ module Gloo
         @engine = engine
         @quiet = quiet
         @debug = engine.settings.debug
+        @theme = engine.theme
         create_loggers
@@ -160,7 +161,7 @@ module Gloo
       def warn( msg )
         @logger.warn msg
         @error.warn msg
-        puts msg.yellow unless @quiet
+        puts @theme.warn( msg ) unless @quiet
       end
       #
@@ -175,11 +176,11 @@ module Gloo
         if ex
           @error.error ex.message
           @error.error ex.backtrace
-          puts msg.red unless @quiet
-          puts ex.message.red unless @quiet
+          puts @theme.error( msg ) unless @quiet
+          puts @theme.error( ex.message ) unless @quiet
           puts ex.backtrace unless @quiet
         else
-          puts msg.red unless @quiet
+          puts @theme.error( msg ) unless @quiet
         end
       end

data/lib/gloo/app/platform.rb CHANGED Viewed

@@ -18,6 +18,7 @@ module Gloo
       PAGER_CMD = 'less -R -F -X'.freeze
       attr_reader :prompt, :table
+      attr_accessor :theme
       #
       # Set up Platform.
@@ -25,6 +26,10 @@ module Gloo
       def initialize
         @prompt = Gloo::App::Prompt.new( self )
         @table = Gloo::App::Table.new( self )
+        # Default theme, in case this platform is ever used
+        # standalone, without an Engine to set the real one.
+        @theme = Gloo::App::Theme.new
       end
       #

data/lib/gloo/app/prompt.rb CHANGED Viewed

@@ -87,7 +87,8 @@ module Gloo
         dt = DateTime.now
         d = dt.strftime( '%Y.%m.%d' )
         t = dt.strftime( '%I:%M:%S' )
-        return "#{'gloo'.blue} #{d.yellow} #{t.white} >"
+        theme = @platform.theme
+        return "#{theme.heading( 'gloo' )} #{theme.accent( d )} #{theme.emphasis( t )} >"
       end
     end

data/lib/gloo/app/settings.rb CHANGED Viewed

@@ -10,10 +10,13 @@ module Gloo
   module App
     class Settings
+      DEFAULT_THEME = 'dark'.freeze
+      THEMES = %w[dark light].freeze
       attr_reader :user_root, :log_path,
         :config_path, :project_path, :ext_path,
         :start_with, :list_indent, :list_levels, :tmp_path,
-        :debug_path, :debug
+        :debug_path, :debug, :theme
       #
       # Load setting from the yml file.
@@ -33,26 +36,29 @@ module Gloo
       # Can be seen in app with 'help settings'
       #
       def show
-        puts "\n Application Settings:".blue
-        puts '   Startup with:  '.yellow + @start_with.to_s.white
-        puts '   Indent in Listing:  '.yellow + @list_indent.to_s.white
-        puts '   List Levels:  '.yellow + @list_levels.to_s.white
-        puts '   Debug?  '.yellow + @debug.to_s.white
-        puts '   Screen Lines:  '.yellow + Gloo::App::Settings.lines( @engine ).to_s.white
-        puts '   Page Size:  '.yellow + Gloo::App::Settings.page_size( @engine ).to_s.white
+        theme = @engine.theme
+        puts theme.heading( "\n Application Settings:" )
+        puts theme.accent( '   Startup with:  ' ) + theme.emphasis( @start_with.to_s )
+        puts theme.accent( '   Indent in Listing:  ' ) + theme.emphasis( @list_indent.to_s )
+        puts theme.accent( '   List Levels:  ' ) + theme.emphasis( @list_levels.to_s )
+        puts theme.accent( '   Debug?  ' ) + theme.emphasis( @debug.to_s )
+        puts theme.accent( '   Theme:  ' ) + theme.emphasis( @theme )
+        puts theme.accent( '   Screen Lines:  ' ) + theme.emphasis( Gloo::App::Settings.lines( @engine ).to_s )
+        puts theme.accent( '   Page Size:  ' ) + theme.emphasis( Gloo::App::Settings.page_size( @engine ).to_s )
         self.show_paths
       end
       #
       # Show path settings
       #
       def show_paths
-        puts "\n Application Paths:".blue
-        puts '   User Root Path is here:  '.yellow + @user_root.white
-        puts '   Projects Path:  '.yellow + @project_path.white
-        puts '   Extensions Path:  '.yellow + @ext_path.white
-        puts '   Tmp Path:  '.yellow + @tmp_path.white
-        puts '   Debug Path:  '.yellow + @debug_path.white
+        theme = @engine.theme
+        puts theme.heading( "\n Application Paths:" )
+        puts theme.accent( '   User Root Path is here:  ' ) + theme.emphasis( @user_root )
+        puts theme.accent( '   Projects Path:  ' ) + theme.emphasis( @project_path )
+        puts theme.accent( '   Extensions Path:  ' ) + theme.emphasis( @ext_path )
+        puts theme.accent( '   Tmp Path:  ' ) + theme.emphasis( @tmp_path )
+        puts theme.accent( '   Debug Path:  ' ) + theme.emphasis( @debug_path )
         puts "\n"
       end
@@ -154,6 +160,9 @@ module Gloo
         @list_levels = settings[ 'gloo' ][ 'list_levels' ]
         @debug = settings[ 'gloo' ][ 'debug' ]
+        @theme = settings[ 'gloo' ][ 'theme' ]&.strip&.downcase
+        @theme = DEFAULT_THEME unless THEMES.include?( @theme )
       end
       #
@@ -184,6 +193,7 @@ module Gloo
             list_indent: 2
             list_levels: 3
             debug: false
+            theme: #{DEFAULT_THEME}
         TEXT
         return str
       end

data/lib/gloo/app/table.rb CHANGED Viewed

@@ -3,7 +3,6 @@
 #
 # CLI input.
 #
-require 'colorize'
 require 'terminal-table'
 module Gloo
@@ -28,14 +27,19 @@ module Gloo
       #
       # Show the given table data.
       #
+      # Deliberately left uncolored: box-drawing borders and text read
+      # fine against the terminal's own default colors, and forcing a
+      # fixed foreground/background (as this used to do) fought
+      # whatever theme the terminal was actually running.
+      #
       def show( headers, data, title = nil )
         unless title.blank?
-          table = Terminal::Table.new(
+          table = Terminal::Table.new(
             :title => title, :headings => headers, :rows => data )
         else
           table = Terminal::Table.new( :headings => headers, :rows => data )
         end
-        puts table.to_s.colorize( color: :white, background: :black )
+        puts table.to_s
       end

data/lib/gloo/app/theme.rb ADDED Viewed

@@ -0,0 +1,144 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Maps semantic color roles (heading, emphasis, etc) onto actual
+# ANSI colors for the app's UI chrome (prompt, settings, log,
+# tables, listings, help). Callers ask for a role, never a literal
+# color, so a single palette swap (dark/light) fixes every call
+# site at once.
+#
+# NOT used by the user-facing `show {target} (color)` verb or the
+# `[colorize]` core-lib object - those are explicit color choices
+# made in gloo scripts, not app chrome, and are intentionally left
+# alone.
+#
+# Design note: most of the base 8 ANSI colors (red/green/yellow/
+# blue/magenta/cyan) are exactly what a well-built terminal color
+# scheme remaps per-background to stay legible - that's what
+# switching a terminal profile from dark to light is for. `white`
+# is the exception: by convention it stays "lightest foreground"
+# regardless of background, so text forced to `.white` goes
+# near-invisible on a light background no matter how good the
+# terminal theme is. That's why :emphasis flips color between the
+# two palettes below.
+#
+# `yellow` and `cyan` turned out to be further exceptions in
+# practice: tested against a real light-background terminal, both
+# were washed out and hard to read - the terminal's own theme
+# wasn't remapping them as dark/saturated as hoped. So the light
+# palette diverges from dark on more than just :emphasis, using
+# explicit 256-color values (:ansi, raw SGR codes - none of these
+# have a true equivalent in the base 16 ANSI colors) picked by eye
+# against a real light terminal:
+#   - :warn uses orange instead of yellow
+#   - :accent uses a dark green instead of yellow
+#   - :subheading uses navy instead of cyan
+#
+require 'colorize'
+require 'colorized_string'
+module Gloo
+  module App
+    class Theme
+      # 256-color values picked by eye against a real light-background
+      # terminal - see design note above. 256-color support has been
+      # effectively universal in terminals for well over a decade.
+      ORANGE = '38;5;208'.freeze
+      NAVY = '38;5;18'.freeze
+      DARK_GREEN = '38;5;22'.freeze
+      #
+      # Dark-background palette. This matches the colors gloo
+      # has always used, so it's the default and non-breaking.
+      #
+      DARK = {
+        :heading    => { :color => :blue, :mode => :bold },
+        :subheading => { :color => :cyan, :mode => :bold },
+        :accent     => { :color => :yellow },
+        :emphasis   => { :color => :white },
+        :muted      => { :color => :light_black },
+        :warn       => { :color => :yellow },
+        :error      => { :color => :red }
+      }.freeze
+      #
+      # Light-background palette.
+      #
+      LIGHT = {
+        :heading    => { :color => :blue, :mode => :bold },
+        :subheading => { :ansi => NAVY },
+        :accent     => { :ansi => DARK_GREEN },
+        :emphasis   => { :color => :black },
+        :muted      => { :color => :light_black },
+        :warn       => { :ansi => ORANGE },
+        :error      => { :color => :red }
+      }.freeze
+      PALETTES = { 'dark' => DARK, 'light' => LIGHT }.freeze
+      ROLES = DARK.keys.freeze
+      attr_reader :name
+      #
+      # Set up the theme for the given theme name ('dark' or 'light').
+      # Falls back to the default (dark) for anything else.
+      #
+      def initialize( name = nil )
+        @name = PALETTES.key?( name ) ? name : Gloo::App::Settings::DEFAULT_THEME
+        @palette = PALETTES[ @name ]
+      end
+      #
+      # Build a Theme from the engine's settings.
+      #
+      def self.for_engine( engine )
+        return new( engine&.settings&.theme )
+      end
+      #
+      # Colorize the given string for the given semantic role.
+      # Unknown roles are returned unchanged rather than raising,
+      # so a typo'd role degrades to plain text instead of crashing.
+      #
+      # Named colors (:color/:mode) go through the colorize gem;
+      # :ansi is a raw SGR parameter string for colors the gem's
+      # named palette doesn't have (eg. 256-color orange).
+      #
+      def apply( str, role )
+        style = @palette[ role ]
+        return str.to_s unless style
+        return ansi_wrap( str.to_s, style ) if style[ :ansi ]
+        params = {}
+        params[ :color ] = style[ :color ] if style[ :color ]
+        params[ :mode ] = style[ :mode ] if style[ :mode ]
+        return ColorizedString[ str.to_s ].colorize( params ).to_s
+      end
+      #
+      # Define a convenience method per role, eg. theme.heading( str ).
+      #
+      ROLES.each do |role|
+        define_method( role ) do |str|
+          apply( str, role )
+        end
+      end
+      private
+      #
+      # Wrap a string in a raw SGR escape sequence - used for :ansi
+      # styles (eg. 256-color orange) that the colorize gem's named
+      # 16-color palette can't express.
+      #
+      def ansi_wrap( str, style )
+        codes = []
+        codes << String.mode_codes[ style[ :mode ] ] if style[ :mode ]
+        codes << style[ :ansi ]
+        return "\e[#{codes.join( ';' )}m#{str}\e[0m"
+      end
+    end
+  end
+end

data/lib/gloo/core/invoker.rb ADDED Viewed

@@ -0,0 +1,102 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Resolves, validates and invokes a function. Shared by the
+# `invoke`/`~>` verb (lib/gloo/verbs/invoke.rb) and inline calls
+# inside any expression (lib/gloo/expr/call.rb), so both go through
+# the same error handling instead of maintaining two copies of it.
+#
+module Gloo
+  module Core
+    class Invoker
+      NO_TARGET_ERR = 'Missing function reference!'.freeze
+      NOT_FOUND_ERR = 'Object was not found: '.freeze
+      NOT_FUNCTION_ERR = 'Not a function: '.freeze
+      PARAM_COUNT_ERR = 'Wrong number of parameters for function: '.freeze
+      #
+      # Resolve, validate and invoke the function at the given
+      # target path, with the given raw (unevaluated) arg tokens.
+      # Reports an error and returns nil for any failure - including
+      # a failure inside the function itself (see Function#invoke,
+      # which leaves `it` alone rather than setting it to an
+      # unreliable result when that happens).
+      #
+      def self.invoke( engine, target, arg_tokens )
+        if target.nil? || target.to_s.strip.empty?
+          engine.err NO_TARGET_ERR
+          return nil
+        end
+        func = resolve_function( engine, target )
+        return nil unless func
+        args = evaluate_arg_tokens( engine, arg_tokens )
+        return nil unless params_count_ok?( engine, func, args )
+        return invoke_function( engine, func, args )
+      end
+      #
+      # Resolve the function object at the target path. Reports an
+      # error and returns nil if the path doesn't resolve to
+      # anything, or resolves to an object that isn't a function.
+      #
+      def self.resolve_function( engine, target )
+        pn = Gloo::Core::Pn.new( engine, target )
+        func = pn.resolve
+        unless func
+          engine.err "#{NOT_FOUND_ERR}#{target}"
+          return nil
+        end
+        unless func.is_function?
+          engine.err "#{NOT_FUNCTION_ERR}#{target}"
+          return nil
+        end
+        return func
+      end
+      #
+      # Evaluate a list of raw tokens, each as its own single-token
+      # expression (a literal or object reference) - the standalone
+      # invoke verb's long-standing per-token semantics, now shared
+      # with the inline-call form too.
+      #
+      def self.evaluate_arg_tokens( engine, tokens )
+        return ( tokens || [] ).map do |t|
+          Gloo::Expr::Expression.new( engine, [ t ] ).evaluate
+        end
+      end
+      #
+      # Confirm the number of args given matches the number the
+      # function declares. Reports an error and returns false if
+      # they don't match.
+      #
+      def self.params_count_ok?( engine, func, args )
+        expected = func.params_hash&.keys&.length || 0
+        return true if args.count == expected
+        engine.err "#{PARAM_COUNT_ERR}#{func.pn} " \
+          "(expected #{expected}, got #{args.count})"
+        return false
+      end
+      #
+      # Invoke the function and return its result.
+      #
+      def self.invoke_function( engine, func, args )
+        engine.log.debug "invoking function: #{func.pn}"
+        result = func.invoke( args )
+        engine.log.debug "function returned: #{result}"
+        return result
+      end
+    end
+  end
+end