//  SPDX-License-Identifier: GFDL-1.3-or-later
//
//  Copyright © 2000-2024 Erick Gallesio <eg@stklos.net>
//
//           Author: Erick Gallesio [eg@unice.fr]
//    Creation date:  3-Feb-2022 11:16 (eg)

==  STklos Idiosyncrasies

=== STklos libraries

This section describes the standard libraries provided by {{stklos}}.

==== The (scheme ...) Libraries

===== {{rseven}} Small Libraries

{{stklos}} offers all the libraries defined by {{rseven}}:

- base
- case-lambda
- char
- complex
- cxr
- eval
- file
- inexact
- lazy
- load
- process-context
- r5rs
- read
- repl
- time
- write

See the <<R7RS>> document for more information.

===== {{rseven}} Large Libraries

{{stklos}} supports some libraries of the (under development) {{rseven}} Large editions.

For now, supported libraries of the *Red edition* are

- bytevector ({{rsix}} bytevectors)
- box _(srfi 111)_
- charset _(srfi 14)_
- comparator _(srfi 128)_
- generator _(srfi 158)_ -- Red edition included SRFI 121, but it was superseded by SRFI 158.
- hash-table _(srfi 125)_
- ideque _(srfi 134)_
- ilist _(srfi 116)_
- list _(srfi 1)_
- list-queue _(srfi 117)_
- lseq _(srfi 127)_
- set _(srfi 113)_
- sort _(srfi 132)_
- stream _(srfi 41)_
- text _(srfi 135)_
- vector _(srfi 133)_

For now, supported libraries of the *Tangerine edition* are

- bitwise _(srfi 151)_
- bytevector _(scheme bytevector)_- not a SRFI: this one is a chapter from R6RS.
- division _(srfi 141)_
- fixnum _(srfi 143)_
- flonum _(srfi 144)_
- generator _(srfi 158)_
- vector @ _(srfi 160)_

**(scheme bytevector) functions**

Importing `(scheme bytevector)` gives access to the supplemental following
bytevector functions.

{{insertdoc 'bytevector-s8-ref}}
{{insertdoc 'bytevector-s8-set!}}
{{insertdoc 'bytevector-fill!}}
{{insertdoc 'bytevector=?}}
{{insertdoc 'bytevector-sint-set!}}
{{insertdoc 'endianness}}
{{insertdoc 'native-endianness}}

==== The (srfi ...) Libraries

All the SRFI supported by {{stklos}} are placed under
the `srfi` meta library and their name is SRFI number. Hence, to use
the exported symbols of {{quick-link-srfi 1}}, you'll have to import the
`(srfi 1)` library.

See  _<<_srfis>>_ for more information

==== The (stklos ...) Libraries

This section describes the standard libraries which are placed under
the `stklos` meta library. Note that {{stklos}} extensions can add
some libraries in the `stklos` meta library; they will be described in
the extension documentation.

===== (stklos itrie) Library

This library was designed by Jerônimo Pellegrini
(https://github.com/jpellegrini[@jpellegrini]).


IMPORTANT: Small description needed

The symbols exported by `(stklos itrie)` are described below:

{{insertdoc 'alist->fxmapping}}
{{insertdoc 'constant-fxmapping}}
{{insertdoc 'constant-iset}}
{{insertdoc 'fxmapping-adjoin}}
{{insertdoc 'fxmapping-contains?}}
{{insertdoc 'fxmapping-empty?}}
{{insertdoc 'fxmapping-height}}
{{insertdoc 'fxmapping-keys}}
{{insertdoc 'fxmapping-mutable?}}
{{insertdoc 'fxmapping-ref/default}}
{{insertdoc 'fxmapping-size}}
{{insertdoc 'fxmapping-values}}
{{insertdoc 'fxmapping-xor}}
{{insertdoc 'fxmapping?}}
{{insertdoc 'iet>=?}}
{{insertdoc 'iset->list}}
{{insertdoc 'iset-adjoin!}}
{{insertdoc 'iset-any?}}
{{insertdoc 'iset-closed-open-interval}}
{{insertdoc 'iset-contains?}}
{{insertdoc 'iset-copy}}
{{insertdoc 'iset-count}}
{{insertdoc 'iset-delete-all!}}
{{insertdoc 'iset-delete-max!}}
{{insertdoc 'iset-disjoint?}}
{{insertdoc 'iset-empty?}}
{{insertdoc 'iset-every?}}
{{insertdoc 'iset-filter!}}
{{insertdoc 'iset-find}}
{{insertdoc 'iset-fold-right}}
{{insertdoc 'iset-for-each}}
{{insertdoc 'iset-height}}
{{insertdoc 'iset-map}}
{{insertdoc 'iset-max}}
{{insertdoc 'iset-member}}
{{insertdoc 'iset-mutable?}}
{{insertdoc 'iset-partition!}}
{{insertdoc 'iset-remove!}}
{{insertdoc 'iset-search!}}
{{insertdoc 'iset-size}}
{{insertdoc 'iset-unfold}}
{{insertdoc 'iset-xor!}}
{{insertdoc 'iset?}}
{{insertdoc 'isubset>=}}
{{insertdoc 'list->iset}}
{{insertdoc 'make-range-iset}}


===== (stklos preproc) Library

IMPORTANT: This library  must be described

=== STklos compiler

{{stklos}} always compiles code into bytecode before executing -- it
is not an interpreter, but a bytecode compiler with an ad-hoc virtual
machine. The compiler is available as a standalone tool, to be
used in shell scripts, and also through primitive procedures.

The command `stklos-compile` compiles a file into {{stklos}} bytecode.
Please refer to its manpage for more information.

Compiling files from Scheme programs can be done with the
`compile-file` procedure.

{{insertdoc 'compile-file}}

==== Compiler flags 


{{stklos}} compiler behaviour can be customized by several parameters. Those parameters are described below.

{{insertdoc 'compiler:time-display}}
{{insertdoc 'compiler:gen-line-number}}
{{insertdoc 'compiler:show-assembly-code}}
{{insertdoc 'compiler:inline-common-functions}}
{{insertdoc 'compiler:source-rewrite}}
{{insertdoc 'compiler:keep-formals}}
{{insertdoc 'compiler:keep-source}}
{{insertdoc 'compiler:unroll-iterations}}
{{insertdoc 'compiler:peephole-optimizer}}

