gloo 6.0.1 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54e31fab11ca7b56ff0774597b7df5ca8ce4c12cd416d5074847119e684e3ba2
-  data.tar.gz: 6ae88d3462a36a5255c26193a9be890b35a51d6f45d92956e1f5dc538e924b28
+  metadata.gz: 6d840aa7f080d3daedcc5bbb7311b5403d40ea859edef9d88caca22b76caee6c
+  data.tar.gz: c324e249c1a307000b1de509573a5c03de4420bae941efb69ea0b1adcd927d47
 SHA512:
-  metadata.gz: a3e32e76dc86d9e5b3dc04f8f1934e083184a20b30171f9a5b57fbc68151d69f166d9eebdc1d04350e48303dc37aa8e8b46e44f1e6d03754060b736611b723b1
-  data.tar.gz: e7f7eaabc94045d1af5afa66d5522c3f9fa914224c9bb8ca7a5b6030380b6b04d940f612e73d38fa3a92570c5eaf3a05c20d0fe41258d1a34b9c65225fba1da9
+  metadata.gz: 48cb54242371f5b6589ba0baacf71da8b75c4f1118fecb6ba78eccb17be0f03d920551f0d93d6512802827c7bfa0cae462cf05a993f77061f525d9d6277c9e8d
+  data.tar.gz: 1bc77db8417820182b27b1f7b797f1587e21dc595d89d06b3250f8db983df149d9564f258bee5b4139182e3af95ceb9dfb23b07b533fcea5bbfe9f803a50eac1

data/CLAUDE.md

@@ -1,5 +1,3 @@
-@/Users/ecrane/dev/gloo_meta/CLAUDE.md
-
 # Gloo — Core Interpreter
 
 This is the main gloo language implementation, packaged as a Ruby gem.
@@ -19,7 +17,7 @@ gloo/
 │   │   ├── str_utils/
 │   │   ├── system/  ruby, file_handle, system
 │   │   └── web/     http_get, http_post, json, uri, erb
-│   ├── verbs/       One file per verb (28 total)
+│   ├── verbs/       One file per verb (29 total)
 │   ├── persist/     File loading/saving
 │   ├── convert/     Type conversion
 │   └── plugin/      Plugin system
@@ -27,6 +25,14 @@ gloo/
 └── test.gloo/       Gloo-language integration tests
 ```
 
+## Documentation
+
+This project is the authoritative source for gloo language documentation — not the `vaults/gloo` Obsidian vault, whose old `doc/` folder was renamed to `doc_deprecated/` and retired.
+
+- **Narrative reference** — `docs/*.md`, ten flat files: `getting_started.md`, `application.md`, `language_objects.md`, `language_syntax.md`, `language_scripting.md`, `operators.md`, `iterators.md`, `objects.md`, `verbs.md`, `plugins.md`. Linked from the root `README.md`. Convention: no markdown link syntax between pages (plain-text pointers instead, e.g. "see Put" not `[Put](put.md)`) since these are read both on GitHub and in a terminal; `---` separates sections that came from different source material.
+- **Verb/object reference** — each verb (`lib/gloo/verbs/*.rb`) and object type (`lib/gloo/objs/**/*.rb`) class defines `self.doc_data` (name, shortcut, description, syntax, parameters, result, errors, examples, notes — see `lib/gloo/docs/doc_data.rb`), rendered by the in-app interactive help shell (`help`/`?`, see `lib/gloo/docs/help_shell.rb`). When adding or changing a verb or object type, add/update its `doc_data` too.
+- Core-lib gems (`gloo_core_libraries`) follow the same `doc_data` pattern for their own verbs/objects; a narrative `doc/` folder per gem is planned but not yet built.
+
 ## Test Suites
 
 ### Ruby unit tests — `test/`

data/README.md

@@ -1,24 +1,55 @@
 # Gloo
 
-Gloo is a scripting language built on ruby.
+## About This Project
 
+gloo is a personal passion project — a custom interpreted programming language
+built in Ruby that I've been designing and building over several years. It's
+under active, ongoing development, so expect the design (especially around
+GUI support) to keep evolving.
+
+This is shared publicly for visibility, not as a maintained open-source
+project. I'm not actively seeking contributions right now, but feel free to
+open an issue if something's broken or you're curious about the design —
+just know response times may be slow.
 
-## Installation
 
-Install gloo like this:
+## Installation
 
-    $ gem install gloo
+The gloo gem is published on [RubyGems](https://rubygems.org/gems/gloo) and
+can be installed with:
 
+```
+gem install gloo
+```
 
 ## Usage
 
 Run gloo:
 
-    $ gloo
+```
+gloo
+```
+
+See documentation below, or the in-app help for usage.
 
 
 ## Documentation
 
-See documentation here:
+Read in order for a guided tour of the language, top to bottom, or jump straight to any page — pages toward the bottom are reference material and read fine out of sequence.
+
+1. [Getting Started](docs/getting_started.md) — prerequisites, installation, hello world, history and concepts
+2. [Application](docs/application.md) — running gloo, modes, configuration, logging, the in-app help shell
+3. [Language, Objects](docs/language_objects.md) — object naming, keywords, literals, value conversion
+4. [Language, Syntax](docs/language_syntax.md) — color, errors, events, system objects, here/it, pathnames
+5. [Language, Scripting](docs/language_scripting.md) — script files, constants, line continuation
+6. [Objects](docs/objects.md) — a tour of built-in object types (string, container, integer)
+7. [Verbs](docs/verbs.md) — a tour of verbs (run, tell, put)
+8. [Operators](docs/operators.md) — math and comparison operators
+9. [Iterators](docs/iterators.md) — each, repeat
+10. [Plugins](docs/plugins.md) — core libraries and user extensions
+
+
+## License
 
-    https://gloo.ecrane.us/doc
+This project is licensed under the [MIT License](LICENSE.txt) — see
+`LICENSE.txt` for details.

data/docs/application.md

@@ -0,0 +1,164 @@
+# Gloo Application
+
+**Contents**
+
+- The Gloo Home Directory
+- Running Gloo
+- Modes
+- Configuration
+- Logging
+- Help
+
+## The Gloo Home Directory
+
+Gloo keeps its configuration, projects, and logs under a per-user home directory. This is exposed at runtime through a set of gloo system objects (see Language, Syntax) (`gloo.gloo_home`, and friends):
+
+- `gloo.gloo_home` — the gloo home directory
+- `gloo.gloo_config` — the configuration directory (see Configuration, below)
+- `gloo.gloo_projects` — the projects directory (same as `gloo.app` when an app is running)
+- `gloo.gloo_log` — the logging directory (see Logging, below)
+
+```
+> show gloo.gloo_home
+```
+
+## Running Gloo
+
+```
+gloo [global option] [file]
+```
+
+Running gloo with a file specified will run that file. Once that file is done, gloo will quit. However, by specifying `--cli`, once the file has finished, gloo will remain open in CLI mode.
+
+When specifying a file there are a couple ways to reference the gloo file to open:
+
+- By Path
+    - Use an absolute or relative path to the gloo file.
+    - Include the `.gloo` or other file extension when specifying by path.
+    - For example:
+        ```
+        gloo ~/folder/file.gloo
+        ```
+- By Project
+    - Use the path within the project folder.
+    - Do not include the `.gloo` or other file extension.
+    - The location of the project folder is part of the configuration.
+    - For example:
+        ```
+        gloo my_project/file.gloo
+        ```
+
+## Modes
+
+```
+--cli        - Run in CLI mode
+             - If no options are specified, this is the default.
+--app        - Run in App mode
+             - Requires an extra parameter which is the root path of the project.
+             - Running in app mode overrides the default project path for gloo.
+             - By default gloo will look for a start.gloo file in the
+               root level of the project. That start.gloo file should load other files
+               and run the app.
+--script     - Run in Script mode
+             - Run the script in the file parameter and then quit.
+             - If a file is provided as a parameter this option does not need to be specified.
+--test       - Run in Test mode
+--version    - Show application version
+```
+
+## Configuration
+
+When gloo runs, it looks for a configuration file which it expects to find in `~/gloo/config/`. If there is no `gloo.yml` file in that directory, one will be created and default values added.
+
+```yaml
+#
+# Gloo configuration
+#
+gloo:
+
+  #
+  # Root directory for projects.
+  # Update this with the directory with your gloo projects.
+  #
+  project_path: /Users/my_user/gloo/projects
+
+  #
+  # Run this script when starting up gloo.
+  # (Only if a script file is not specified.)
+  #
+  start_with: start
+
+  #
+  # Indentation (spaces) when showing an object outline.
+  #
+  list_indent: 3
+
+  #
+  # Show listing the object tree,
+  # how many levels of children will be shown?
+  # Children at deeper levels will be hidden.
+  #
+  list_levels: 3
+
+  #
+  # Show debug statements in the log?
+  #
+  debug: false
+```
+
+## Logging
+
+Gloo writes to the `gloo.log` and `error.log` files as well as to the console.
+
+Debug messages are written to the log only, but other messages are also written to the console unless the application is running in quiet mode.
+
+Only error and warning level messages are written to the error log.
+
+The application logs folder is in the gloo folder. When gloo is run, the log files will be created if they do not exist. To trim the logs, just delete those log files.
+
+Example tail command to watch the gloo log:
+
+```shell
+tail -f ~/gloo/logs/gloo.log
+tail -f ~/gloo/logs/error.log
+```
+
+## Help
+
+### Inline Reference
+
+Gloo has a built-in `help` verb (shortcut `?`) that enters an interactive help shell:
+
+```gloo
+help
+```
+
+From the `help>` prompt, 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:
+
+- `verbs` — list all verbs
+- `objects` — list all object types
+- `settings` — show application settings
+- `extensions` — list loaded extensions (only loaded extensions are shown; use `load ext {name}` first)
+- `libraries` — list loaded libraries (only loaded libraries are shown; use `load lib {name}` first)
+- `docs` — list all narrative doc pages (this page and its siblings)
+- `verb {name}` — detailed help for one verb (tab-completable)
+- `object {name}` — detailed help for one object type (tab-completable)
+- `doc {name}` — show one narrative doc page (tab-completable)
+- `library {name}` — show a loaded library's README, from the root of its gem (tab-completable, loaded libraries only)
+- `extension {name}` — show a loaded extension's README, from the root of its extension folder (tab-completable, loaded extensions only)
+- `quit` — leave the help shell
+
+```gloo
+> help
+help> verbs
+help> verb put
+help> object container
+help> docs
+help> doc getting_started
+help> library db
+help> quit
+```
+
+### Narrative Docs in the Shell
+
+This page and its nine siblings (`docs/*.md` in the interpreter's source) are the same files shown by `help> doc {name}` — there's no separate doc server or web mode. A `gloo --doc` local web server was considered and put off in favor of this: one system, no separate build/serve step.

data/docs/getting_started.md

@@ -0,0 +1,112 @@
+# Getting Started with Gloo
+
+**Contents**
+
+- Prerequisites
+- Installation
+- Configuration
+- Running Gloo
+- Hello World
+- History
+- Concepts
+- Source Code
+
+## Prerequisites
+
+- Ruby
+
+Gloo requires Ruby to run. Nothing else is required for the core interpreter.
+
+If you don't have Ruby installed, you can download it from here: http://www.ruby-lang.org/en/downloads/
+
+MySQL and Postgres are only needed if you plan to use the `gloo-mysql` or `gloo-pg` core library gems to connect to those databases from a gloo script — see Plugins. Install them only if and when you load one of those libraries.
+
+## Installation
+
+Gloo is distributed as a Ruby gem (https://rubygems.org/gems/gloo). Once you have Ruby installed, you can install Gloo by running the following command:
+
+```shell
+ gem install gloo
+```
+
+## Configuration
+
+See Application Configuration for details on how to configure Gloo.
+
+## Running Gloo
+
+To start Gloo, run the following command:
+
+```shell
+ gloo
+```
+
+This will start the Gloo application. This is just enough to get going — for the full set of global options and the two ways to point gloo at a file (by path or by project), see Application, Running Gloo.
+
+## Hello World
+
+Once Gloo is running you can interact with the gloo interpreter. Type the following command to see the "Hello World" message:
+
+```gloo
+ show "Hello World"
+```
+
+## History
+
+### CLI, On Ruby
+
+Gloo is a scripting language and a CLI runtime engine. It was built primarily to run on the Mac and has hooks into several Mac technologies. It runs, at least nominally, on Windows and Linux as well.
+
+Gloo was built in Ruby as a gem. More than that, it has hooks into ruby, can run ruby code, and shares a lot the way ruby works.
+
+### The Name "Gloo" and a Bit of History
+
+Like glue, it is meant to hold things together.
+
+Gloo follows in a series of languages created by it's author. The first was called 'EDT' which stood for Eric's Data Tools. That first set of tools was followed shortly by 'Sqlman' built in the late 90s. Sqlman evolved into a more generalized tool called "AppBuilder". Those three applications were built in Prograph CPX and ran on pre-OS X Macs.
+
+ObjectWise came along as a cross-platform version of AppBuilder. ObjectWise was built in Java on a Sun workstation, and targeted Solaris, Mac OS X, and Windows. It was built around the turn of the millenium. But with job changes, the project went cold for a while and was revived under the name 'Obliner' around 2010. Obliner never gained much traction and never had any substantial use.
+
+Then in late 2018, the project with many names took on a new form as a ruby gem. It was intially called 'object-script' but that was soon changed to 'gloo'. Gloo remains under active development. It has one fanatical user, it's author, but that user makes daily use of it in his work, for personal use, and for fun.
+
+### Why Another Language?
+
+Why another scripting language? Why not just use ruby? Everything in gloo could be done in ruby or any number of other programming or scripting languages. Well, why not? Why should a developer NOT build a programming language as a way to learn and tinker? Why not have a bespoke tool that does just what one wants and that one can change as one pleases? Building a language is an act of invention and creativity. It is an act of rebellion against the machine of best practice and uniformity that corporate jobs often end up being. It is entirely consistent with being a software developer. And why not build a language for the sheer joy of inventing?
+
+### Ideas Behind It
+
+The following technologies influenced the thinking behind gloo and its predecessors:
+
+- HyperCard
+- Userland Frontier
+- Prograph
+- Newton OS
+- Ruby and Rails
+
+But each of those could be an essay in and of themselves. Maybe some day they will be.
+
+## Concepts
+
+### Outline Based Language
+
+One of the key ideas of gloo is that code and data is organized in an outline. All data and code is intermixed in the same hierarchy. And data in this case represents what in other languages are variables as well as in memory data structures and data storage. Data and code all in the same space. It is all accessed the same way, with a path through the outline. And variables and data can be inspected just like code. This can be done at time of coding as well as at runtime.
+
+### Composition
+
+Another key idea is that code is composed of smaller pieces. The best way to think of gloo is a collection of parts that are assembled together to make something useful.
+
+### Convention
+
+Like Rails, gloo prefers convention over configuration. That is to say that it attempts to make configuration unnecessary unless the user wishes to diverge from the convention. It does not require the programmer to tell it what it can figure out on its own.
+
+### Objects & Messages
+
+In gloo, everything is an object. The object types are built into the language. (There is a plan to add support for user defined object types.)
+
+Objects can have simple values and can also contain other objects.
+
+Interaction with objects is done by sending messages to them.
+
+## Source Code
+
+Gloo source code is in GitHub (https://github.com/ecrane/gloo), although the repository is currently private. It might be made public in the future if there is interest or need.

data/docs/iterators.md

@@ -0,0 +1,294 @@
+# Iterators
+
+**Contents**
+
+- Each
+- Each Child
+- Each Directory
+- Each File
+- Each Line
+- Each Word
+- Repeat
+
+## Each
+
+Perform an action for each item in a collection.
+
+There are several variations on this object type. They are:
+
+- each child object in a container
+- each directory in a folder
+- each file in a folder
+- each line in a block of text (string)
+- each word in a string
+
+The general pattern is that there are three children:
+
+- An `in` object that points to the item collection.
+- A reference to the item instance. This reference is updated each time through the loop. Note that the name of this child is used to determine which kind of loop is in play.
+- A `do` script to run for each iteration through the loop.
+
+Messages:
+
+- `run` — Run the loop for each item in the collection.
+
+See examples in the specific variations, below.
+
+See also: Object Base.
+
+## Each Child
+
+Iterate for each child in a container.
+
+Children:
+
+- `child` (alias)
+    - Alias to the child instance.
+- `in` (container)
+    - The collection of objects we will iterate over.
+- `do` (script)
+    - The action we want to perform for each child in the container.
+
+### Group By
+
+Group the results by a child property. This is an optional feature. It can be used when we want to do something specific every time a value in the child object changes.
+
+Whenever the `group_by` value changes, the `on_group_start` and `on_group_end` scripts are run. This can be used to aggregate results in rows or other groupings.
+
+The group by feature adds the following children:
+
+- `group_by` (string)
+    - The name of the child object we want to group by. This will be a property of the object instance of the `child` container.
+- `on_group_start` (script)
+    - The action we want to perform when the `group_by` value changes. This script will be run before the `do` script for the first instance of the child with the new `group_by` value.
+- `on_group_end` (script)
+    - The action we want to perform when the `group_by` value changes. This script will be run after the `do` script for the last instance of the `group_by` value.
+
+Messages:
+
+- `run` — Run the loop for each object in the container.
+
+```gloo
+#
+# 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
+```
+
+See also: Object Base, Each, Each File, Each Line, Each Word.
+
+## Each Directory
+
+Iterate for each directory in a folder (directory).
+
+Children:
+
+- `dir` (file — a directory)
+    - The directory instance.
+- `in` (file — a directory)
+    - The folder (directory) we will look in for directories.
+- `do` (script)
+    - The action we want to perform for each directory in the folder.
+
+Messages:
+
+- `run` — Run the loop for each directory.
+
+```gloo
+#
+# Show each directory.
+#
+each_dir [can] :
+
+  # Iterator on files in a folder.
+  for [each] :
+    dir [file] :
+    in [file] : /my/folder/
+    do [script] : show ^.dir
+
+  # Run the iterator.
+  on_load [script] :
+    show 'showing directory' (white)
+    tell each_dir.for to run
+```
+
+See also: Each, Each File.
+
+## Each File
+
+Iterate for each file in a folder (directory).
+
+Children:
+
+- `file` (file)
+    - The file instance.
+- `in` (file)
+    - The folder (directory) we will look in for files.
+- `do` (script)
+    - The action we want to perform for each file in the folder.
+- `ext` (string)
+    - Optional file extension. Limit to files of this kind.
+
+Messages:
+
+- `run` — Run the loop for each file in the folder.
+
+```gloo
+#
+# Show each file in a folder.
+#
+each_file [can] :
+
+  # Iterator on files in a folder.
+  for [each] :
+    file [file] :
+    ext [string] : gloo
+    in [file] : /my/folder/
+    do [script] : show ^.file
+
+  # Run the iterator.
+  on_load [script] :
+    show 'showing files in folder' (white)
+    tell each_file.for to run
+```
+
+See also: Object Base, Each, Each Line, Each Word, Each Child, Each Directory.
+
+## Each Line
+
+Iterate for each line in a text block (string).
+
+Children:
+
+- `line` (string)
+    - The single line of text.
+- `in` (text)
+    - The block of text or string.
+- `do` (script)
+    - The action we want to perform for each line in the text.
+
+Messages:
+
+- `run` — Run the loop for each line in the text.
+
+```gloo
+#
+# Show each line in a string.
+#
+each_line [can] :
+
+  # Iterator on children of a container.
+  for [each] :
+    line [string] :
+    in [alias] : ^.in
+    do [script] : show ^.line
+
+  # Data
+  in [txt] : BEGIN
+    I will now write a poem
+    of several lines
+    Then I will show it
+    and it will be awesome!
+    END
+
+  # Run the iterator.
+  on_load [script] :
+    show 'showing lines in a text block' (white)
+    tell each_line.for to run
+```
+
+See also: Object Base, Each, Each Word, Each Child, Each File.
+
+## Each Word
+
+Iterate for each word in a string.
+
+Children:
+
+- `word` (string)
+    - The word (string).
+- `in` (string)
+    - The source string.
+- `do` (script)
+    - The action we want to perform for each word in the string.
+
+Messages:
+
+- `run` — Run the loop for each word in the string.
+
+```gloo
+#
+# Show each word in a string.
+#
+each_word [can] :
+
+  # Iterator on words in a string.
+  for [each] :
+    word [string] :
+    in [string] : one word at a time
+    do [script] : show ^.word
+
+  # Run the iterator.
+  on_load [script] :
+    show 'showing words in a string' (white)
+    tell each_word.for to run
+```
+
+See also: Object Base, Each, Each Child, Each File, Each Line.
+
+## Repeat
+
+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 we want to perform for iteration of the loop.
+
+Messages:
+
+- `run` — Run the script for the given number of times.
+
+```gloo
+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
+```
+
+See also: Object Base.