Skip to content

Instantly share code, notes, and snippets.

@draegtun
Last active May 15, 2017 10:06
Show Gist options
  • Save draegtun/ee3cbad6d400e2f964370a94a2d83f3f to your computer and use it in GitHub Desktop.
Save draegtun/ee3cbad6d400e2f964370a94a2d83f3f to your computer and use it in GitHub Desktop.
User and Console wiki draft

User and Console

see: https://github.com/r3n/reboldocs/wiki/User-and-Console

This documents the changes to User & Console experience in Ren/C branch of Rebol 3.

Console

This is Rebol's REPL (Read-Eval-Print-Loop). Simply running Rebol from command-line without any options will start the console:

$ r3
Rebol 3 (Ren/C branch) [version: 2.102.0.2.5 build: 13-May-2017/18:49:15]

Welcome to the Rebol console.  For more information please type in the commands below:

  HELP    - For starting information
  ABOUT   - Information about your Rebol
  CHANGES - What's different about this version

>>

NB. At anytime can you enter q to quit console.

For more start-up information use --about option:

$ r3 --about
**************************************************************************
**                                                                      **
**  REBOL 3.0 (Ren-C branch)                                            **
**                                                                      **
**    Copyright: 2012 REBOL Technologies                                **
**    Copyright: 2012-2017 Rebol Open Source Contributors               **
**               Apache 2.0 License, see LICENSE.                       **
**    Website:   http://github.com/metaeducation/ren-c                  **
**                                                                      **
**    Version:   2.102.0.2.5                                            **
**    Platform:  Macintosh osx-x86                                      **
**    Build:     13-May-2017/18:49:15                                   **
**    Commit:    _                                                      **
**                                                                      **
**    Language:  English                                                **
**    Locale:    United Kingdom                                         **
**    Home:      /home/baz/                                             **
**    Resources: /home/baz/.rebol/                                      **
**    Console:   default                                                **
**                                                                      **
**************************************************************************

Welcome to the Rebol console.  For more information please type in the commands below:

  HELP    - For starting information
  ABOUT   - Information about your Rebol
  CHANGES - What's different about this version

>>

And you can increase verbosity of start-up messages using --verbose:

$ r3 --verbose
Loading boot extensions...
Starting console...

Rebol 3 (Ren/C branch) [version: 2.102.0.2.5 build: 13-May-2017/18:49:15]

Welcome to the Rebol console.  For more information please type in the commands below:

  HELP    - For starting information
  ABOUT   - Information about your Rebol
  CHANGES - What's different about this version

Console skinning:

  Skin does not exist - /home/baz/.rebol/console-skin.reb (CONSOLE not updated)

>>

NB. You can combine --about --verbose options.

On starting console, system/console is set to a prototype console! object. This controls how the console looks, for eg. if you want to change the prompt...

>> system/console/prompt: ">>> "
== ">>> "

>>> 

See Console Skinning for more information about changing the look & feel of the console.

Home & Resources

Note the Home: and Resources: output in --about. From your console you can also do this:

>> system/options/home
== %/home/baz/

>> system/options/resources
== %/home/baz/.rebol/

Now hopefully your Home & Resources show something similar? If either above returned _ for you then this means your Rebol wasn't able to find Resoures directory or fathom out what your Home is!

Home

This will be your Home directory on your machine. In Unix parlance this is where your HOME environment variable points to and usually is something like /home/baz or /Users/baz.

If HOME environment variable is found and directory exists then system/options/home is set to it. If not then it will be _ (blank!)

The environment variables are checked in the following order:

Linux, MacOS, Unix Windows
$HOME %HOME%
%HOMEPATH%

Resources

This is a directory where Rebol resources like modules, start-up scripts, console-skinning files, etc can be kept.

By default its a directory found under Home (system/options/home) with following directory name dependant on platform:

Linux, MacOS, Unix Windows
.rebol/ REBOL/

NB. This directory needs to be created by you!

You can manually override where Rebol looks for this directory by using this command-line option:

--resources /home/baz/code/rebol-dir

This is handy if Rebol is unable to resolve your Home (where system/options/home is set to _).

Console skinning

When Rebol console starts it looks for a %console-skin.reb file in the resources directory. This will be a Rebol script, which if found will be run and if the last expression evaluated is a console! object then this updates system/console. Thus you can use this to skin your console automatically on start.

Note the Console: on --about start-up. This gives gives 4 possible "states":

name description
default Not loaded skin-file script
loaded Skin-file script run but system/console not updated
updated Skin-file script run and system/console updated
error Skin-file produced an error

NB. Also notice that --verbose option provides extra (more human friendly) information on console start-up.

Here is an example %console-skin.reb:

Rebol []    ;; this is optional
    
foo: does [1 + 1]   ;; can create new words, functions, etc
    
print "Running from console-skin!"
    
;;
;; below is last expression and so changes system/console/
    
make console! [
    prompt: "Enter> "
    result: "Rebol= "
]

Now when starting r3 with above skin you would see:

Running from console-skin!
Rebol 3 (Ren/C branch) [version: 2.102.0.2.5 build: 13-May-2017/18:49:15]

Welcome to the Rebol console.  For more information please type in the commands below:

  HELP    - For starting information
  ABOUT   - Information about your Rebol
  CHANGES - What's different about this version

Enter> foo

Rebol= 2

Simple appearance settings

prompt:   {>> }
result:   {== }
warning:  {!! }        
error:    {** }                ;; not used yet
info:     to-string #{e29398}  ;; info sign!
greeting: _                    ;; Line before first prompt.  Prints nothing by default or --quiet

NB. To change in console it's: system/console/prompt: ">" or via %console-skin.reb it's make console! [prompt: ">"]

More advanced configuration

Behaviour methods that can be overridden (see Tips & tricks).

print-prompt 
print-result   
print-warning  
print-error   
print-info   
print-greeting 
print-gap      

Shortcuts

Simple one word shortcuts are available in the console:

>> list-shortcuts
q: [quit]
list-shortcuts: [print system/repl/shortcuts]

This lists all the pre-defined shortcuts, where each word is transformed (and executed) to what it maps to.

Because this happens within the console then these words are still available for general use...

>> :list-shortcuts

above returned nothing because there is no LIST-SHORTCUT word. So lets define it and see what happens...

>> list-shortcuts: 1
== 1

>> list-shortcuts    
!! LIST-SHORTCUTS interpreted by console as: print system/repl/shortcuts
!! use :list-shortcuts to get variable.
q: [quit]
list-shortcuts: [print system/repl/shortcuts]

the console notices you've now defined LIST-SHORTCUTS so gives a little warning but still executes the shortcut...

>> :list-shortcuts
== 1

see you did define LIST-SHORTCUTS :)

And you can define (or change) your own shortcuts like so:

>> system/console/add-shortcut 'd [now]

>> d
== 13-May-2017/22:03:32+1:00

Hooks

Along with shortcuts the console provide two other pre-processor hooks

NB. Below describes the current implementation. This may change slightly in near future!

Input hook

input-hook is a console method which wraps each line of input entered. By default (in console!) it does nothing (gets string and returns it as-is). You can override it in console or, as in this example below, in %console-skin.reb:

make console! [
    input-hook: function [s] [
        parse s [
            ";q" end (s: "quit")
            | {\h} (change/part s {help } 2)
        ]
        s
    ]
]

now...

>> \h red
RED is a tuple of value:255.0.0

>> \hblue
BLUE is a tuple of value:0.0.255

see space not needed after \h. Now time to quit...

>> ;q

Dialect hook

dialect-hook is a console method which wraps the whole (multi-line) code block just before evaluation. This can be used for parsing more complex patterns and for building console dialects. Here's a skin file example again:

TBD --- There is an example in PR #475 but I want to provide better example ---

NB. Hooks concatenate this way: Input-hook -> Shortcut -> Dialect-hook

Tips & tricks

TBD - Write up some clever things todo with Console Skinning (probably on separate page)

Command-line options

List of (switch) options that are new or have changed:

--option description
--resources dir system/options/resources: dir. Dies if dir doesn't exist
--about system/options/about: true
--suppress str system/options/suppress: str (quoted).

Example of --suppress switch options:

--suppress "%console-skin.reb"         ; stops %console-skin.reb start-up
--suppress "%rebol.reb %user.reb"      ; stops %rebol.reb & %user.reb start-up
--suppress "*"                         ; stops ALL startup scripts

NB. Currently there are 3 start-up scripts (see start-up scripts).

system/options

List of options that are new or have changed:

option description
home HOME directory
resources User RESOURCES directory
bin Path to directory where Rebol executable binary lives
suppress Block of start-up files to suppress
loaded Block with full paths to loaded start-up scripts
about Show full info banner (ABOUT) on console start-up if set TRUE

system/user

User defined settings. Currently the following settings are available:

setting default description
name _ User's or login name?
home systems/options/home Users HOME directory
words _
identity see § Prototype email profile
identities [] Email profiles

NB. system/user/home is a copy of system/options/home. They're not tied so you can safely change.

§ - Email pop3, smtp, set net and identities renclib wiki entry for more info

Start-up scripts

The following scripts are run when found (and not suppressed) in the following order:

start-up script when from
%rebol.reb Always system/options/bin
%user.reb Always system/options/resources
%console-skin.reb Console system/options/resources

List of PR's that implemented about changes.

  • #508 - Command-line option improvements
  • #507 - Host-start --verbose changes
  • #502 - Console banner changes
  • #501 - Added DIE, a graceful way to FAIL in host-start
  • #495 - Added back %user.r start-up scrip
  • #489 - Fix system/options/home + other related changes
  • #484 - REPL renamed to CONSOLE
  • #481 - REPL - simple fixes and refactoring
  • #475 - Added REPL object to allow skinning

Tech refs

  • System objects definitions: boot/sysobj.r
  • User-mode start-up code: /src/os/host-start.r
  • User-mode console code: /src/os/host-console.r

Changes from Rebol 2 / R3-Alpha

  • In Rebol 2 & Rebol 3 docs, system/home == HOME environment variable
  • In R3-Alpha system/home == r3 executable path
  • %rebol.r <= %rebol.reb
  • %user.r <= %user.reb
  • Rebol 2 looked for %rebol.r and %user.r in current directory and then directory where executable directory
  • R3-Alpha looked for %rebol.r in current directory
  • Rebol 3 docs suggest it looks for %rebol.r & %user.r in HOME first and then current directory
  • %user.r not implemented in R3-Alpha

Rebol 2 & R3-alpha docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment