//  SPDX-License-Identifier: GFDL-1.3-or-later
//
//  Copyright © 2000-2024 Erick Gallesio <eg@stklos.net>
//
//           Author: Erick Gallesio [eg@unice.fr]
//    Creation date: 26-Nov-2000 18:19 (eg)

== STklos Customization


=== Parameter Objects

{{stklos}} environement can be customized using Parameter Objects. These
parameters are listed below.

{{insertdoc 'real-precision}}
[#srfi169]
{{insertdoc 'accept-srfi-169-numbers}}
{{insertdoc 'read-case-sensitive}}
{{insertdoc 'write-pretty-quotes}}
(((STKLOS_LOAD_PATH)))
[#loadpath]
{{insertdoc 'load-path}}
(((STKLOS_LOAD_SUFFIXES)))
{{insertdoc 'load-suffixes}}
{{insertdoc 'load-verbose}}
{{insertdoc 'thread-handler-error-show}}
{{insertdoc 'stklos-debug-level}}

=== Environment variables

The following variables can be used to customize {{stklos}}:


- ((("STKLOS_LOAD_PATH")))**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,load>>` or `<<tryload,try-load>>`.  See also the
  `<<loadpath,load-path>>` parameter.

- (((STKLOS_FRAMES)))**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)))**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).

=== REPL

By default, the (((REPL))){{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).

{{insertdoc 'repl}}


==== 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,

```scheme
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>
```




{{insertdoc 'repl-add-command}}

==== 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

```scheme
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)
```

==== REPL parameters

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

{{insertdoc 'repl-theme}}
{{insertdoc 'repl-show-startup-message}}
