gloo 6.0.1 → 6.2.0

data/docs/language_objects.md

@@ -0,0 +1,190 @@
+# Language, Objects
+
+**Contents**
+
+- Object Naming
+- Keywords
+- Literals
+- Value Conversion
+
+## Object Naming
+
+Object names are single words (no spaces) and conform to the following:
+
+- Spaces in names are not allowed.
+- Names should be unique within their context.
+    - Note that there is no technical restriction. Multiple objects with the same name in the same context can exist, but there's no way to reference objects past the first one with the given name.
+- Names can be capitalized or lower case.
+    - But names with different cases are not treated as unique.
+- Names can contain numbers and special characters.
+
+```gloo
+#
+# Example of object naming.
+#
+# NOTE that the second 'a' and the 'A' objects are not reachable.
+# 'naming.a' will always reach the 'First A' string.
+#
+naming [container] :
+  on_load [script] :
+    show naming.msg!$%
+    show naming.a
+    show naming.1
+  msg!$% [string] : Naming stuff
+  a [string] : First A
+  a [string] : Second A is not reachable
+  A [string] : Capital A is not reachable
+  1 [string] : One
+```
+
+See also: Pathname.
+
+## Keywords
+
+Gloo doesn't reserve words the way many languages do. A verb keyword like `put` or an object type name like `string` can also be used as an object name — there's no parser conflict, because verbs are only looked up as the first word of a statement, and object type names are only looked up where a type is expected (inside the `[ ]` on a declaration). Everywhere else, the word is just a pathname segment (see Object Naming, above).
+
+That said, gloo's own vocabulary — words that already mean something built-in — comes from two sources:
+
+- Verb keywords, and their shortcuts (see Verbs) — `put`, `show`, `run`, `tell`, and the rest.
+- Object type names, and their shortcuts (see Objects) — `string`, `container`, `integer`, and the rest.
+
+Both lists grow as core libraries and extensions load — `load lib {name}` and `load ext {name}` can add new verbs and object types at runtime, so the full set isn't fixed. Use the in-app help (see Application, Help) for the live list of whatever's currently loaded: enter `help` (or `?`), then `verbs` or `objects`.
+
+See also: Verbs, Objects.
+
+## Literals
+
+Literals are values inline in a script command.
+
+The following rules apply to literal values:
+
+- Strings
+    - Can be delimited by single or double quotes. (`"` or `'`)
+- Numbers
+    - Integer and decimal numbers need no delimiters.
+    - To refer to a decimal with no fractional value, include `.0` to indicate a decimal value.
+- Booleans
+    - Can be `TRUE` or `FALSE`
+    - Note that the text is case insensitive.
+
+```gloo
+#
+# Examples of literal values.
+#
+
+  literal [can] :
+
+    s [string] :
+    i [integer] :
+    d [decimal] :
+    b [boolean] :
+
+    #
+    # Use Literals to assign values
+    #
+    on_load [script] :
+
+      # String literals
+      put 'Hello world.' into ^.s
+      show ^.s
+      put "You're Awesome!" into ^.s
+      show ^.s
+
+      # Number literals
+      put 1 into ^.i
+      show ^.i
+      put 3.12 into ^.d
+      show ^.d
+
+      # Boolean literals
+      # Boolean literals are case insensitive
+      put TRUE into ^.b
+      show ^.b
+      put false into ^.b
+      show ^.b
+```
+
+See also: Put, Show, String, Boolean, Integer, Decimal, Value Conversion.
+
+## Value Conversion
+
+When putting an object or literal value into another object, gloo will attempt to convert the value to the target type.
+
+Here are some of the value conversions that gloo will attempt:
+
+- string to integer
+    - additional text is discarded
+    - `put '1 one' into x` => 1
+- integer to string
+    - simple to-string conversion
+- string to decimal
+    - additional text is discarded
+    - `put '3.25 and more…' into x` => 3.25
+- decimal to string
+    - simple to-string conversion
+- decimal to integer
+    - drops everything after the decimal point
+    - `put 1.23 into x` => 1
+- integer to decimal
+    - decimal with integer value
+    - `put 1 into d` => 1.0
+- string to boolean
+    - if the string is (trimmed, case-insensitive) 'true' or 't' then the boolean is true; 'false' or 'f' is false; anything else is false
+    - `put 'true' into bool` => true
+- boolean to string
+    - simple to-string conversion: 'true' or 'false'
+- integer to boolean
+    - 0 => false, otherwise true
+    - `put 1 into bool` => true
+- boolean to integer
+    - true => 1, false => 0
+- string to date
+    - uses Chronic lib to convert text to date
+    - `put '7/11' into dt` => 2024.07.11
+- date to string
+    - convert date to string in default format
+- string to time
+    - uses Chronic lib to convert text to time
+    - `put 'now' into time` => 01:24:55 pm
+- time to string
+    - convert time to string in default format
+- string to datetime
+    - uses Chronic lib to convert text to datetime
+    - `put 'now' into dt` => 2024.07.11 01:21:39 pm
+- datetime to string
+    - convert datetime to string in default format
+
+```gloo
+#
+# Examples of value conversions.
+#
+
+  convert [can] :
+
+    i [integer] : 1
+    d [decimal] : 7.75
+    s [string] : "hello"
+    b [boolean] : true
+    date [date] : "2024-07-11"
+    time [time] : "13:45:00"
+    dt [datetime] : "2024-07-11 13:45:00"
+
+    #
+    # Do some value conversions.
+    #
+    on_load [script] :
+
+      # String to integer
+      put '3 third time' into ^.i
+      show ^.i
+
+      # String to decimal
+      put '3.12 more' into ^.d
+      show ^.d
+
+      # String to date
+      put 'now' into ^.dt
+      show ^.dt
+```
+
+See also: Literals.

data/docs/language_scripting.md

@@ -0,0 +1,62 @@
+# Language, Scripting
+
+**Contents**
+
+- Gloo Script Files
+- Gloo Constants
+- Line Continuation
+
+## Gloo Script Files
+
+Gloo scripts are stored in regular text files with the `.gloo` extension.
+
+Conventions:
+
+- Script files are small and composable.
+- Each file contains a single root level object.
+    - There is no system requirement that a file contains only a single object. There can be more than one.
+    - The single-root-object convention means that object hierarchy can better align with files in folders.
+- The root level object has the same name as the file.
+
+```gloo
+#
+# Example of gloo script file.
+#
+hello [can] :
+  on_load [script] : show 'hello world'
+```
+
+## Gloo Constants
+
+There is no gloo language construct for constants. They are simply objects. But by convention, constants are named in all caps. They might be in a container or at the root object level.
+
+```gloo
+#
+# Example of a constant in gloo.
+#
+constants [can] :
+
+  MSG [string] : Hello World!
+
+  on_load [script] :
+    show ^.MSG
+```
+
+## Line Continuation
+
+In gloo scripting, a line continuation is done by ending a line with a backslash (`\`). Logical lines can be split across multiple physical lines of text in scripts. A line break is otherwise an indication of a new statement.
+
+```gloo
+#
+# Example of a continuation character in gloo scripts.
+#
+
+continuation [can] :
+
+  one [string] : Hello
+  two [string] : World!
+
+  on_load [script] :
+    show continuation.one and \
+      ' ' and continuation.two
+```

data/docs/language_syntax.md

@@ -0,0 +1,334 @@
+# Language, Syntax
+
+**Contents**
+
+- Color
+- Errors
+- Events
+- Function Calls
+- Gloo System Objects
+- Here
+- It
+- Operators
+- Pathname
+
+## Color
+
+The following colors can be used by the `show` verb to display colored text:
+
+```gloo
+red
+blue
+green
+white
+black
+yellow
+```
+
+These are the common ones, but any color name from the `colorize` gem works too (e.g. `cyan`, `magenta`, or a `light_` variant of any of the above).
+
+The color names are considered as virtual objects but may also be referenced in variables. See the example below.
+
+```gloo
+#
+# Show multiple messages in color
+#
+colors [can] :
+  var [string] : red
+  on_load [script] :
+    show "red" (colors.var)
+    show "blue" (blue)
+    show "green" (green)
+```
+
+See also: Show.
+
+## Errors
+
+Gloo has a special `error` variable that's not part of the normal object heap. The error will be empty most of the time, but if a command results in an error, this variable will hold the error message until the next command is executed. The error is a string and can be accessed by simply referring to the path-name `error`.
+
+To see the last error:
+
+```
+> show error
+```
+
+To run a command that generates an error:
+
+```
+> put 3 into
+Target (into) missing!
+```
+
+Then, showing the error:
+
+```
+> show error
+Target (into) missing!
+```
+
+But, as mentioned, the next command will clear out the last error. If you need to keep track of the result of a command, you should put the error into another object.
+
+```
+> create err as string
+> put 3 into
+> put error into err
+```
+
+See also: Pathname.
+
+## Events
+
+Scripts can be written to be triggered by events. The current list is as follows, but it is expected that the list of events will grow.
+
+The following events are application and file-level events:
+
+- `on_load` — run when an object loads
+- `on_unload` — run when an object receives an unload message
+- `on_quit` — event triggered when gloo is quitting
+- `on_save` — when an object is saved, this event is triggered
+- `on_reload` — event triggered when an object receives message to reload
+- `on_error` — event triggered when there is an error in the application
+
+Some objects also have events that are triggered as part of their lifecycle. Here are some examples:
+
+- function — `on_invoke`, `after_invoke`
+- server — `on_start`, `on_stop`
+- page — `on_prerender`, `on_render`, `after_render`
+- partial — `on_render`, `after_render`
+
+```gloo
+#
+# Show a message when a file is loaded:
+#
+start [container] :
+    on_load [script] : show "Welcome back!" (white)
+
+
+#
+# Show a message when a file unloaded:
+#
+done [container] :
+    on_unload [script] : show "See ya soon!" (white)
+
+
+#
+# Show a message when gloo is quitting:
+#
+quitting [container] :
+    on_quit [script] : show "Gloo is done for now." (white)
+
+
+#
+# Show a message when an object is going to be saved:
+#
+on_save [script] :
+    show 'This object file is going to saved now.' (yellow)
+
+
+#
+# Show a message when an object is giong to be re-loaded:
+#
+on_reload [script] :
+    show "The object is reloading now."
+
+#
+# Global Error Handler.
+# Include the data container for the error data.
+# The data is populated by the application on error event.
+#
+on_error [script] :
+  tell audit_error.write to run
+
+error_data [can] :
+  message [string] :
+  backtrace [string] :
+```
+
+See also: Load, Reload, Unload, Save, Quit.
+
+## Function Calls
+
+The `invoke` verb (shortcut `~>`) calls a function object (`[ƒ]`) as a standalone command, space-separated params:
+
+```gloo
+invoke functions.add 3 4
+show it
+```
+
+`invoke( ... )` and `~>( ... )` are the inline forms of the same thing — usable anywhere an expression is evaluated (`show`, `put ... into`, `if`, `unless`, `eval`, and more), not just as a standalone command:
+
+```gloo
+show invoke( functions.add 3 4 )
+put ~>( functions.add 3 4 ) into total
+show "Total: " + invoke( functions.add 3 4 )
+if invoke( checks.is_ready ) then show 'ready'
+```
+
+`invoke(...)` and `~>(...)` are exactly equivalent — just the full keyword and its shortcut, same as the standalone verb. Params stay space-separated inside the parens; each one is evaluated as a single token (a literal or object reference), same as the standalone verb — not a multi-token sub-expression, so `invoke( f 3+4 )` won't parse `3+4` as one param.
+
+The parens must immediately follow the keyword with no space (`invoke(`, not `invoke (`) — that's what tells gloo it's a function call rather than `show`'s unrelated trailing `(color)` syntax, which always has a space before the paren.
+
+See also: Color.
+
+## Gloo System Objects
+
+The gloo system objects are virtual objects. That is, they can be accessed like other objects, but the values are set by the system. The values cannot be updated. The other difference is that the virtual objects do not show up in the object heap.
+
+The gloo objects can be accessed through the `gloo` root level virtual object designation. There is also a shortcut for the virtual object path: `$`. For example, to see the current user:
+
+```
+> show gloo.user
+```
+
+Or:
+
+```
+> show $.user
+```
+
+Some objects include an `_` to separate words. As an alternative, a `.` can be used instead. The following commands are treated as identical:
+
+```
+> show gloo.working_dir
+> show gloo.working.dir
+> show $.working_dir
+> show $.working.dir
+```
+
+```
+APP
+gloo.app             # Path of the running app. (Same as gloo.gloo_projects)
+
+IDENTITY
+gloo.hostname         # Get the system hostname.
+gloo.user             # Get the logged in User.
+
+SPECIAL CHARS
+gloo.line             # A carriage return (line feed) character.
+
+FILE SYSTEM
+gloo.user_home        # Get the user's home directory.
+gloo.working_dir      # Get the working directory.
+gloo.gloo_home        # Get the gloo home directory
+gloo.gloo_config      # Get the gloo configuration directory
+gloo.gloo_projects    # Get the gloo projects directory
+gloo.gloo_log         # Get the gloo logging directory
+
+SCREEN
+gloo.screen_lines     # Get the number of lines on screen.
+gloo.screen_cols      # Get the number of columns on screen.
+
+PLATFORM
+gloo.platform_cpu       # Get the platform CPU
+gloo.platform_os        # Get the platform Operating System
+gloo.platform_version   # Get the platform version
+gloo.platform_windows?  # Is the platform Windows?
+gloo.platform_unix?     # Is the platform Unix?
+gloo.platform_linux?    # Is the platform Linux?
+gloo.platform_mac?      # Is the platform Mac?
+gloo.platform_wsl?      # Is the platform WSL (Windows Subsystem for Linux)?
+```
+
+See also: Pathname. The file-system subset of these objects is also referenced in Application > The Gloo Home Directory.
+
+## Here
+
+Gloo scripts can use relative referencing to access objects without specifying the full path. This relative referencing is referred to as the "here" operator, which is a single caret (`^`) character.
+
+Using two carets together (`^^`) means to go up a level — that is, go to the parent container to find the object. Three carets, `^^^`, says to go up yet another level in the object hierarchy.
+
+In the following script, the here reference is used several times:
+
+```gloo
+#
+# Use here reference.
+#
+here [can] :
+  s [str] : local string
+  on_load [script] : show ^.s
+  a [can] :
+    s [str] : A string
+    b [can] :
+      s [str] : B string
+      on_load [script] :
+        show ^.s
+        show ^^.s
+```
+
+A single use of `^` means: refer to an object at the same level as the running script. It tells the interpreter to "look here" for the object.
+
+Use of two `^^` here references means to go up a level, and so forth.
+
+See also: Pathname.
+
+## It
+
+`it` is a special virtual object. `it` contains the value of the last expression or command run. Not all commands result in a change to the value of `it`.
+
+Get the value of an expression and store it somewhere for later use:
+
+```gloo
+#
+# Example of usage of 'it'.
+#
+example [can] :
+  result [int] :
+  on_load [script] :
+    show 3 + 4
+    put it into ^.result
+    show ^.result
+```
+
+Running this script will show `7` twice. The first time will be the result of the addition. The second time will be showing the result object.
+
+See also: Pathname.
+
+## Operators
+
+Operators have their own dedicated page — see the Operators page.
+
+## Pathname
+
+All gloo object data and scripts are stored in a heap of objects, or just "the heap." The heap is hierarchical, with some objects having children objects. To reference an object, we use a "pathname." The pathname starts with the root level object, then has a period, `.`, then the child object name, and so forth. `a.b.c` refers to the `c` object in the `b` container, which is in the `a` container.
+
+### Root & Context
+
+The word "root" is not needed when referring to objects. In some special cases, "root" can be used to point to the first level of the object heap. One such use would be with the "context" verb.
+
+The pathname will start from the root container. When context has been set, the pathname can start from the context container by use of the `@.` prefix. For example:
+
+```gloo
+context [container] :
+  sub [container] :
+    msg [string] : Hello Gloo World!
+    on_load [script] :
+        @ context.sub
+        show @.msg
+        @ root
+```
+
+Full pathnames can be used when context has been set.
+
+### Exceptional Cases
+
+The following are also exceptional pathname cases:
+
+- Here
+- It
+- Errors
+- Gloo System Objects
+
+Here is an example of objects and a pathname reference to an object within the hierarchy:
+
+```gloo
+#
+# Hierarchical containers.
+#
+a [can] :
+  b [can] :
+    c [string] : Hello World
+on_load [script] : show a.b.c
+```
+
+See also: Context, Object Naming.

data/docs/objects.md

@@ -0,0 +1,77 @@
+# Objects
+
+Everything in gloo is an object. Strings, numbers, containers, scripts, functions, dates — even the folder-like structures that hold your code — are all objects, and they're all accessed and manipulated the same way: by sending them messages.
+
+Gloo ships with a large set of built-in object types, and core libraries and extensions can add more. This page doesn't try to cover them all — it walks through three common ones to get a feel for how objects work. For the complete list of object types, and every message each one supports, use the in-app help: enter `help` (or `?`), then `objects` to list them all, or `object {name}` for detail on one (see Application, Help).
+
+**Contents**
+
+- String
+- Container
+- Integer
+
+## String
+
+A string holds text. Beyond just storing a value, a string object responds to messages that transform or inspect it:
+
+```gloo
+s [can] :
+  msg [string] : Hello World!
+  on_load [script] :
+    show s.msg
+    tell s.msg to up
+    show s.msg
+    tell s.msg to size
+    show it
+```
+
+Sending `up` to the string converts it to uppercase, in place. Sending `size` puts the character count into `it`. There are messages for lowercasing, counting words and lines, checking prefixes/suffixes, encoding, and generating random strings (UUIDs, hex, alphanumeric) — see the in-app help for the full list.
+
+## Container
+
+A container holds other objects — it's the closest thing gloo has to a folder, a hash, or a struct. Any object nested inside a container is reachable through a dotted pathname:
+
+```gloo
+can [can] :
+  data [can] :
+    1 : one
+    2 : two
+    3 : three
+  on_load [script] :
+    tell can.data to count
+    show it
+```
+
+`can.data` is itself a container holding three children; `count` puts the number of children into `it`. Because containers can nest arbitrarily, this is how gloo builds up everything from simple config blocks to entire applications.
+
+## Integer
+
+An integer holds a numeric value and responds to a handful of convenience messages:
+
+```gloo
+#
+# Integer object.
+#
+i [can] :
+  x [integer] : 0
+  on_load [script] :
+    show i.x
+    tell i.x to inc
+    show i.x
+    put i.x * 10 into i.x
+    show i.x
+
+    # Show a random number
+    tell ^.x to randomize
+    show 'Random number (up to 100 by default): ' + ^.x
+
+    tell ^.x to randomize(6)
+    tell ^.x to inc
+    show '6-sided dice: ' + ^.x
+```
+
+`inc`/`dec` step the value by one; `randomize` sets it to a random number in a range (0 by default, or up to a given maximum — handy for things like rolling a die).
+
+---
+
+These three barely scratch the surface — decimals, booleans, dates, files, functions, and many more object types are all documented in-app. Enter `help` (or `?`), then `objects` to browse them. (This page itself is also viewable in-app: `help> doc objects`.)