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.
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.
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!
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% |
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 _).
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
prompt: {>> }
result: {== }
warning: {!! }
error: {** } ;; not used yet
info: to-string #{e29398} ;; info sign!
greeting: _ ;; Line before first prompt. Prints nothing by default or --quietNB. To change in console it's: system/console/prompt: ">" or via %console-skin.reb it's make console! [prompt: ">"]
Behaviour methods that can be overridden (see Tips & tricks).
print-prompt
print-result
print-warning
print-error
print-info
print-greeting
print-gap
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
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 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 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
TBD - Write up some clever things todo with Console Skinning (probably on separate page)
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).
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 |
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
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 |
- #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
- 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
- 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