STklos Reference Manual : (version 2.10)

10. STklos Customization

10.1. Parameter Objects

STklos environement can be customized using Parameter Objects. These parameters are listed below.

STklos procedure

(real-precision)
(real-precision value)

This parameter object allows changing the default precision used to print real numbers.

By precision when printing a number we mean the number of significant digits — that is, excluding the leading and trailing zeros in decimal representation. (This is exactly the same as the number for the g specifier for printf in the C language).

(real-precision)         => 15
(define f 0.123456789)
(display f)              => 0.123456789
(real-precision 3)
(display f)              => 0.123
(display   1.123456789)  => 1.12
(display  12.123456789)  => 12.1
(display 123.123456789)  => 123.0

In the last example, only three significant digits were printed (123), and the zero only marks this number as inexact.

If the number won’t fit using the usual decimal format, it will be printed in scientific notation, but still using the specified number of significant digits:

(display     1234.123456789) => 1.23e+03
(display    12345.123456789) => 1.23e+04
(display 12345678.123456789) => 1.23e+07

Repeating the three examples above with precision equal to one results in the following.

(real-precision 1)
(display     1234.123456789) => 1e+03
(display    12345.123456789) => 1e+04
(display 12345678.123456789) => 1e+07

If the number is only printed up to its n-th digit, then the printed nth digit will be n rounded up or down, according to the digit that comes after it.

(real-precision 4)
(display 12.123456789) => 12.12  ;; "123..." rounded to "12"
(display 12.987654321) => 12.99  ;; "987..." rounded to "99"

STklos procedure

(accept-srfi-169-numbers)
(accept-srfi-169-numbers value)

This parameter object permits to change the behavior of the reader with underscores in numbers. Numbers with underscores are defined in ,(link-srfi 169). By default, this variable is true, meaning that underscores are accepted in numbers.

(accept-srfi-169-numbers)        => #t
(symbol? '1_000_000)             => #f
(number? '1_000_000)             => #t
(accept-srfi-169-numbers #f)
(symbol? '1_000_000)             => #t
(number? '1_000_000)             => #f

STklos procedure

(read-case-sensitive)
(read-case-sensitive value)

This parameter object permits to change the default behaviour of the read primitive used on the current input port , when reading a symbol. If this parameter has a true value a symbol is not converted to a default case when interned. Since R⁷RS requires that symbol are case insignificant, the default value of this parameter is #t.

This parameter works on the current input port only and cannot change read beahviour’s globally.
See also syntax for special characters in symbols.

STklos procedure

(write-pretty-quotes)
(write-pretty-quotes value)

This parameter object permits to change the default behaviour of the display or write primitives when they write a list which starts with the symbol quote, quasiquote, unquote or unquote-splicing. If this parameter has a false value, the writer uses the list notation instead of a more human-readable value. By default, this parameter value is set to #t.

(let ((x ''a))
  (display x)
  (display " ")
  (write-pretty-quotes #f)
  (display x))               |- 'a (quote a)

STklos procedure

(load-path)
(load-path value)

load-path is a parameter object. It returns the current load path. The load path is a list of strings which correspond to the directories in which a file must be searched for loading. Directories of the load path are ,(emph "prepended") (in their apparition order) to the file name given to load or try-load until the file can be loaded.

The initial value of the current load path can be set from the shell, by setting the STKLOS_LOAD_PATH shell variable.

Giving a value to the parameter load-path permits to change the current list of paths.

STklos procedure

(load-suffixes)
(load-suffixes value)

load-suffixes is a parameter object. It returns the list of possible suffixes for a Scheme file. Each suffix, must be a string. Suffixes are appended (in their apparition order) to a file name is appended to a file name given to load or try-load until the file can be loaded.

STklos procedure

(load-verbose)
(load-verbose value)

load-verbose is a parameter object. It permits to display the path name of the files which are loaded by load or try-load on the current error port, when set to a true value. If load-verbose is set to #f, no message is printed.

STklos procedure

(thread-handler-error-show)
(thread-handler-error-show value)

When an untrapped error occurs in a thread, it produces an uncaught exception which can finally be trapped when the thread is joined. Setting the thread-handler-error-show parameter permits to see error message as soon as possible, even without joining the thread. This makes debugging easier. By default, this parameter is set to #t.

STklos procedure

(stklos-debug-level)

stklos-debug-level is a parameter objet. It permits to know the current debugging level. The default value of this parameter is 0 (meaning "no debug"). Note that the debugging level can also be set by the --debug option of the stklos(1) command.

10.2. Environment variables

The following variables can be used to customize STklos:

STKLOS_LOAD_PATH: This is a colon-separated list of directories in which stklos looks for loading files. It is used by primitives such as load or try-load. See also the load-path parameter.
STKLOS-FRAME: This variable must contains an integer which indicates the number of frames printed on an error. Use the value 0 for an unlimited backtrace.
STKLOS-CONFDIR: This variable can be used to designate the directory used by STklos to store its configuration or packages files. If not set, the default STklos configuration directory is by default ${XDG_CONFIG_HOME}/stklos (or ~/.config/stklos if the shell variable XDG_CONFIG_HOME is unset).

10.3. REPL

By default, the STklos REPL try to find an installed editing line library to read input expressions. It tries to link with GNU readline [Readline] or BSD libedit [Libedit] libraries. Line editing offers editing capabilities while the user is entering the line (navigation in the line, in the history and function or file completion).

STklos procedure

(repl)
(repl :in inport :out outport :err errport)

This procedure launches a new Read-Eval-Print-Loop. Calls to repl can be embedded. The ports used for input/output as well as the error port can be passed when repl is called. If not passed, they default to current-input-port, current-output-port and current-error-port.

10.3.1. REPL commands

By default, STklos accepts some special commands. A command starts with a comma character, followed by the name of the command. The list of available commands is given below.

,backtrace (or ,bt): Show the stack when last error occurred
,cd: Change current directory
,quit (or ,q): Exit STklos
,time (or ,t ): Print the time used to run the next expression
,describe (or ,d): Describe an object
,expand (or ,e): Pretty print the macro expansion of a form
,import (or ,i): Import a library
,require-feature (or ,r): Require a feature
,open (or ,o): Open file or URL
,browse (or ,b): Browse file or URL with the default browser
,manual (or ,m): Search reference manual
,apropos (or ,a): Search symbols containing a given string
,version (or ,v): Show version
,help (or ,? or *,h): Show help on REPL command with parameter. With a parameter, display the help of this parameter

Furthermore, the '!' character can also be used to execute an external command using sh(1). For instance,

stklos> !pwd
/tmp/test
stklos> !emacs foo.stk &   ;; to launch emacs on file foo.stk
stklos> (define !pwd 100)
;; !pwd
stklos> !pwd               ;; now !pwd overrides pwd(1)
100
stklos>

STklos procedure

(repl-add-command names doc func)

Add a new command to the REPL. The names of the command are given in the first parameter as a list (or a symbol if there is only one name). The documentation of the command is given as a string as the second parameter. Finally, the function given as the third parameter is called when the new command is executed by the user. The code hereafter, permits to add a command to call an editor, with the commands ,editor or ,ed followed (eventually) by a file name.

(repl-add-command '(editor ed)
                 "Edit a file with $EDITOR (or emacs if unset)"
                 (lambda ()
                   (let ((cmd (or (getenv "EDITOR") "emacs")))
                     (system (string-append cmd " " (read-line) " 2>/dev/null")))))

STklos has already a number of commands defined, but repl-add-command can be useful to define your own commrand. A good place to add such a definition is in the stklosrc file.

10.3.2. REPL variables

By default, STklos defines the following variables:

@1, @2, @3, @4 and @5 contains five the last REPL’s computed values
@ is an alias on @1 (the last value computed by the REPL)
@* contains a list of @1, @2, @3, @4 and @5 values

stklos> (values 'a 'b 'c 'd 'e)
a
b
c
d
e
stklos> @*
(a b c d e)
stklos> (+ 2 3)
5
stklos> @*
(5 (a b c d e) a b c)

10.3.3. REPL parameters

The following parameter objects can be used to customize the REPL:

STklos procedure

(repl-theme)
(repl-theme plist)
(repl-theme name)

The STklos REPL colors can be customized using a property list (or a theme name) using the repl-theme parameter. The properties that can be used in this property list are:

#:error for the color of error messages
#:prompt for the color of the prompt
#:help-prompt for the color of the help prompt
#:help for the color of the help messages
#:repl-depth for the color of the depth indicator for recursive REPLs
#:info for the color of information messages.

There are three default themes:

classic which is the (colorful) default theme.
monochrome which doesn’t use colors
minimal where only the prompt and errors are colored.

Colors are expressed using the conventions of the ansi-color primitive. For instance:

(key-set! (repl-theme) :prompt '(bold green)) ;; set the prompt to bold green

(repl-theme 'minimal)                         ;; to use a sober prompt

(repl-theme '(#:error (bold red)              ;; explicitly defined theme
              #:prompt (bold bg-red white)))

A good place to change your theme is the stklosrc file.

STklos procedure

(repl-show-startup-message)
(repl-show-startup-message val)

If this parameter is a true value, a banner is printed when STklos starts in interactive mode. Otherwise, no banner is printed. By default, this parameter is set to #t.

This parameter can be set to #f with the --no-startup-message option of the STklos command. Otherwise, a good place to set this parameter is in the stklosrc file.

1. Documentation about hygienic macros has been stolen in the SLIB manual

1. In fact define-module on a given name defines a new module only the first time it is invoked on this name. By this way, interactively reloading a module does not define a new entity, and the other modules which use it are not altered.

2. This transcript uses the default toplevel loop which displays the name of the current module in the evaluator prompt.

1. Under Unix, you can simply connect to a listening socket with the telnet of netcat command. For the given example, this can be achieved with netcat localhost 12345

2. Port 13, if open, can be used for testing: making a connection to it permits to know the distant system’s idea of the time of day.

1. The "pattern matching compiler" has been written by Jean-Marie Geffroy and is part of the Manuel Serrano’s Bigloo compiler since several years [Bigloo]

1. This section is an adaptation of Jeff Dalton’s (J.Dalton@ed.ac.uk) "Brief introduction to CLOS" which can be found at http://www.aiai.ed.ac.uk/~jeff/clos-guide.html