gloo 6.0.1 → 6.2.0

data/docs/operators.md

@@ -0,0 +1,62 @@
+# Operators
+
+Gloo operators can be used to do basic math and to compare values.
+
+**Contents**
+
+- Math Operators
+- Comparison Operators
+- Example
+
+## Math Operators
+
+These are the gloo math operators:
+
+```
++   addition
+-   subtraction
+*   multiplication
+/   division
+```
+
+## Comparison Operators
+
+Strings, integers, and decimal numbers can be compared.
+
+These are the gloo comparison operators:
+
+```
+=   equal (== also works, as an alternate spelling — not a separate identity check)
+!=  not equal
+>   greater than
+<   less than
+>=  greater than or equal to
+<=  less than or equal to
+```
+
+## Example
+
+Here are some examples of math operator usage:
+
+```
+> show 2 + 5
+> put 12 / 3 into x
+> show 23 * 3 - 6
+```
+
+And some examples of comparison operator usage:
+
+```
+> show 2 = 2
+> show 2 != 2
+> show 2 > 2
+> show 2 < 2
+> show 2 >= 2
+> show 2 <= 2
+
+> if a = b then show "the strings are equal"
+> if x > y then run my_script
+> put x != y into my_bool
+```
+
+See also: Put, Show.

data/docs/plugins.md

@@ -0,0 +1,376 @@
+# Plugins
+
+**Contents**
+
+- Core Libraries
+- User Extensions
+
+## Core Libraries
+
+Core Libraries extend gloo functionality, primarily by adding object types and potentially verbs.
+
+Be sure to load a core library (or extension) prior to loading a gloo file that includes object types defined in the library.
+
+Use the Load Verb to use an extension.
+
+A core library ships as its own gem (`gloo-<name>`). `load lib <name>` requires the gem, installing it first via `gem install` if it isn't already present — so the explicit `gem install` step below is optional, but doing it yourself ahead of time is recommended so the install doesn't happen mid-script. Once loaded, a library's objects and verbs show up in the `help`/`?` shell exactly like built-ins:
+
+```gloo
+> gem install gloo-yaml
+> load lib yaml
+help> object yaml
+```
+
+### Available Core Libraries
+
+- **CLI** — Use the `gloo-cli` gem when building CLI applications.
+    - Library Objects: Prompt, Colorize, Confirm, Select, Menu, Menu Item, Shell, Command
+    ```gloo
+    > gem install gloo-cli
+    > load lib cli
+    help> object prompt
+    ```
+- **Database** — Use the `gloo-db` gem and one or more of `gloo-sqlite`, `gloo-mysql`, `gloo-pg` connector gems.
+    - Library Objects: Query, Table, SQLite, MySQL, Postgres
+    ```gloo
+    > gem install gloo-db gloo-sqlite
+    > load lib db
+    > load lib sqlite
+    help> object query
+    ```
+- **Email** — Use the `gloo-email` gem to send and receive email.
+    - Library Objects: Email, Email SMTP, Email IMAP
+    ```gloo
+    > gem install gloo-email
+    > load lib email
+    help> object email_smtp
+    ```
+- **Markdown** — Use the `gloo-md` gem to render markdown.
+    - Library Objects: Markdown, MD Doc (a markdown file with YAML frontmatter), Markdown Extensions (part of the markdown object)
+    ```gloo
+    > gem install gloo-md
+    > load lib md
+    help> object markdown
+    ```
+- **Test** — Use the `gloo-test` gem to manually include. See Test Runner for notes about the gloo test runner.
+    - Library Objects: Test
+    - Library Verbs: Assert, Refute
+    - See also: Eval, It
+    ```gloo
+    > gem install gloo-test
+    > load lib test
+    help> verb assert
+    ```
+- **Web Server** — Use the `gloo-web` gem when building web applications.
+    - Library Objects: Server, Page, Partial, Form, Field, Element
+    ```gloo
+    > gem install gloo-web
+    > load lib web
+    help> object page
+    ```
+- **YAML** — Use the `gloo-yaml` gem for YAML file read/write support.
+    - Library Objects: YAML
+    ```gloo
+    > gem install gloo-yaml
+    > load lib yaml
+    help> object yaml
+    ```
+
+## User Extensions
+
+A User Extension is a mechanism that can be used to add verbs and objects that are not built into gloo.
+
+Extensions are ruby code that live in the `extensions` folder inside the gloo root folder (`~/gloo/extensions` by default — see `ext_path` in Settings).
+
+An extension is structured thus:
+
+```
+~/gloo/extensions/
+  /ext_name
+    /doc/
+    /src/
+    /test/
+    /ext_name_ext.rb
+```
+
+- `ext_name_ext.rb` — the extension's entry point. Loaded and registered when `load ext ext_name` runs.
+- `src/` — the verb and/or object classes themselves, one file per class.
+- `doc/` — narrative markdown for the extension (a `README.md` at the extension root plus optional per-object/verb `.md` files under `doc/` are the convention used by the built-in extensions — see e.g. `extensions/beep/`).
+- `test/` — both Ruby unit tests (`*_test.rb`, minitest, same conventions as this project's own `test/` — see Test Suites in the root `CLAUDE.md`) and/or a gloo-language integration test (`*.test.gloo`).
+
+Be sure to load an extension (or core library) prior to loading a gloo file that includes object types defined in the extension.
+
+Use the Load Verb to use an extension: `load ext ext_name`.
+
+### The extension entry point
+
+`ext_name_ext.rb` defines a class named `<ExtName>Ext` (the extension's folder name, capitalized, plus `Ext`) that derives from `Gloo::Plugin::Base` and implements `register`. `register` is handed a `Gloo::Plugin::Callback` that it uses to register one or more verb and/or object classes:
+
+```ruby
+#
+# Registers the beep extension.
+#
+# This extension provides a simple beep command.
+#
+class BeepExt < Gloo::Plugin::Base
+
+    #
+    # Register verbs and objects.
+    #
+    def register( callback )
+      require_relative 'src/beep'
+
+      callback.register_verb( Beep )
+    end
+
+end
+```
+
+`callback.register_verb` and `callback.register_obj` both take a class, not an instance. Wrap the calls in a `begin`/`rescue` if the extension has external dependencies (a gem, a CLI tool on the `PATH`, etc.) that might not be present, so a missing dependency logs an error instead of crashing the whole extension load — see `extensions/stats/stats_ext.rb` or `extensions/git/git_ext.rb` for the pattern:
+
+```ruby
+def register( callback )
+  require_relative 'src/git'
+
+  begin
+    callback.register_obj( Git )
+  rescue => e
+    puts "Failed to load Git extension: #{e.message}"
+  end
+end
+```
+
+### Adding a Verb
+
+A verb subclasses `Gloo::Core::Verb` and must implement `self.keyword`, `self.keyword_shortcut`, and `run`. Inside `run`, `@tokens` gives access to the parsed command line and `@engine` is the running engine (use `@engine.err` for user-facing errors, `@engine.heap.it` to set the implicit `it` result).
+
+The simplest possible verb — `beep`, which takes no parameters (`extensions/beep/src/beep.rb`):
+
+```ruby
+#
+# Play a standard system beep sound.
+#
+class Beep < Gloo::Core::Verb
+
+  KEYWORD = 'beep'.freeze
+  KEYWORD_SHORT = 'b'.freeze
+
+  def self.keyword
+    return KEYWORD
+  end
+
+  def self.keyword_shortcut
+    return KEYWORD_SHORT
+  end
+
+  def run
+    print 7.chr
+  end
+
+  # ---------------------------------------------------------------------
+  #    Verb Documentation
+  # ---------------------------------------------------------------------
+
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'Play a standard system beep sound.',
+      :syntax => [ 'beep' ],
+      :result => 'A system beep (chime) is sounded.',
+      :examples => <<~EXAMPLES.strip
+        > beep
+      EXAMPLES
+    }
+  end
+
+end
+```
+
+A verb that reads a parameter — `alert`, which evaluates an expression and shows it as a system notification (`extensions/alert/src/alert.rb`):
+
+```ruby
+class Alert < Gloo::Core::Verb
+
+  KEYWORD = 'alert'.freeze
+  KEYWORD_SHORT = '!'.freeze
+
+  MISSING_EXPR_ERR = 'Missing Expression!'.freeze
+  NO_RESULT_ERR = 'Expression evaluated with no result!'.freeze
+
+  def run
+    unless @tokens.token_count > 1
+      @engine.err MISSING_EXPR_ERR
+      return
+    end
+
+    expr = Gloo::Expr::Expression.new( @engine, @tokens.params )
+    result = expr.evaluate
+
+    if result
+      @engine.heap.it.set_to result
+      post_alert result
+    else
+      @engine.err NO_RESULT_ERR
+    end
+  end
+
+  def self.keyword
+    return KEYWORD
+  end
+
+  def self.keyword_shortcut
+    return KEYWORD_SHORT
+  end
+
+  private
+
+  def post_alert( msg )
+    @engine.log.info msg
+    return if @engine.args.quiet?
+
+    post_osx msg
+  end
+
+  def post_osx( msg )
+    cmd1 = '/usr/bin/osascript -e "display notification \"'
+    cmd2 = '\" with title \"Gloo\" "'
+    system( cmd1 + msg.to_s + cmd2 )
+  end
+
+end
+```
+
+Register it from `alert_ext.rb` with `callback.register_verb( Alert )`, and the verb `alert {message}` becomes available anywhere after `load ext alert`.
+
+### Adding an Object
+
+An object subclasses `Gloo::Core::Obj` and must implement `self.typename` and `self.short_typename`. Objects typically:
+
+- expose named children (settings/parameters) that are read with `find_child`
+- optionally auto-add default children on creation, via `add_children_on_create?` and `add_default_children`
+- respond to messages (`tell obj to some_message`) by overriding `self.messages` to list the message names and defining a `msg_<name>` method for each
+
+`stats`, from `extensions/stats/src/stats.rb`, shows all three. It declares three children (`folder`, `types`, `skip`), adds them automatically on `create`, and implements three messages that delegate to a plain Ruby helper class (`Gloo::Utils::Stats`, in `extensions/stats/src/stats_util.rb`) that does the real work:
+
+```ruby
+class Stats < Gloo::Core::Obj
+
+  KEYWORD = 'stats'.freeze
+  KEYWORD_SHORT = 'stat'.freeze
+  FOLDER = 'folder'.freeze
+  TYPES = 'types'.freeze
+  SKIP = 'skip'.freeze
+
+  def self.typename
+    return KEYWORD
+  end
+
+  def self.short_typename
+    return KEYWORD_SHORT
+  end
+
+  def path_value
+    o = find_child FOLDER
+    return o ? o.value : nil
+  end
+
+  def types_value
+    o = find_child TYPES
+    return o ? o.value : ''
+  end
+
+  def skip_list
+    o = find_child SKIP
+    val = o ? o.value : ''
+    return val.split ' '
+  end
+
+  # ---------------------------------------------------------------------
+  #    Children
+  # ---------------------------------------------------------------------
+
+  def add_children_on_create?
+    return true
+  end
+
+  def add_default_children
+    fac = @engine.factory
+    fac.create_file FOLDER, '', self
+    fac.create_string TYPES, '', self
+    fac.create_can SKIP, self
+  end
+
+  # ---------------------------------------------------------------------
+  #    Messages
+  # ---------------------------------------------------------------------
+
+  def self.messages
+    all = %w[show_all]
+    more = %w[show_busy_folders show_types]
+    return super + all + more
+  end
+
+  def msg_show_all
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.show_all
+  end
+
+  def msg_show_types
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.file_types
+  end
+
+  def msg_show_busy_folders
+    o = Gloo::Utils::Stats.new(
+      @engine, path_value, types_value, skip_list )
+    o.busy_folders
+  end
+
+end
+```
+
+`self.messages` should call `super` and append to it — the base `Gloo::Core::Obj` already contributes messages every object receives (`reload`, `unload`, `blank?`, `contains?`, `responds_to?`).
+
+Used from gloo, once loaded:
+
+```gloo
+main [can] :
+  stats [stats] :
+    folder [file] : /Users/me/dev/project
+    types [string] : rb erb js
+    skip [string] : .git tmp
+  on_load [script] :
+    tell main.stats to show_all
+```
+
+Register it from `stats_ext.rb` with `callback.register_obj( Stats )`.
+
+### Custom `each` iterators
+
+An extension's object can also plug into the built-in `each` verb by providing its own iterator. `extensions/git/src/each_repo.rb` shows the shape: a plain Ruby class (not a `Gloo::Core::Obj`) with `self.use_for?( iterator_obj )` — which returns `true` when the `each` loop's iterator object looks like a match (here, when it has a `repo` child) — and a `run` method that walks whatever it's iterating over, setting the loop's child value and calling `@iterator_obj.run_do` for each item. See the git extension for the full pattern; this hook only makes sense for extensions that also register a matching object type (here, `git_repo`).
+
+### Documenting the extension
+
+Add `self.doc_data` to every verb/object class (see the `beep` and `stats` examples above) — this is what powers the in-app `help`/`?` shell once the extension is loaded, exactly as it does for built-in verbs and objects (see `lib/gloo/docs/doc_data.rb`). Also add a top-level `README.md` for the extension (usage, `load ext` line, list of verbs/objects, a pointer to `help> verb <name>` / `help> object <name>` for the full reference) — see `extensions/beep/README.md` or `extensions/git/README.md` for the expected shape and length.
+
+### Testing an extension
+
+Add a Ruby unit test per verb/object class under `test/` (mirrors the conventions in the root `CLAUDE.md`'s Test Suites section — inherit from the project's `GlooTest`/`BaseEngineTest` base), and add a `*.test.gloo` integration test that loads the extension and exercises it end to end, e.g. `extensions/beep/test/beep.test.gloo`:
+
+```gloo
+tests [can] :
+  beep [can] :
+
+    on_load [script] :
+      load ext beep
+
+    assert_verb [test] :
+      description [string] : The beep verb exists
+      on_test [script] :
+        exists? verb beep
+        assert "beep verb should exist"
+        beep
+```

data/docs/verbs.md

@@ -0,0 +1,64 @@
+# Verbs
+
+Verbs are the commands that make up a gloo script — `put`, `show`, `run`, `tell`, and 25 others. Every statement in gloo starts with a verb.
+
+Verbs aren't just for scripts, though. They're also the interactive language of the gloo application itself: run `gloo` in CLI mode (see Application, Running Gloo) and you can type these same verbs directly at the prompt, one at a time, in a REPL.
+
+**Contents**
+
+- Run
+- Tell
+- Put
+
+This page walks through three of the most commonly used verbs to get a feel for how they work together. For the complete list of verbs, their full syntax, and every error they can raise, use the in-app help: enter `help` (or `?`), then `verbs` to list them all, or `verb {name}` for detail on one (see Application, Help).
+
+## Run
+
+`run` runs a script or other runnable object — the same as sending it a `run` message.
+
+```gloo
+run {path.to.object}
+```
+
+```gloo
+> run my.script
+
+> create s as script : "show 3 + 4"
+> run s
+```
+
+## Tell
+
+`tell` sends a message to an object, asking it to do something. Where `run` executes a runnable object, `tell` is the general-purpose way to invoke any message an object supports (`up`, `count`, `inc`, `randomize` — see Objects).
+
+```gloo
+tell {path.to.object} to {message}
+```
+
+```gloo
+> tell an.obj to unload
+> tell the.script to run
+> tell my.str to up
+> tell the.container to count
+```
+
+## Put
+
+`put` evaluates an expression and stores the result in an object.
+
+```gloo
+put {expression} into {dst.path}
+```
+
+```gloo
+> put 'one' into str
+> put 123 into x
+> put 3 + 5 into x
+> put TRUE into flag
+```
+
+`it` also picks up the result of the evaluation, same as with other verbs — see It.
+
+---
+
+`run`, `tell`, and `put` cover a lot of ground on their own, but there are 26 more verbs — `show`, `if`, `create`, `each`, `check`, and so on — all documented in-app. Enter `help` (or `?`), then `verbs` to browse them. (This page itself is also viewable in-app: `help> doc verbs`.)

data/docs/web_app.md

@@ -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`.