# Sagittarius Users' Reference

This document is a manual for Sagittarius, an R6RS/R7RS Scheme implementation. This is for version 0.9.13.

1. Introduction
   1. Overview of Sagittarius
   2. Notations
2. Programming in Sagittarius
   1. Invoking Sagittarius
   2. Writing Scheme scripts
   3. Working on REPL
   4. Writing a library
   5. Compiled cache
   6. Deviation
3. R6RS Libraries
   1. Library form
   2. Top library
   3. Base Library
   4. Unicode
   5. Bytevectors
   6. List utilities
   7. Sorting
   8. Control structures
   9. Records syntactic layer
   10. Records procedural layer
   11. Records inspection
   12. Exceptions
   13. Conditions
   14. I/O condition types
   15. File system
   16. Command-line access and exit values
   17. Arithmetic libraries
   18. Syntax-case
   19. Hashtables
   20. Enumerations
   21. Composite libraries
4. R7RS Support
   1. R7RS library system
   2. R7RS libraries
   3. R7RS-large
5. CLOS
   1. (clos user) -CLOS user APIs
   2. (clos core) - CLOS core library
6. Sagittarius extensions
   1. (sagittarius) - builtin library
   2. (sagittarius control) - control library
   3. (sagittarius ffi) - Foreign Function Interface
   4. (sagittarius filewatch) - Monitoring filesystem
   5. (sagittarius io) - Extra IO library
   6. Sagittarius MOP
   7. (sagittarius object) - Convenient refs and coercion procedures
   8. (sagittarius process) - Process library
   9. (sagittarius reader) - reader macro library
   10. (sagittarius record) - Extra record inspection library
   11. (sagittarius regex) - regular expression library
   12. (sagittarius socket) - socket library
   13. (sagittarius threads) - Thread
   14. (sagittarius timezone) - Timezone
   15. (sagittarius debug) - Debugging support
   16. (sagittarius generators) - Generators
   17. Cryptographic libraries
   18. (sagittarius atomic) - Atomic operation
7. Utility libraries
   1. (archive) - Generic archive interface
   2. (asn.1) - Abstract Syntas Notation One library
   3. (binary data) - Binary data read/write
   4. (binary io) - Binary I/O utilities
   5. (binary pack) - Packing binary data
   6. (util buffer) - Buffer utilities
   7. (util bytevector) - Bytevector utility library
   8. (util concurrent) - Concurrency utilities
   9. (crypto) - Cryptographic library
   10. (dbi) - Database independent access layer
   11. (dbm) - Generic DBM interface
   12. (util deque) - Deque
   13. (util duration) - Duration
   14. (util file) - File operation utility library
   15. (getopt) - Parsing command-line options
   16. (util hashtables) - Hashtable utilities
   17. (util heap) - Heap
   18. (util list) - Extra list utility library
   19. (util logging) - Logging utilities
   20. (math) - Mathematics library
   21. (net mq amqp) - AMQP library
   22. (net http-client) - Modern HTTP client
   23. (net http) - Async HTTP client
   24. (net mq mqtt) - MQTT library
   25. (net oauth) - OAuth library
   26. (net server) - Simple server framework
   27. (net socket) - Modern Socket library
   28. (odbc) - ODBC binding
   29. (peg) - PEG library
   30. (rsa pkcs :5) - Password Based Cryptography library
   31. (rsa pkcs :12) - PKCS#12
   32. (util queue) - Queue
   33. (record builder) - Record builder
   34. (rfc :5322) - Internet message format library
   35. (rfc base32) - Base 32 encode and decode library
   36. (rfc base64) - Base 64 encode and decode library
   37. (rfc cmac) - CMAC library
   38. (rfc hmac) - HMAC library
   39. (rfc http) - HTTP client
   40. (rfc http2) - HTTP/2 client
   41. (rfc http-connections) - HTTP client utilities
   42. (rfc json-pointer) - JSON Pointer
   43. (rfc jwe) - Json Web Encryption
   44. (rfc jwk) - Json Web Key
   45. (rfc jws) - Json Web Signature
   46. (rfc jwt) - Json Web Token
   47. (rfc pem) - PEM format library
   48. (rfc hotp) - HMAC-based One-Time Password library
   49. (rfc totp) - Time-based One-Time Password library
   50. (rfc quoted-printable) - Base 64 encode and decode library
   51. (rfc sftp) - SFTP library
   52. (rfc smtp) - SMTP client
   53. (rfc tls) - TLS protocol library
   54. (rfc uri) - Parse and construct URIs
   55. (rfc uri-template) - URI template
   56. (rfc uuid) - UUID generate library
   57. (rfc websocket) - WebSocket
   58. (rfc x.509) - X.509 certificate utility library
   59. (rfc zlib) - zlib compression library
   60. RPC support framework
   61. (rpc json) - JSON RPC library
   62. (security keystore) - Generic Keystore Access
   63. (security password) - Password policy
   64. (text csv) - Comma separated values parser library
   65. (text html-lite) - Simple HTML document builder library
   66. (text json) -- JSON parser
   67. (text json object-builder) -- JSON object builder/serializer
   68. (text json jmespath) - JMESPath
   69. (text json mutable) - Mutable JSON
   70. (text json pointer) - JSON Pointer
   71. (text json patch) - JSON Patch
   72. (text json schema) - JSON Schema
   73. (text json validator) - JSON validator
   74. (text sxml html-parser) - Flxible HTML parser
   75. (text markdown) -- Markdown parser and converter
   76. (text sxml object-builder) - SXML to Scheme object builder
   77. (text tree) - Lightweight text generation
   78. (text yaml) -- YAML parser
   79. (util timer) - Timer
   80. (tlv) - TLV library
   81. (util treemap) - Treemap
   82. (util vector) - Extra vector utility library
8. Ported libraries
   1. (match) -- Pattern matching
   2. (text parse) - Parsing input stream
   3. (text sxml ssax) - Functional XML parser
   4. (text sxml sxpath) - Functional XML parser
   5. (packrat) -- Packrat parser library
   6. (json) -- JSON parser library
9. Supporting SRFIs
   1. Reader macros for SRFIs
10. Index

# Introduction

This is a users' guide and reference manual of Sagittarius Scheme system. Here I tried to describe the points which are not conformed to R6RS.

The target readers are those who already know Scheme and want to write useful programs in Sagittarius.

## Overview of Sagittarius

Sagittarius is a Scheme script engine; it reads Scheme programs, compiles it on-the-fly and executes it on a virtual machine. Sagittarius conforms the language standard "Revised^6 Report on the Algorithmic Language Scheme" (R6RS), "Revised^7 Report on the Algorithmic Language Scheme" (R7RS), and supports various common libraries defined in "Scheme Requests for Implementation" (SRFI)s.

There are a lot of Scheme implementations and they have different strong and weak points. Sagittarius focuses on "Flexibility" and "Easy to Use". R6RS specifies strict requirements, but sometimes you may think this is too much. For that purpose, Sagittarius has less strictness. There are invocation options that make Sagittarius run on strict RnRS mode.

To avoid to lose portability or write miss-working code, you may want to know what are the non conformed points.

Reader

  Basically reader has 3 modes. One is R6RS mode, one is R7RS mode and the last one is compatible mode. Although, user can modify reader with reader macro. These modes can be switched via `#!r6rs`, `#!r7rs` or `#!compatible`. For more details, see Predefined reader macros.

Miscellaneous

  Redefinition of exported values are allowed on script file. This can be restricted by `-r6` option to run the script strict R6RS mode. Multiple import of the same identifier is allowed. The value which imported at the last will be used.

## Notations

In this manual, each entry is represented like this.

Category foo arg1 arg2

[spec] Description foo ...

Category denotes category of the entry foo. The following category will appear in this manual.

Program

  A command line program

Function

  A Scheme function

Syntax

  A syntax

Auxiliary Syntax

  A auxiliary syntax

Macro

  A macro

Auxiliary Macro

  A auxiliary macro

Library

  A library

Condition Type

  A condition type

Reader Macro

  A reader macro

Class

  A CLOS class

Generic

  A generic function

Method

  A method

For functions, syntaxes, or macros, the the entry may be followed by one or more arguments. In the arguments list, following notations may appear.

arg ...

  Indicates zero or more arguments

:optional x y z
:optional (x x-default) (y y-default) (z z-default)

  Indicates is may take up to three optional arguments. The second form specifies default values for x, y and z.

The description of the entry follows the entry line. If the specification of the entry comes from some standard or implementation, its origin is noted in the bracket at the beginning of the description. The following origins are noted:

[R6RS]
[R6RS+]

  The entry works as specified in "Revised^6 Report on the Algorithmic Language Scheme.". If it is marked as "[R6RS+]", the entry has additional functionality.

[R7RS]

  The entry works as specified in "Revised^7 Report on the Algorithmic Language Scheme.".

[SRFI-n]
[SRFI-n+]

  The entry works as specified in SRFI-n. If it is marked as "[SRFI-n+]", the entry has additional functionality.

# Programming in Sagittarius

## Invoking Sagittarius

Sagittarius can be used as an independent Scheme interpreter. The interpreter which comes with Sagittarius distribution is a program named `sagittarius`on Unix like environment and `sash` on Windows environment.

Program sagittarius [options] scheme-file arg ...

Invoking sagittarius. If scheme-file is not given, it runs with interactive mode.

Specifying `-r` option with Scheme standard number, currently `6`and `7` are supported, forces to run Sagittarius on strict standard mode. For example, entire script is read then evaluated on R6RS (`-r6` option) mode. Thus macros can be located below the main script.

Detail options are given with option `"-h"`.

For backward compatibility, symbolic link `sash` is also provided on Unix like environment. However this may not exist if Sagittarius is built with disabling symbolic link option.

## Writing Scheme scripts

When a Scheme file is given to `sagittarius`, it bounds an internal variable to list of the remaining command-line arguments which you can get with the `command-line` procedure, then loads the Scheme program. If the first line of scheme-file begins with `"#!"`, then Sagittarius ignores the entire line. This is useful to write a Scheme program that works as an executable script in unix-like systems.

Typical Sagittarius script has the first line like this:

    #!/usr/local/bin/sagittarius

or

    #!/bin/env sagittarius

The second form uses "shell trampoline" technique so that the script works as far as `sagittarius` is in the PATH.

After the script file is successfully loaded, then Sagittarius will process all toplevel expression the same as Perl.

Now I show a simple example below. This script works like `cat(1)`, without any command-line option processing and error handling.

    #!/usr/local/bin/sagittarius
    (import (rnrs))
    (let ((args (command-line)))
      (unless (null? (cdr args))
        (for-each (lambda (file)
    		(call-with-input-file file
    		  (lambda (in)
    		    (display (get-string-all in)))))
    	      (cdr args)))
      0)

If you need to add extra load path in the executing script file, you can also write like this:

    #!/bin/bash
    #|
    # Adding lib directory located in the same directory as this script
    # is located
    DIR=$(dirname "$0")
    exec sagittarius -L${DIR}/lib $0 "$@"
    |#
    ;; Scheme script
    (import (rnrs))

If the script file contains `main` procedure, then Sagittarius execute it as well with one argument which contains all command line arguments. This feature is defined in SRFI-22. So the above example can also be written like the following:

    #!/usr/local/bin/sagittarius
    (import (rnrs))
    (define (main args)
      (unless (null? (cdr args))
        (for-each (lambda (file)
    		(call-with-input-file file
    		  (lambda (in)
    		    (display (get-string-all in)))))
    	      (cdr args)))
      0)

NOTE: the `main` procedure is called after all toplevel expressions are executed.

## Working on REPL

If `sagittarius` does not get any script file to process, then it will go in to REPL (read-eval-print-loop). For developers' convenience, REPL imports some libraries by default such as `(rnrs)`.

If `.sashrc` file is located in the directory indicated `HOME` or `USERPROFILE` environment variable, then REPL reads it before evaluating user input. So developer can pre-load some more libraries, instead of typing each time.

NOTE: `.sashrc` is only for REPL, it is developers duty to load all libraries on script file.

## Writing a library

Sagittarius provides 2 styles to write a library, one is R6RS style and other one is R7RS style. Both styles are processed the same and users can use it without losing code portability.

Following example is written in R6RS style, for the detail of `library` syntax please see the R6RS document described in bellow sections.

    (library (foo)
      (export bar)
      (import (rnrs))

     (define bar 'bar) )

The library named `(foo)` must be saved the file named `foo.scm`, `foo.ss`, `foo.sls` or `foo.sld` (I use `.scm` for all examples) and located on the loading path, the value is returned by calling `add-load-path` with 0 length string.

### Library file extensions

The file extension also controls the reader mode.

`.ss` and `.sls`

  When a file with one of the extensions is loaded during library importing, then `#!r6rs` directive is applied to the target file by default.

`.sld`

  When a file has this extensions, then `#!r7rs` directive is applied to the target file by default.

`.scm`

  This file extension uses `#!compatible` directive.

If the loading file contains other directive, then the default directive is overwritten.

If you want to write portable code yet want to use Sagittarius specific functionality, then you can write implementation specific code separately using `.sagittarius.scm`, `.sagittarius.ss`, `.sagittarius.sls` or `.sagittarius.sld` extensions. This functionality is implemented almost all R6RS implementation. If you use R7RS style library syntax, then you can also use `cond-expand` to separate implementation specific functionalities.

### Hidden library

If you don't want to share a library but only used in specific one, you can write both in one file and name the file you want to show. For example;

    (library (not showing)
      ;; exports all internal use procedures
      (export ...)
      (import (rnrs))
    ;; write procedures
    ...
    )

    (library (shared)
      (export shared-procedure ...)
      (import (rnrs) (not showing))
    ;; write shared procedures here
    )

Above script must be saved the file named `shared.scm`. The order of libraries are important. Top most dependency must be the first and next is second most, so on.

Note: This style can hide some private procedures however if you want to write portable code, some implementations do not allow you to write this style.

## Compiled cache

For better starting time, Sagittarius caches compiled libraries. The cache files are stored in one of the following environment variables;

For Unix like (POSIX) environment:

- `SAGITTARIUS_CACHE_DIR`

- `HOME`

For Windows environment:

- `SAGITTARIUS_CACHE_DIR`

- `TEMP`

- `TMP`

Sagittarius will use the variables respectively, so if the `SAGITTARIUS_CACHE_DIR` is found then it will be used.

The caching compiled file is carefully designed however the cache file might be stored in broken state. In that case use `-c` option with `sagittarius`, then it will wipe all cache files. If you don't want to use it, pass `-d` option then Sagittarius won't use it.

Adding `#!nocache` directive to a library file would disable caching of the file. This is sometimes useful especially if you need importing time information, e.g. loading path, which is not available if the library is loaded from a cache.

## Deviation

Some of the behaviours are not compliant or deviate from other implementations. Here, we list some of them.

### Macro expansion

The following code will print `#t` instead of `#f` with `-r6`command line option or doing it on a library:

    (import (rnrs) (for (rnrs eval) expand))

    (define-syntax foo
      (lambda(ctx)
        (syntax-case ctx ()
          ((_ id)
           (free-identifier=?
    	#'id
    	(eval '(datum->syntax #'k 'bar) (environment '(rnrs))))))))

    (define bar)

    (display (foo bar))

This is because, Sagittarius doesn't have separated phases of macro expansion and compilation. When `foo` is expanded, then the `bar` is not defined yet or at least it's not visible during the macro expansion. So, both _bar_s are not bound, then `free-identifier=?` will consider them the same identifiers.

### Directives

On R6RS, symbol starts with `#!` is ignored, however this is not the case on R7RS. Sagittarius ignores these symbols on both mode.

# R6RS Libraries

Sagittarius works with library even toplevel expressions are belong to a library named `"user"`. Here I list up all R6RS libraries. Some libraries contain the same procedure ie. assoc which is in `(rnrs (6))` and `(srfi :1 lists)`. In this case I will put a pointer to other library's section.

If library specifies its version, Sagittarius, however, ignores it. This behaviour may change in future.

## Library form

Syntax library name export-clause import-clause body

Declare a library named name.

name uniquely identifies a library and is globally visible in the `import` clauses of all other libraries. It must have the following form:

    (_identifier1 identifier2_ ... _version_)

where version is empty or has the following form: `(_sub-version_ ...)`An export-clause names a set of imported and locally defined bindings to be exported. It must have following form:

    (export _export-spec_ ...)

export-spec must have one of the following forms:

- `_identifier_`

- `(rename (_identifier1 identifier2_) ...)`

In an export-spec, an identifier names a single binding defined within or imported into the library, where the external name for the export is the same as the name of the binding within the library. A `rename` spec exports the binding named by identifier1 in each `(_identifier1 identifier2_)` pairing, using identifier2 as the external name.

import-clause specifies a set of bindings to be imported into the library. It must have the following form:

    (import _import-spec_ ...)

Each import-spec specifies a set of bindings to be imported into the library. An import-spec must be one of the following:

- import-set

- `(for _import-set_ _import-level_ ...)`

An import-level is one of the following:

- `run`

- `expand`

- `(meta _level_)`

where level represents an exact integer object.

Note: The levels will be ignored on Sagittarius. The macro expansion phase will be automatically resolved. For portable code, it is better to specify the proper level.

An import-set names a set of bindings from another library and possibly specifies local names for the imported bindings. It must be one of the following:

- reference

- `(library _reference_)`

- `(only _import-set_ _identifier_ ...)`

- `(except _import-set_ _identifier_ ...)`

- `(prefix _import-set_ _identifier_)`

- `(rename _import-set_ (_identifier1 identifier2_) ...)`

A reference identifies a library by its name and optionally by its version. It must have one of the following forms:

- `(_identifier1 identifier2_ ...)`

- `(_identifier1 identifier2_ ... _version_)`

Note: Sagittarius ignores version.

A reference whose first identifier is `for, library, only, except, prefix` or `rename` is permitted only within a `library` import-set. The import-set`(library _reference_)` is otherwise equivalent to reference.

By default, all of an imported library's exported bindings are made visible within an importing library using the names given to the bindings by the imported library. The precise set of bindings to be imported and the names of those bindings can be adjusted with the `only, except, prefix` and `rename` forms described below.

- An `only` form produces a subset of the bindings from another import-set, including only the listed _identifier_s. The included _identifier_s should be in the original import-set.

- An `except` form produces a subset of the bindings from another import-set, including all but the listed _identifier_s. All of the excluded _identifier_s should be in the original import-set.

- A `prefix` form adds the identifier prefix to each name from another import-set.

- A `rename` form `(rename _identifier1 identifier2_ ...)`, removes the bindings for identifier1 ... to form an intermediate import-set, then adds the bindings back for the corresponding identifier2 ... to form the final import-set. Each identifier1 should be the original import-set, each identifier2 should not be int the intermediate import-set, and the identifier2's must be distinct.

Note: Sagittarius does not check importing or exporting non-existing or duplicated bindings. So the following code is actually valid.

    (library (foo)
      (export bar)
      (import (rename (rnrs) (define def) (not-exist define) (define def)))
     (def bar)
    )

## Top library

Library (rnrs (6))

[R6RS] The library `(rnrs (6))` is required by R6RS. It just export all symbols from the libraries which are listed below.

Most of these libraries documentations are from R6RS specification.

- (rnrs base (6))

- (rnrs unicode (6))

- (rnrs bytevectors (6))

- (rnrs lists (6))

- (rnrs sorting (6))

- (rnrs control (6))

- (rnrs records syntactic (6))

- (rnrs records procedural (6))

- (rnrs records inspection (6))

- (rnrs exceptions (6))

- (rnrs conditions (6))

- (rnrs io ports (6))

- (rnrs io simple (6))

- (rnrs files (6))

- (rnrs programs (6))

- (rnrs arithmetic fixnums (6))

- (rnrs arithmetic flonums (6))

- (rnrs arithmetic bitwise (6))

- (rnrs syntax-case (6))

- (rnrs hashtables (6))

- (rnrs enums (6))

## Base Library

Library (rnrs base (6))

[R6RS] This library exports many of the procedure and syntax bindings that are traditionally associated with Scheme.

### Variable definitions

Syntax define variable expression
Syntax define variable
Syntax define (variable formals) body ...
Syntax define (variable . formal) body ...

[R6RS] The `define` form is a definition used to create variable bindings and may appear anywhere other definitions may appear.

The first from of `define` binds variable to a new location before assigning the value of expression to it.

    (define add3 (lambda (x) (+ x 3)))

    (add3 3)

6

    (define first car)

    (first '(1 2))

1

The second form of `define` is equivalent to

    (define _variable_ _unspecified_)

where unspecified is a side-effect-free expression returning an unspecified value.

In the third form of `define`, formals must be either a sequence of zero or more variables, or a sequence of one or more variables followed by a dot `.` and another variable. This form is equivalent to

    (define _variable_ (lambda (_formals_) _body ..._))

In the fourth form of `define`, formal must be a single variable. This form is equivalent to

    (define _variable_ (lambda _formal_ _body ..._))

### Syntax definitions

Syntax define-syntax keyword expression

[R6RS] The `define-syntax` form is a definition used to create keyword bindings and may appear anywhere other definitions may appear.

Binds keyword to the value of expression, which must evaluate, at macro-expansion time, to a transformer.

### Quotation

Syntax quote datum

[R6RS] `quote` evaluates to the datum value represented by datum.

    (quote a)

a

    (quote #(a b c))

#(a b c)

    (quote (+ 1 2))

(+ 1 2)

### Procedures

Syntax lambda formals body ...

[R6RS+]A `lambda` expression evaluates to a procedure. The environment in effect when the lambda expression is evaluated is remembered as part of the procedure. When the procedure is later called with some arguments, the environment in which the `lambda` expression was evaluated is extended by binding the variables in the parameter list to fresh locations, and the resulting argument values are stored in those locations. Then, the expressions in the body of the `lambda` expression are evaluated sequentially in the extended environment. The results of the last expression in the body are returned as the results of the procedure call.

    (lambda (x) (+ x x))

a procedure

    ((lambda (x) (+ x x)) 4)

8

    ((lambda (x)
       (define (p y) (+ y 1))
       (+ (p x) x)) 5)

11

    (define reverse-subtract (lambda (x y) (- y x)))

    (reverse-subtract 7 10)

3

    (define add4 (let ((x 4)) (lambda (y) (+ x y))))

    (add4 6)

10

Formals must have one of the following forms:

- (<variable1> ...) The procedure takes a fixed number of arguments; when the procedure is called, the arguments are stored in the bindings of the corresponding variables.

- <variable> The procedure takes any number of arguments; when the procedure is called, the sequence of arguments is converted into a newly allocated list, and the list is stored in the binding of the <variable>.

- (<variable1> ... <variablen> . <variablen+1>) If a period `.` precedes the last variable, then the procedure takes n or more arguments, where n is the number of parameters before the period (there must be at least one). The value stored in the binding of the last variable is a newly allocated list of the arguments left over after all the other arguments have been matched up against the other parameters.

      ((lambda x x) 3 4 5 6)

  (3 4 5 6)

      ((lambda (x y . z) z)  3 4 5 6)

  (5 6)
  Any variable must not appear more than once in formals.

- (<variable> ... <extended-spec> ...)

  Extended argument specification. Zero or more variables that specifies required formal argument, followed by an <extended-spec>, a list begginning with a keyword `:optional`, `:key` or `:rest`. The <extended-spec> part consists of the optional argument spec, the keyword argument spec and the rest argument spec. They can appear in any combinations.

  `:optional _optspec_ ...`

    ecifies optional arguments. Each optspec can be either one of the following forms:

        _variable_

        (_variable_ _init-expr_)

    The variable names the formal argument, which is bound to the value of the actual argument if given, or the value of the expression init-expr otherwise. If optspec is just a variable, and the actual argument is not given, then it will be unspecified value. The expression init-expr is only evaluated if the actual argument is not given. The scope in which init-expr is evaluated includes the preceding formal arguments.

        ((lambda (a b :optional (c (+ a b))) (list a b c)) 1 2)

    (1 2 3)

        ((lambda (a b :optional (c (+ a b))) (list a b c)) 1 2 -1)

    (1 2 -1)

        ((lambda (a b :optional c) (list a b c)) 1 2)

    (1 2 #\<unspecified>)

        ((lambda (:optional (a 0) (b (+ a 1))) (list a b)))

    (1 2)
    The procedure raises an `&serious` if more actual arguments than the number of required and optional arguments are given, unless it also has `:key` or `:rest` arguments spec.

        ((lambda (:optional a b) (list a b)) 1 2 3)

    &serious

        ((lambda (:optional a b :rest r) (list a b r)) 1 2 3)

    (1 2 (3))
    `:key _keyspec_ ... [:allow-other-keys [_variable_]]`

    ecifies keyword arguments. Each keyspec can be one of the following forms.

        _variable_

        (_variable_ _init-expr_)

        ((_keyword_ _variable_) _init-expr_)

        (_variable_ _keyword_ _init-expr_)

    The variable names the formal argument, which is bound to the actual argument given with the keyword of the same name as variable. When the actual is not given, init-expr is evaluated and the result is bound to variable in the second, third and fourth form, or unspecified value is bound in the first form.

        (define f (lambda (a :key (b (+ a 1)) (c (+ b 1)))
              (list a b c)))

        (f 10)

    (10 11 12)

        (f 10 :b 4)

    (10 4 5)

        (f 10 :c 8)

    (10 11 8)

        (f 10 :c 1 :b 3)

    (10 3 1)
    With the third and fourth form you can name the formal argument differently from the keyword to specify the argument.

        ((lambda (:key ((:aa a) -1)) a) ::aa 2)

    2

        ((lambda (:key (a :aa -1)) a) ::aa 2)

    2
    By default, the procedure with keyword argument spec raises `&serious` if a keyword argument with an unrecognized keyword is given. Giving `:allow-other-keys` in the formals suppresses this behaviour. If you give variable after `:allow-other-keys`, the list of unrecognized keywords and their arguments are bound to it.

        ((lambda (:key a) a) :a 1 :b 2)

    &serious

        ((lambda (:key a :allow-other-keys) a) :a 1 :b 2)

    1

        ((lambda (:key a :allow-other-keys z) (list a z)) :a 1 :b 2)

    (1 (b 2))
    When used with `:optional` argument spec, the keyword arguments are searched after all the optional arguments are bound.

        ((lambda (:optional a b :key c) (list a b c)) 1 2 :c 3)

    (1 2 3)

        ((lambda (:optional a b :key c) (list a b c)) :c 3)

    (c 3 #\<unspecified>)

        ((lambda (:optional a b :key c) (list a b c)) 1 :c 3)

    &serious
    `:rest _variable_`

    ecifies the rest argument. If specified without `:optional` argument spec, a list of remaining arguments after required arguments are taken is bound to variable. If specified with `:optional` argument spec, the actual arguments are first bound to required and all optional arguments, and the remaining arguments are bound to variable.

        ((lambda (a b :rest z) (list a b z)) 1 2 3 4 5)

    (1 2 (3 4 5))

        ((lambda (a b :optional c d :rest z) (list a b z)) 1 2 3 4 5)

    (1 2 3 4 (5))

             ((lambda (a b :optional c d :rest z) (list a b z)) 1 2 3)

    (1 2 3 #\<unspecified> ())
    When the rest argument spec is used with the keyword argument spec, both accesses the same list of actual argument -- the remaining arguments after required and optional arguments are taken

        ((lambda (:optional a :rest r :key k) (list a r k)) 1 :k 3)

    (1 (k 3) 3)

### Conditionals

Syntax if test consequent alternate
Syntax if test consequent

[R6RS]An `if` expression is evaluated as follows: first, _test_is evaluated. If it yields a true value, then consequent is evaluated and its values are returned. Otherwise alternate is evaluated and its values are returned. If test yields #f and no alternate is specified, then the result of the expression is unspecified.

### Assignment

Syntax set! variable expression

[R6RS] Expression is evaluated, and the resulting value is stored in the location to which variable is bound. Variable must be bound either in some region enclosing the `set!` expression or at the top level. The result of the `set!` expression is unspecified.

Note: R6RS requires to throw syntax violation if variable refers immutable binding. In Sagittarius, however, it won't throw any error.

### Derived conditionals

Syntax cond clause ...

[R6RS] Each clause must be the form

    (_test_ _expression_ ...)

    (_test_ => _expression_)

    (else _expression_ ...)

The last form can appear only in the last clause.

A `cond` expression is evaluated by evaluating the test expressions of successive clauses in order until one of them evaluates to a true value. When a test evaluates to a true value, then the remaining expressions in its clause are evaluated in order, and the results of the last expression in the clause are returned as the results of the entire `cond` expression. If the selected clause contains only the test and no expressions, then the value of the test is returned as the result. If the selected clause uses the `=>` alternate form, then the expression is evaluated. Its value must be a procedure. This procedure should accept one argument; it is called on the value of the test and the values returned by this procedure are returned by the `cond` expression. If all tests evaluate to #f, and there is no `else` clause, then the conditional expression returns unspecified values; if there is an `else` clause, then its expressions are evaluated, and the values of the last one are returned.

Syntax case clause ...

[R6RS] Key must be an expression. Each clause must have one of the following forms:

    ((_datum_ ...) _expression_ ...)

    (else _expression_ ...)

The last form can appear only in the last clause.

A `case` expression is evaluated as follows. Key is evaluated and its result is compared using `eqv?` against the data represented by the _datums_of each clause in turn, proceeding in order from left to right through the set of clauses. If the result of evaluating key is equivalent to a datum of a clause, the corresponding expressions are evaluated from left to right and the results of the last expression in the clause are returned as the results of the `case` expression. Otherwise, the comparison process continues. If the result of evaluating key is different from every datum in each set, then if there is an `else` clause its expressions are evaluated and the results of the last are the results of the `case` expression; otherwise the `case` expression returns unspecified values.

Syntax and test ...

[R6RS] If there are no tests, #t is returned. Otherwise, the test expressions are evaluated from left to right until a _test_returns #f or the last test is reached. In the former case, the and expression returns #f without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values are returned.

    (and (= 2 2) (> 2 1))

#t

    (and (= 2 2) (< 2 1))

    (and 1 2 'c '(f g))

(f g)

    (and)

#t
Syntax or test ...

[R6RS] If there are no tests, #f is returned. Otherwise, the _test_expressions are evaluated from left to right until a test returns a true value or the last test is reached. In the former case, the or expression returns val without evaluating the remaining expressions. In the latter case, the last expression is evaluated and its values are returned.

    (or (= 2 2) (> 2 1))

#t

    (or (= 2 2) (< 2 1))

#t

    (or #f #f #f)

    (or '(b c) (/ 3 0))

(b c)

### Binding constructs

Syntax let bindings body ...

[R6RS] Bindings must have the form

    ((_variable1_ _init1_) ...)

where each init is an expression. Any variable must not appear more than once in the variables.

The inits are evaluated in the current environment, the variables are bound to fresh locations holding the results, the body is evaluated in the extended environment, and the values of the last expression of body are returned. Each binding of a variable has body as its region.

Syntax let* bindings body ...

[R6RS] Bindings must have the form

    ((_variable1_ _init1_) ...)

The `let*` form is similar to `let`, but the inits are evaluated and bindings created sequentially from left to right, with the region of each binding including the bindings to its right as well as body. Thus the second init is evaluated in an environment in which the first binding is visible and initialized, and so on.

Syntax letrec bindings body ...

[R6RS] Bindings must have the form

    ((_variable1_ _init1_) ...)

where each init is an expression. Any variable must not appear more than once in the variables.

The variables are bound to fresh locations, the inits are evaluated in the resulting environment, each variable is assigned to the result of the corresponding init, the body is evaluated in the resulting environment, and the values of the last expression in body are returned. Each binding of a variable has the entire `letrec` expression as its region, making it possible to define mutually recursive procedures.

In the most common uses of `letrec`, all the inits are `lambda`expressions and the restriction is satisfied automatically.

Syntax letrec* bindings body ...

[R6RS] Bindings must have the form

    ((_variable1_ _init1_) ...)

where each init is an expression. Any variable must not appear more than once in the variables.

The variables are bound to fresh locations, each variable is assigned in left-to-right order to the result of evaluating the corresponding init, the body is evaluated in the resulting environment, and the values of the last expression in body are returned. Despite the left-to-right evaluation and assignment order, each binding of a variable has the entire `letrec*`expression as its region, making it possible to define mutually recursive procedures.

Syntax let-values mv-bindings body ...

[R6RS] Mv-bindings must have the form

    ((_formals_ _init1_) ...)

where each init is an expression. Any variable must not appear more than once in the set of formals.

The inits are evaluated in the current environment, and the variables occurring in the formals are bound to fresh locations containing the values returned by the inits, where the formals are matched to the return values in the same way that the formals in a `lambda` expression are matched to the arguments in a procedure call. Then, the body is evaluated in the extended environment, and the values of the last expression of _body_are returned. Each binding of a variable has body as its region. If the formals do not match, an exception with condition type `&assertion`is raised.

Syntax let*-values mv-bindings body ...

[R6RS] Mv-bindings must have the form

    ((_formals_ _init1_) ...)

where each init is an expression. In each formals, any variable must not appear more than once.

The `let*-values` form is similar to `let-values`, but the _inits_are evaluated and bindings created sequentially from left to right, with the region of the bindings of each formals including the bindings to its right as well as body. Thus the second init is evaluated in an environment in which the bindings of the first formals is visible and initialized, and so on.

### Sequencing

Syntax begin form ...
Syntax begin expression ...

[R6RS]The begin keyword has two different roles, depending on its context:

- It may appear as a form in a body , library body, or top-level body, or directly nested in a begin form that appears in a body. In this case, the begin form must have the shape specified in the first header line. This use of begin acts as a splicing form - the forms inside the body are spliced into the surrounding body, as if the begin wrapper were not actually present. A begin form in a body or library body must be non-empty if it appears after the first expression within the body.

- It may appear as an ordinary expression and must have the shape specified in the second header line. In this case, the expressions are evaluated sequentially from left to right, and the values of the last expression are returned. This expression type is used to sequence side effects such as assignments or input and output.

### Equivalence predicates

A `predicate` is a procedure that always returns a boolean value (#t or #f). An `equivalence predicate` is the computational analogue of a mathematical equivalence relation (it is symmetric, reflexive, and transitive). Of the equivalence predicates described in this section, `eq?` is the finest or most discriminating, and `equal?` is the coarsest. The `eqv?` predicate is slightly less discriminating than `eq?`.

Function eq? obj1 obj2
Function eqv? obj1 obj2
Function equal? obj1 obj2

[R6RS] `eq?` only sees if the given two objects are the same object or not, `eqv?` compares numbers. `equal?` compares the values equivalence.

On Sagittarius Scheme interned symbol, keyword(only compatible mode), character, literal string, boolean, fixnum, and '() are used as the same objects. If these objects indicates the same value then `eq?` returns #t.

The following examples are not specified R6RS. But it is always good to know how it works.

    (let ((p (lambda (x) x))) (eqv? p p))

#t

    (eqv? "" "")

#t

    (eqv? "abc" "abc") ;; literal string are the same object

#t

    (eqv? "abc" (list->string '(#\a #\b #\c)))

    (eqv? '#() '#())

    (eqv? (lambda (x) x) (lambda (x) x))

    (eqv? (lambda (x) x) (lambda (y) y))

    (eqv? +nan.0 +nan.0)

### Procedure predicate

Function procedure? obj

[R6RS] Returns #t if obj is a procedure, otherwise returns #f.

### Numerical type predicates

Function number? obj
Function complex? obj
Function real? obj
Function rational? obj
Function integer? obj

[R6RS] These numerical type predicates can be applied to any kind of argument. They return #t if the object is a number object of the named type, and #f otherwise. In general, if a type predicate is true of a number object then all higher type predicates are also true of that number object. Consequently, if a type predicate is false of a number object, then all lower type predicates are also false of that number object.

If z is a complex number object, then `(real? _z_)` is true if and only if `(zero? (imag-part _z_))` and `(exact? (imag-part _z_))`are both true.

If x is a real number object, then `(rational? _x_)` is true if and only if there exist exact integer objects k1 and k2 such that `(= _x_ (/ _k1_ _k2_))` and `(= (numerator _x_) _k1_)`and `(= (denominator _x_) _k2_)` are all true. Thus infinities and NaNs are not rational number objects.

If q is a rational number objects, then `(integer? _q_)` is true if and only if `(= (denominator _q_) 1)` is true. If q is not a rational number object, then `(integer? _q_)` is #f.

Function real-valued? obj
Function rational-valued? obj
Function integer-valued? obj

[R6RS] These numerical type predicates can be applied to any kind of argument. The `real-valued?` procedure returns #t if the object is a number object and is equal in the sense of `=` to some real number object, or if the object is a NaN, or a complex number object whose real part is a NaN and whose imaginary part is zero in the sense of zero?. The `rational-valued?` and `integer-valued?`procedures return #t if the object is a number object and is equal in the sense of `=` to some object of the named type, and otherwise they return #f.

Function exact? obj
Function inexact? obj

[R6RS] These numerical predicates provide tests for the exactness of a quantity. For any number object, precisely one of these predicates is true.

### Generic conversion

Function exact z
Function inexact z

[R6RS] The `inexact` procedure returns an inexact representation of z. If inexact number objects of the appropriate type have bounded precision, then the value returned is an inexact number object that is nearest to the argument.

The `exact` procedure returns an exact representation of z. The value returned is the exact number object that is numerically closest to the argument; in most cases, the result of this procedure should be numerically equal to its argument.

### Arithmetic operations

Function = z1 z2 z3 ...
Function > x1 x2 x3 ...
Function < x1 x2 x3 ...
Function >= x1 x2 x3 ...
Function <= x1 x2 x3 ...

[R6RS] These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, and #f otherwise.

Function zero? z
Function positive? z
Function negative? z
Function odd? z
Function even? z
Function finite? z
Function infinite? z
Function nan? z

[R6RS] These numerical predicates test a number object for a particular property, returning #t or #f.

The `zero?` procedure tests if the number object is `=` to zero.

The `positive?` tests whether it is greater than zero.

The `negative?` tests whether it is less than zero.

The `odd?` tests whether it is odd.

The `even?` tests whether it is even

The `finite?` tests whether it is not an infinity and not a NaN.

The `infinite?` tests whether it is an infinity.

The `nan?` tests whether it is a NaN.

Function max x1 x2 ...
Function min x1 x2 ...

[R6RS] These procedures return the maximum or minimum of their arguments.

Function + z ...
Function * z ...

[R6RS] These procedures return the sum or product of their arguments.

Function - z ...
Function - z1 z2 ...

[R6RS] With two or more arguments, this procedures returns the difference of its arguments, associating to the left. With one argument, however, it returns the additive inverse of its argument.

If this procedure is applied to mixed non-rational real and non-real complex arguments, it returns an unspecified number object.

Function / z ...
Function / z1 z2 ...

[R6RS+] If all of the arguments are exact, then the divisors must all be nonzero. With two or more arguments, this procedure returns the quotient of its arguments, associating to the left. With one argument, however, it returns the multiplicative inverse of its argument.

If this procedure is applied to mixed non-rational real and non-real complex arguments, it returns an unspecified number object.

In R6RS, it requires to raise `&assertion` when the divisor was 0, on Sagittarius, however, it returns NaN or infinite number when it is running with compatible mode. In R6RS mode it raises `&assertion`.

Function abs x

[R6RS] Returns the absolute value of its argument.

Function div-and-mod x1 x2
Function div x1 x2
Function mod x1 x2
Function div0-and-mod0 x1 x2
Function div0 x1 x2
Function mod0 x1 x2

[R6RS] These procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations. In each case, x1 must be neither infinite nor a NaN, and x2 must be nonzero; otherwise, an exception with condition type `&assertion` is raised.

Function gcd n1 ...
Function lcm n1 ...

[R6RS] These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non-negative.

Function numerator q
Function denominator q

[R6RS] These procedures return the numerator or denominator of their argument; the result is computed as if the argument was represented as a fraction in lowest terms. The denominator is always positive. The denominator of 0 is defined to be 1.

Function floor x
Function ceiling x
Function truncate x
Function round x

[R6RS] These procedures return inexact integer objects for inexact arguments that are not infinities or NaNs, and exact integer objects for exact rational arguments. For such arguments, `floor` returns the largest integer object not larger than x. The `ceiling` procedure returns the smallest integer object not smaller than x. The `truncate` procedure returns the integer object closest to x whose absolute value is not larger than the absolute value of x. The `round` procedure returns the closest integer object to x, rounding to even when x represents a number halfway between two integers.

Although infinities and NaNs are not integer objects, these procedures return an infinity when given an infinity as an argument, and a NaN when given a NaN.

Function rationalize x1 x2

[R6RS] The `rationalize` procedure returns the a number object representing the simplest rational number differing from x1 by no more than x2. A rational number r1 is simpler than another rational number r2 if r1 = p1/q1 and r2 = p2/q2 (in lowest terms) and |p1| ≤ |p2| and |q1| ≤ |q2|. Thus 3/5 is simpler than 4/7. Although not all rationals are comparable in this ordering (consider 2/7 and 3/5) any interval contains a rational number that is simpler than every other rational number in that interval (the simpler 2/5 lies between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of all.

Function exp z
Function log z
Function log z1 z2
Function sin z
Function cos z
Function tan z
Function asin z
Function acos z
Function atan z
Function atan z1 z2

[R6RS] These procedures compute the usual transcendental functions. The `exp` procedure computes the base-e exponential of z.

The `log` procedure with a single argument computes the natural logarithm of z (not the base-ten logarithm); `(log _z1_ _z2_)` computes the base-z2 logarithm of z1.

The `asin`, `acos`, and `atan` procedures compute arcsine, arccosine, and arctangent, respectively.

The two-argument variant of `atan` computes `(angle (make-rectangular _x2_ _x1_))`.

Function sqrt z

[R6RS] Returns the principal square root of z. For rational z, the result has either positive real part, or zero real part and non-negative imaginary part.

The sqrt procedure may return an inexact result even when given an exact argument.

Function expt z1 z2

[R6RS] Returns z1 raised to the power z2. For nonzero z1, this is e^{z2 log z1}. 0.0z is 1.0 if z = 0.0, and 0.0 if `(real-part _z_)` is positive. For other cases in which the first argument is zero, an unspecified number object(`+nan.0+nan.0i`) is returned.

For an exact real number object z1 and an exact integer object z2, `(expt _z1_ _z2_)` must return an exact result. For all other values of z1 and z2, `(expt _z1_ _z2_)` may return an inexact result, even when both z1 and z2 are exact.

Function make-rectangular x1 x2
Function make-polar x3 x4
Function real-part z
Function imag-part z
Function magnitude z
Function angle z

[R6RS] Suppose a1, a2, a3, and a4 are real numbers, and c is a complex number such that the following holds:

_c = a1 + a2 ^ i = a3 e ^ ia4_Then, if x1, x2, x3, and x4 are number objects representing a1, a2, a3, and a4, respectively, `(make-rectangular _x1_ _x2_)` returns c, and `(make-polar _x3_ _x4_)` returns c.

### Numerical input and output

Function number->string z :optional radix precision

[R6RS+] Radix must be an exact integer object, between 2, and 32. If omitted, radix defaults to 10. In Sagittarius precision will be ignored. The `number->string` procedure takes a number object and a radix and returns as a string an external representation of the given number object in the given radix such that

    (let ((number _z_) (radix _radix_))
      (eqv? (string->number
              (number->string number radix)
              radix)
            number))

is true.

Function number->string string :optional radix

[R6RS+] Returns a number object with maximally precise representation expressed by the given string. Radix must be an exact integer object, between 2, and 32. If supplied, radix is a default radix that may be overridden by an explicit radix prefix in string (e.g., "#o177"). If radix is not supplied, then the default radix is 10. If string is not a syntactically valid notation for a number object or a notation for a rational number object with a zero denominator, then `string->number`returns #f.

These `number->string` and `string->number`'s resolutions of radix are taken from Gauche.

### Booleans

Function not obj

[R6RS] Returns #t if obj is #f, and returns #f otherwise.

Function boolean? obj

[R6RS] Returns #t if obj is either #t or #f and returns #f otherwise.

Function boolean=? bool1 bool2 bool3 ...

[R6RS] Returns #t if the booleans are the same.

### Pairs and lists

A pair is a compound structure with two fields called the car and cdr fields (for historical reasons). Pairs are created by the procedure `cons`. The car and cdr fields are accessed by the procedures `car` and `cdr`.

Pairs are used primarily to represent lists. A list can be defined recursively as either the empty list or a pair whose cdr is a list. More precisely, the set of lists is defined as the smallest set X such that

- The empty list is in

- If list is in X, then any pair whose cdr field contains _list_is also in X.

The objects in the car fields of successive pairs of a list are the elements of the list. For example, a two-element list is a pair whose car is the first element and whose cdr is a pair whose car is the second element and whose cdr is the empty list. The length of a list is the number of elements, which is the same as the number of pairs.

The empty listis a special object of its own type. It is not a pair. It has no elements and its length is zero.

A chain of pairs not ending in the empty list is called an improper list. Note that an improper list is not a list. The list and dotted notations can be combined to represent improper lists:

    (a b c . d)

is equivalent to

    (a . (b . (c . d)))

Whether a given pair is a list depends upon what is stored in the cdr field.

Function pair? obj

[R6RS] Returns #t if obj is a pair, and otherwise returns #f.

Function cons obj1 obj2

[R6RS] Returns a newly allocated pair whose car is obj1 and whose cdr is obj2. The pair is guaranteed to be different (in the sense of `eqv?`) from every existing object.

Function car pair
Function cdr pair

[R6RS] Returns the contents of the car/cdr field of pair.

Function caar pair
Function cadr pair

:

Function cadddr pair
Function cddddr pair

[R6RS] These procedures are compositions of `car` and `cdr`, where for example `caddr` could be defined by

    (define caddr (lambda (x) (car (cdr (cdr x)))))

.

Arbitrary compositions, up to four deep, are provided. There are twenty-eight of these procedures in all.

Function null? obj

[R6RS] Returns #t if obj is the empty list, #f otherwise.

Function list? obj

[R6RS] Returns #t if obj is a list, #f otherwise. By definition, all lists are chains of pairs that have finite length and are terminated by the empty list.

Function list obj ...

[R6RS] Returns a newly allocated list of its arguments.

Function length list

[R6RS+] Returns the length of list. If the list is improper list, it returns -1 If the list is infinite list , it returns -2.

Function append list ... obj

[R6RS] Returns a possibly improper list consisting of the elements of the first list followed by the elements of the other lists, with _obj_as the cdr of the final pair. An improper list results if obj is not a list.

Function reverse list

[R6RS] Returns a newly allocated list consisting of the elements of list in reverse order.

Function list-tail list k :optaionl fallback

[R6RS+] The `list-tail` procedure returns the subchain of pairs of list obtained by omitting the first k elements. If _fallback_is given and k is out of range, it returns fallback otherwise `&assertion` is raised.

Function list-ref list k :optaionl fallback

[R6RS+] The `list-ref` procedure returns the _k_th element of list. If fallback is given and k is out of range, it returns fallback otherwise `&assertion` is raised.

Function map proc list1 list2 ...

[R6RS+ SRFI-1] The `map` procedure applies proc element-wise to the elements of the lists and returns a list of the results, in order. The order in which proc is applied to the elements of the lists is unspecified. If multiple returns occur from `map`, the values returned by earlier returns are not mutated. If the given lists are not the same length, when the shortest list is processed the `map` will stop.

Function for-each proc list1 list2 ...

[R6RS+ SRFI-1] The `for-each` procedure applies proc element-wise to the elements of the lists for its side effects, in order from the first elements to the last. The return values of `for-each` are unspecified. If the given lists are not the same length, when the shortest list is processed the `for-each` will stop.

### Symbols

Function symbol? obj

[R6RS] Returns #t if obj is a symbol, otherwise returns #f.

Function symbol->string symbol

[R6RS] Returns the name of symbol as an immutable string.

Function symbol=? symbol1 symbol2 symbol3 ...

[R6RS] Returns #t if the symbols are the same, i.e., if their names are spelled the same.

Function string->symbol string

[R6RS] Returns the symbol whose name is string.

### Characters

Characters are objects that represent Unicode scalar values.

Function char? obj

[R6RS] Returns #t if obj is a character, otherwise returns #f.

Function char->integer char
Function integer->char sv

[R6RS] Sv must be a Unicode scalar value, i.e., a non-negative exact integer object in [0, #xD7FF] ∪ [#xE000, #x10FFFF].

Given a character, `char->integer` returns its Unicode scalar value as an exact integer object. For a Unicode scalar value sv, `integer->char`returns its associated character.

Function char=? char1 char2 char3 ...
Function char<? char1 char2 char3 ...
Function char>? char1 char2 char3 ...
Function char<=? char1 char2 char3 ...
Function char>=? char1 char2 char3 ...

[R6RS] These procedures impose a total ordering on the set of characters according to their Unicode scalar values.

### Strings

Strings are sequences of characters. The length of a string is the number of characters that it contains. This number is fixed when the string is created. The valid indices of a string are the integers less than the length of the string. The first character of a string has index 0, the second has index 1, and so on.

Function string? obj

[R6RS] Returns #t if obj is a string, otherwise returns #f.

Function make-string k :optional char

[R6RS] Returns a newly allocated string of length k. If _char_is given, then all elements of the string are initialized to char, otherwise the contents of the string are `#\space`.

These are equivalence:

    (make-string 10)

(code (make-string 10 #\\space))
Function string char ...

[R6RS] Returns a newly allocated string composed of the arguments.

Function string-length string

[R6RS] Returns the number of characters in the given string as an exact integer object.

Function string-ref string k :optional fallback

[R6RS+] The `string-ref` procedure returns character. If a third argument is given ant k is not a valid index, it returns fallback, otherwise raises `&assertion`.

k of string using zero-origin indexing.

Function string=? string1 string2 string3 ...

[R6RS] Returns #t if the strings are the same length and contain the same characters in the same positions. Otherwise, the `string=?` procedure returns #f.

Function string<? string1 string2 string3 ...
Function string>? string1 string2 string3 ...
Function string<=? string1 string2 string3 ...
Function string>=? string1 string2 string3 ...

[R6RS] These procedures are the lexicographic extensions to strings of the corresponding orderings on characters. For example, `string<?` is the lexicographic ordering on strings induced by the ordering `char<?` on characters. If two strings differ in length but are the same up to the length of the shorter string, the shorter string is considered to be lexicographically less than the longer string.

Function substring string start end

[R6RS] String must be a string, and start and end must be exact integer objects satisfying

0 ≤ start ≤ end ≤ `(string-length _string_)`.

The `substring` procedure returns a newly allocated string formed from the characters of string beginning with index start (inclusive) and ending with index end (exclusive).

Function string-append string ...

[R6RS] Returns a newly allocated string whose characters form the concatenation of the given strings.

Function string->list string
Function list->string list

[R6RS+] List must be a list of characters.

The `string->list` procedure returns a newly allocated list of the characters that make up the given string.

The `list->string` procedure returns a newly allocated string formed from the characters in list.

The `string->list` and `list->string` procedures are inverses so far as `equal?` is concerned.

If optional argument start and end are given, it restrict the conversion range. It convert from start (inclusive) to end(exclusive).

If only start is given, then the end is the length of given string.

Function string-for-each proc string1 string2 ...

[R6RS+] Proc should accept as many arguments as there are strings. The `string-for-each` procedure applies proc element-wise to the characters of the strings for its side effects, in order from the first characters to the last. The return values of `string-for-each` are unspecified.

Analogous to for-each.

Function string-copy string :optional (start 0) (end -1)

[R6RS+] Returns a newly allocated copy of the given string.

If optional argument start was given, the procedure copies from the given start index.

If optional argument end was given, the procedure copies to the given end index (exclusive).

### Vectors

Vectors are heterogeneous structures whose elements are indexed by integers. A vector typically occupies less space than a list of the same length, and the average time needed to access a randomly chosen element is typically less for the vector than for the list.

The length of a vector is the number of elements that it contains. This number is a non-negative integer that is fixed when the vector is created. The valid indices of a vector are the exact non-negative integer objects less than the length of the vector. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector.

Function vector? obj

[R6RS] Returns #t if obj is a vector. Otherwise returns #f.

Function make-vector k :optional fill

[R6RS] Returns a newly allocated vector of k elements. If a second argument is given, then each element is initialized to fill. Otherwise the initial contents of each element is unspecified.

Function vector obj ...

[R6RS] Returns a newly allocated vector whose elements contain the given arguments. Analogous to `list`.

Function vector-length vector

[R6RS] Returns the number of elements in vector as an exact integer object.

Function vector-ref vector k :optional fallback

[R6RS+] The `vector-ref` procedure returns the contents of element k of vector. If a third argument is given and k is not a valid index, it returns fallback, otherwise raises `&assertion`.

Function vector-ref vector k obj

[R6RS] K must be a valid index of vector. The `vector-set!`procedure stores obj in element k of vector, and returns unspecified values.

It raises `&assertion` when it attempt to modify immutable vector on R6RS mode.

Function vector->list vector :optional start end
Function list->vector list :optional start end

[R6RS+] The `vector->list` procedure returns a newly allocated list of the objects contained in the elements of vector. The `list->vector`procedure returns a newly created vector initialized to the elements of the list list. The optional start and end arguments limit the range of the source.

    (vector->list '#(1 2 3 4 5))

(1 2 3 4 5)

    (list->vector '(1 2 3 4 5))

#(1 2 3 4 5)

    (vector->list '#(1 2 3 4 5) 2 4)

(3 4)

    (list->vector (circular-list 'a 'b 'c) 1 6)

#(b c a b c)
Function vector-fill! vector :optional start end

[R6RS+] Stores fill in every element of vector and returns unspecified values. Optional start and end limits the range of effect between start-th index (inclusive) to end-th index (exclusive). Start defaults to zero, and end defaults to the length of vector.

Function vector-map proc vector1 vactor2 ...

[R6RS+] Proc should accept as many arguments as there are vectors. The `vector-map` procedure applies proc element-wise to the elements of the vectors and returns a vector of the results, in order. If multiple returns occur from `vector-map`, the return values returned by earlier returns are not mutated.

Analogous to `map`.

Function vector-for-each proc vector1 vactor2 ...

[R6RS+] Proc should accept as many arguments as there are vectors. The `vector-for-each` procedure applies proc element-wise to the elements of the vectors for its side effects, in order from the first elements to the last. The return values of `vector-for-each` are unspecified.

Analogous to `for-each`.

### Errors and violations

Function error who message irritant ...
Function assertion-violation who message irritant ...

[R6RS] Who must be a string or a symbol or #f. Message must be a string. The irritants are arbitrary objects.

These procedures raise an exception. The `error` procedure should be called when an error has occurred, typically caused by something that has gone wrong in the interaction of the program with the external world or the user. The `assertion-violation` procedure should be called when an invalid call to a procedure was made, either passing an invalid number of arguments, or passing an argument that it is not specified to handle.

The who argument should describe the procedure or operation that detected the exception. The message argument should describe the exceptional situation. The irritants should be the arguments to the operation that detected the operation.

### Control features

Function apply proc arg1 ... rest-args

[R6RS] Rest-args must be a list. Proc should accept n arguments, where n is number of args plus the length of rest-args. The `apply`procedure calls proc with the elements of the list `(append (list _arg1_ ...) _rest-args_)` as the actual arguments.

If a call to `apply` occurs in a tail context, the call to `proc` is also in a tail context.

Function call-with-current-continuation proc
Function call/cc proc

[R6RS] Proc should accept one argument. The procedure `call-with-current-continuation` (which is the same as the procedure `call/cc`) packages the current continuation as an "escape procedure" and passes it as an argument to proc. The escape procedure is a Scheme procedure that, if it is later called, will abandon whatever continuation is in effect a that later time and will instead reinstate the continuation that was in effect when the escape procedure was created. Calling the escape procedure may cause the invocation of before and after procedures installed using `dynamic-wind`.

The escape procedure accepts the same number of arguments as the continuation of the original call to `call-with-current-continuation`.

Function values obj ...

[R6RS] Returns objs as multiple values.

Function call-with-values producer consumer

[R6RS] Producer must be a procedure and should accept zero arguments. Consumer must be a procedure and should accept as many values as producer returns. The `call-with-values` procedure calls _producer_with no arguments and a continuation that, when passed some values, calls the consumer procedure with those values as arguments. The continuation for the call to consumer is the continuation of the call to `call-with-values`.

If a call to `call-with-values` occurs in a tail context, the call to consumer is also in a tail context.

Function dynamic-wind before thunk after

[R6RS] Before, thunk, and after must be procedures, and each should accept zero arguments. These procedures may return any number of values. The `dynamic-wind` procedure calls thunk without arguments, returning the results of this call. Moreover, `dynamic-wind` calls _before_without arguments whenever the dynamic extent of the call to thunk is entered, and after without arguments whenever the dynamic extent of the call to thunk is exited. Thus, in the absence of calls to escape procedures created by `call-with-current-continuation`, `dynamic-wind` calls before, thunk, and after, in that order.

### Iteration

Syntax let variable bindings body ...

[R6RS] “Named let” is a variant on the syntax of `let` that provides a general looping construct and may also be used to express recursion. It has the same syntax and semantics as ordinary `let` except that _variable_is bound within body to a procedure whose parameters are the bound variables and whose body is body. Thus the execution of body may be repeated by invoking the procedure named by variable.

### Quasiquote

Syntax quasiquote qq-template
Auxiliary Syntax unquote qq-template
Auxiliary Syntax unquote-splicing qq-template

[R6RS] "Quasiquote" expressions is useful for constructing a list or vector structure when some but not all of the desired structure is known in advance.

Qq-template should be as specified by the grammar at the end of this entry.

If no `unquote` or `unquote-splicing` forms appear within the qq-template, the result of evaluating `(quasiquote _qq-template_)`is equivalent to the result of evaluating `(quote _qq-template_)`.

If an `(unquote _expression_ ...)` form appears inside a qq-template, however, the expressions are evaluated `("unquoted")` and their results are inserted into the structure instead of the `unquote` form.

If an `(unquote-splicing _expression_ ...)` form appears inside a qq-template, then the expressions must evaluate to lists; the opening and closing parentheses of the lists are then "stripped away" and the elements of the lists are inserted in place of the `unquote-splicing` form.

Any `unquote-splicing` or multi-operand unquote form must appear only within a list or vector qq-template.

Note: even though `unquote` and `unquote-splicing` are bounded, however it does not work with import prefix nor renamed import. This may be fixed in future.

### Binding constructs for syntactic keywords

The `let-syntax` and `letrec-syntax` forms bind keywords. On R6RS mode it works like a `begin` form, a `let-syntax` or `letrec-syntax`form may appear in a definition context, in which case it is treated as a definition, and the forms in the body must also be definitions. A `let-syntax`or `letrec-syntax` form may also appear in an expression context, in which case the forms within their bodies must be expressions.

Syntax let-syntax bindings form ...

[R6RS] Bindings must have the form

    ((_keyword_ _expression_) ...)

Each keyword is an identifier, and each expression is an expression that evaluates, at macro-expansion time, to a transformer. Transformers may be created by `syntax-rules` or `identifier-syntax` or by one of the other mechanisms described in library chapter on "syntax-case". It is a syntax violation for keyword to appear more than once in the list of keywords being bound.

The forms are expanded in the syntactic environment obtained by extending the syntactic environment of the `let-syntax` form with macros whose keywords are the keywords, bound to the specified transformers. Each binding of a keyword has the forms as its region.

Syntax letrec-syntax bindings form ...

[R6RS] Bindings must have the form

    ((_keyword_ _expression_) ...)

Each keyword is an identifier, and each expression is an expression that evaluates, at macro-expansion time, to a transformer. Transformers may be created by `syntax-rules` or `identifier-syntax` or by one of the other mechanisms described in library chapter on "syntax-case". It is a syntax violation for keyword to appear more than once in the list of keywords being bound.

The forms are expanded in the syntactic environment obtained by extending the syntactic environment of the `letrec-syntax` form with macros whose keywords are the keywords, bound to the specified transformers. Each binding of a keyword has the bindings as well as the forms within its region, so the transformers can transcribe forms into uses of the macros introduced by the `letrec-syntax` form.

Note: The forms of a `let-syntax` and a `letrec-syntax` form are treated, whether in definition or expression context, as if wrapped in an implicit `begin` on R6RS mode, it is, then, treated as if wrapped in an implicit `let` on compatible mode. Thus on compatible mode, it creates a scope.

### Macro transformers

In R6RS, it requires `'_'` `'...'` as bounded symbols but in Sagittarius these are not bound. And if import clause has rename or prefix these auxiliary syntax are not be renamed or prefixed. This behaivour may be fixed in future.

Syntax syntax-rules (literal ... ) rule ...

[R6RS] Each literal must be an identifier. Each rule must have the following form:

    (srpattern template)

An srpattern is a restricted form of pattern, namely, a nonempty pattern in one of four parenthesized forms below whose first subform is an identifier or an underscore `_`. A pattern is an identifier, constant, or one of the following.

- (pattern ...)

- (pattern pattern ... . pattern)

- (pattern ... pattern ellipsis pattern ...)

- (pattern ... pattern ellipsis pattern ... . pattern)

- #(pattern ...)

- #(pattern ... pattern ellipsis pattern ...)

An ellipsis is the identifier `"..."` (three periods).

A template is a pattern variable, an identifier that is not a pattern variable, a pattern datum, or one of the following.

- (subtemplate ...)

- (subtemplate ... . template)

- #(subtemplate ...)

A subtemplate is a template followed by zero or more ellipses.

An instance of `syntax-rules` evaluates, at macro-expansion time, to a new macro transformer by specifying a sequence of hygienic rewrite rules. A use of a macro whose keyword is associated with a transformer specified by `syntax-rules`is matched against the patterns contained in the rules, beginning with the leftmost rule. When a match is found, the macro use is transcribed hygienically according to the template. It is a syntax violation when no match is found.

Syntax identifier-syntax template
Syntax identifier-syntax (id1 template1) (set! id2 pattern) template2

[R6RS] The ids must be identifiers. The templates must be as for `syntax-rules`.

When a keyword is bound to a transformer produced by the first form of `identifier-syntax`, references to the keyword within the scope of the binding are replaced by template.

    (define p (cons 4 5))

    (define-syntax p.car (identifier-syntax (car p)))

    p.car

4

    (set! p.car 15)

&syntax exception

The second, more general, form of `identifier-syntax` permits the transformer to determine what happens when `set!` is used. In this case, uses of the identifier by itself are replaced by template1, and uses of `set!` with the identifier are replaced by template2

    (define p (cons 4 5))

    (define-syntax p.car
      (identifier-syntax
        (_ (car p))
        ((set! _ e) (set-car! p e))))

    (set! p.car 15)

    p.car

15

    p

(15 5)

## Unicode

Library (rnrs unicode (6))

[R6RS] The procedures exported by the `(rnrs unicode (6))`library provide access to some aspects of the Unicode semantics for characters and strings: category information, case-independent comparisons, case mappings, and normalization.

Some of the procedures that operate on characters or strings ignore the difference between upper case and lower case. These procedures have "-ci" (for "case insensitive") embedded in their names.

### Characters

Function char-upcase char
Function char-downcase char
Function char-titlecase char
Function char-foldcase char

[R6RS] These procedures take a character argument and return a character result. If the argument is an upper-case or title-case character, and if there is a single character that is its lower-case form, then `char-downcase`returns that character. If the argument is a lower-case or title-case character, and there is a single character that is its upper-case form, then `char-upcase`returns that character. If the argument is a lower-case or upper-case character, and there is a single character that is its title-case form, then `char-titlecase`returns that character. If the argument is not a title-case character and there is no single character that is its title-case form, then `char-titlecase`returns the upper-case form of the argument. Finally, if the character has a case-folded character, then `char-foldcase` returns that character. Otherwise the character returned is the same as the argument. For Turkic characters İ (#\x130) and ı (#\x131), `char-foldcase` behaves as the identity function; otherwise `char-foldcase` is the same as `char-downcase` composed with `char-upcase`.

Function char-ci=? char1 char2 char3 ...
Function char-ci>? char1 char2 char3 ...
Function char-ci<? char1 char2 char3 ...
Function char-ci>=? char1 char2 char3 ...
Function char-ci<=? char1 char2 char3 ...

[R6RS] These procedures are similar to `char=?`, etc., but operate on the case-folded versions of the characters.

Function char-alphabetic? char
Function char-numeric? char
Function char-whitespace? char
Function char-upper-case? char
Function char-lower-case? char
Function char-title-case? char

[R6RS] These procedures return #t if their arguments are alphabetic, numeric, whitespace, upper-case, lower-case, or title-case characters, respectively; otherwise they return #f.

A character is alphabetic if it has the Unicode "Alphabetic" property. A character is numeric if it has the Unicode "Numeric" property. A character is whitespace if has the Unicode "White_Space" property. A character is upper case if it has the Unicode "Uppercase" property, lower case if it has the "Lowercase" property, and title case if it is in the Lt general category.

Function char-general-category char

[R6RS] Returns a symbol representing the Unicode general category of char, one of Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd, Nl, No, Ps, Pe, Pi, Pf, Pd, Pc, Po, Sc, Sm, Sk, So, Zs, Zp, Zl, Cc, Cf, Cs, Co, or Cn.

### Strings

Function string-upcase string start end
Function string-downcase string start end
Function string-titlecase string start end
Function string-foldcase string start end

[R6RS+][SRFI-13] These procedures take a string argument and return a string result. They are defined in terms of Unicode's locale-independent case mappings from Unicode scalar-value sequences to scalar-value sequences. In particular, the length of the result string can be different from the length of the input string. When the specified result is equal in the sense of `string=?` to the argument, these procedures may return the argument instead of a newly allocated string.

The `string-upcase` procedure converts a string to upper case; `string-downcase` converts a string to lower case.

The `string-foldcase` procedure converts the string to its case-folded counterpart, using the full case-folding mapping, but without the special mappings for Turkic languages.

The `string-titlecase` procedure converts the first cased character of each word via `char-titlecase`, and downcases all other cased characters.

If the optional argument start and end are given, these must be exact integer and the procedures will first substring the given string with range start and end then convert it.

Function string-ci=? string1 string2 string3 ...
Function string-ci>? string1 string2 string3 ...
Function string-ci<? string1 string2 string3 ...
Function string-ci>=? string1 string2 string3 ...
Function string-ci<=? string1 string2 string3 ...

[R6RS] These procedures are similar to `string=?`, etc., but operate on the case-folded versions of the strings.

Function string-nfd string
Function string-nfkd string
Function string-nfc string
Function string-nfkc string

[R6RS] These procedures take a string argument and return a string result, which is the input string normalized to Unicode normalization form D, KD, C, or KC, respectively. When the specified result is equal in the sense of `string=?`to the argument, these procedures may return the argument instead of a newly allocated string.

## Bytevectors

Many applications deal with blocks of binary data by accessing them in various ways-extracting signed or unsigned numbers of various sizes. Therefore, the `(rnrs bytevectors (6))`library provides a single type for blocks of binary data with multiple ways to access that data. It deals with integers and floating-point representations in various sizes with specified endianness.

Bytevectorsare objects of a disjoint type. Conceptually, a bytevector represents a sequence of 8-bit bytes. The description of bytevectors uses the term byte for an exact integer object in the interval { - 128, ..., 127} and the term octet for an exact integer object in the interval {0, ..., 255}. A byte corresponds to its two's complement representation as an octet.

The length of a bytevector is the number of bytes it contains. This number is fixed. A valid index into a bytevector is an exact, non-negative integer object less than the length of the bytevector. The first byte of a bytevector has index 0; the last byte has an index one less than the length of the bytevector.

Generally, the access procedures come in different flavors according to the size of the represented integer and the endianness of the representation. The procedures also distinguish signed and unsigned representations. The signed representations all use two's complement.

Like string literals, literals representing bytevectors do not need to be quoted:

    #vu8(12 23 123)

#vu8(12 23 123)
Library (rnrs bytevectors (6))

[R6RS] This library provides a single type for blocks of binary data with multiple ways to access that data.

### General operations

Macro endianness symbol

[R6RS] The name of symbol must be a symbol describing an endianness. `(endianness _symbol_)` evaluates to the symbol named symbol. Whenever one of the procedures operating on bytevectors accepts an endianness as an argument, that argument must be one of these symbols. It is a syntax violation for symbol to be anything other than an endianness symbol supported by the Sagittarius.

Currently, Sagittarius supports these symbols; `big`, `little`and `native`.

Function native-endianness

[R6RS] Returns the endianness symbol associated platform endianness. This may be a symbol either big or little.

Function bytevector? obj

[R6RS] Returns #t if obj is a bytevector, otherwise returns #f.

Function make-bytevector k :optional fill

[R6RS] Returns a newly allocated bytevector of k bytes.

If the fill argument is missing, the initial contents of the returned bytevector are 0.

If the fill argument is present, it must be an exact integer object in the interval {-128, ..., 255} that specifies the initial value for the bytes of the bytevector: If fill is positive, it is interpreted as an octet; if it is negative, it is interpreted as a byte.

Function bytevector-length bytevector

[R6RS] Returns, as an exact integer object, the number of bytes in bytevector.

Function bytevector=? bytevector1 bytevector2

[R6RS] Returns #t if bytevector1 and bytevector2 are equal-that is, if they have the same length and equal bytes at all valid indices. It returns #f otherwise.

Function bytevector-fill! bytevector fill :optional start end

[R6RS+] The fill argument is as in the description of the `make-bytevector` procedure. The `bytevector-fill!` procedure stores fill in every element of bytevector and returns unspecified values. Analogous to `vector-fill!`.

If optional arguments start or end is given, then the procedure restricts the range of filling from start to end (exclusive) index of bytevector. When end is omitted then it uses the length of the given bytevector.

Function bytevector-copy! source source-start target target-start k

[R6RS] Source and target must be bytevectors. Source-start, target-start, and k must be non-negative exact integer objects that satisfy

0 <= source-start <= source-start + k <= _source-length_0 <= target-start <= target-start + k <= _target-length_where source-length is the length of source and _target-length_is the length of target.

The `bytevector-copy!` procedure copies the bytes from source at indices

source-start, ... source-start + k - 1

to consecutive indices in target starting at target-index.

This returns unspecified values.

Function bytevector-copy bytevector _

_ :optional (start 0) (end -1)

[R6RS+] Returns a newly allocated copy of bytevector.

If optional argument start was given, the procedure copies from the given start index.

If optional argument end was given, the procedure copies to the given end index (exclusive).

### Operation on bytes and octets

Function bytevector-u8-ref bytevector k
Function bytevector-s8-ref bytevector k

[R6RS] K must be a valid index of bytevector.

The `bytevector-u8-ref` procedure returns the byte at index k of bytevector, as an octet.

The `bytevector-s8-ref` procedure returns the byte at index k of bytevector, as a (signed) byte.

Function bytevector-u8-set! bytevector k octet
Function bytevector-s8-set! bytevector k byte

[R6RS] K must be a valid index of bytevector.

The `bytevector-u8-set!` procedure stores octet in element _k_of bytevector.

The `bytevector-s8-set!` procedure stores the two's-complement representation of byte in element k of bytevector.

Both procedures return unspecified values.

Function bytevector->u8-list bytevector
Function u8-list->bytevector bytevector

[R6RS] List must be a list of octets.

The `bytevector->u8-list` procedure returns a newly allocated list of the octets of bytevector in the same order.

The `u8-list->bytevector` procedure returns a newly allocated bytevector whose elements are the elements of list list, in the same order. It is analogous to `list->vector`.

### Operations on integers of arbitary size

Function bytevector-uint-ref bytevector k endianness size
Function bytevector-sint-ref bytevector k endianness size
Function bytevector-uint-set! bytevector k n endianness size
Function bytevector-sint-set! bytevector k n endianness size

[R6RS] Size must be a positive exact integer object. K, ..., k + size - 1 must be valid indices of bytevector.

The `bytevector-uint-ref` procedure retrieves the exact integer object corresponding to the unsigned representation of size size and specified by endianness at indices k, ..., k + size - 1.

The `bytevector-sint-ref` procedure retrieves the exact integer object corresponding to the two's-complement representation of size size and specified by endianness at indices k, ..., k + size - 1.

For `bytevector-uint-set!`, n must be an exact integer object in the interval _{0, ..., 256 ^ "size" - 1}_The `bytevector-uint-set!` procedure stores the unsigned representation of size size and specified by endianness into bytevector at indices k, ..., k + size - 1.

For `bytevector-sint-set!`, n must be an exact integer object in the interval {-256 ^ "size" / 2, ..., 256 ^ "size" / 2 - 1}. `bytevector-sint-set!` stores the two's-complement representation of size size and specified by endianness into bytevector at indices k, ..., k + size - 1.

The `...-set!` procedures return unspecified values.

Function bytevector->uint-list bytevector endianness size
Function bytevector->sint-list bytevector endianness size
Function uint-list->bytevector list endianness size
Function sint-list->bytevector list endianness size

[R6RS] Size must be a positive exact integer object. For `uint-list->bytevector`, list must be a list of exact integer objects in the interval {0, ..., 256 ^ "size" - 1}. For `sint-list->bytevector`, list must be a list of exact integer objects in the interval {-256 ^ "size"/2, ..., 256 ^ "size"/2 - 1}. The length of _bytevector_or, respectively, of list must be divisible by size.

These procedures convert between lists of integer objects and their consecutive representations according to size and endianness in the _bytevector_objects in the same way as `bytevector->u8-list` and `u8-list->bytevector`do for one-byte representations.

### Operation on 16-bit integers

Function bytevector-u16-ref bytevector k endianness
Function bytevector-s16-ref bytevector k endianness
Function bytevector-u16-native-ref bytevector k
Function bytevector-s16-native-ref bytevector k
Function bytevector-u16-set! bytevector k n endianness
Function bytevector-s16-set! bytevector k n endianness
Function bytevector-u16-native-set! bytevector k n
Function bytevector-s16-native-set! bytevector k n

[R6RS] K must be a valid index of bytevector; so must k + 1. For `bytevector-u16-set!` and `bytevector-u16-native-set!`, _n_must be an exact integer object in the interval {0, ..., 2 ^ 16 - 1}. For `bytevector-s16-set!` and `bytevector-s16-native-set!`, _n_must be an exact integer object in the interval {-2 ^ 15, ..., 2 ^ 15 - 1}.

These retrieve and set two-byte representations of numbers at indices _k_and k + 1, according to the endianness specified by endianness. The procedures with `u16` in their names deal with the unsigned representation; those with `s16` in their names deal with the two's-complement representation.

The procedures with `native` in their names employ the native endianness, and work only at aligned indices: k must be a multiple of 2.

The `...-set!` procedures return unspecified values.

### Operation on 32-bit integers

Function bytevector-u32-ref bytevector k endianness
Function bytevector-s32-ref bytevector k endianness
Function bytevector-u32-native-ref bytevector k
Function bytevector-s32-native-ref bytevector k
Function bytevector-u32-set! bytevector k n endianness
Function bytevector-s32-set! bytevector k n endianness
Function bytevector-u32-native-set! bytevector k n
Function bytevector-s32-native-set! bytevector k n

[R6RS] K must be a valid index of bytevector; so must k + 3. For `bytevector-u32-set!` and `bytevector-u32-native-set!`, _n_must be an exact integer object in the interval {0, ..., 2 ^ 32 - 1}. For `bytevector-s32-set!` and `bytevector-s32-native-set!`, _n_must be an exact integer object in the interval {-2 ^ 31, ..., 2 ^ 32 - 1}.

These retrieve and set two-byte representations of numbers at indices _k_and k + 3, according to the endianness specified by endianness. The procedures with `u32` in their names deal with the unsigned representation; those with `s32` in their names deal with the two's-complement representation.

The procedures with `native` in their names employ the native endianness, and work only at aligned indices: k must be a multiple of 4.

The `...-set!` procedures return unspecified values.

### Operation on 64-bit integers

Function bytevector-u64-ref bytevector k endianness
Function bytevector-s64-ref bytevector k endianness
Function bytevector-u64-native-ref bytevector k
Function bytevector-s64-native-ref bytevector k
Function bytevector-u64-set! bytevector k n endianness
Function bytevector-s64-set! bytevector k n endianness
Function bytevector-u64-native-set! bytevector k n
Function bytevector-s64-native-set! bytevector k n

[R6RS] K must be a valid index of bytevector; so must k + 7. For `bytevector-u64-set!` and `bytevector-u64-native-set!`, _n_must be an exact integer object in the interval {0, ..., 2 ^ 64 - 1}. For `bytevector-s64-set!` and `bytevector-s64-native-set!`, _n_must be an exact integer object in the interval {-2 ^ 63, ..., 2 ^ 64 - 1}.

These retrieve and set two-byte representations of numbers at indices _k_and k + 7, according to the endianness specified by endianness. The procedures with `u64` in their names deal with the unsigned representation; those with `s64` in their names deal with the two's-complement representation.

The procedures with `native` in their names employ the native endianness, and work only at aligned indices: k must be a multiple of 8.

The `...-set!` procedures return unspecified values.

### Operation on IEEE-754 representations

Function bytevector-ieee-single-native-ref bytevector k
Function bytevector-ieee-single-ref bytevector k endianness

[R6RS] K, …, k + 3 must be valid indices of bytevector. For `bytevector-ieee-single-native-ref`, k must be a multiple of 4.

These procedures return the inexact real number object that best represents the IEEE-754 single-precision number represented by the four bytes beginning at index k.

Function bytevector-ieee-double-native-ref bytevector k
Function bytevector-ieee-double-ref bytevector k endianness

[R6RS] K, …, k + 7 must be valid indices of bytevector. For `bytevector-ieee-double-native-ref`, k must be a multiple of 8.

These procedures return the inexact real number object that best represents the IEEE-754 double-precision number represented by the four bytes beginning at index k.

Function bytevector-ieee-single-native-set! bytevector k x
Function bytevector-ieee-single-set! bytevector k x endianness

[R6RS] K, …, k + 3 must be valid indices of bytevector. For `bytevector-ieee-single-native-set!`, k must be a multiple of 4.

These procedures store an IEEE-754 single-precision representation of _x_into elements k through k + 3 of bytevector, and return unspecified values.

Function bytevector-ieee-double-native-set! bytevector k x
Function bytevector-ieee-double-set! bytevector k x endianness

[R6RS] K, …, k + 7 must be valid indices of bytevector. For `bytevector-ieee-double-native-set!`, k must be a multiple of 8.

These procedures store an IEEE-754 double-precision representation of _x_into elements k through k + 7 of bytevector, and return unspecified values.

### Operation on strings

This section describes procedures that convert between strings and bytevectors containing Unicode encodings of those strings. When decoding bytevectors, encoding errors are handled as with the replace semantics of textual I/O: If an invalid or incomplete character encoding is encountered, then the replacement character U+FFFD is appended to the string being generated, an appropriate number of bytes are ignored, and decoding continues with the following bytes.

Function string->utf8 string :optional start end

[R6RS+] [R7RS] Returns a newly allocated (unless empty) bytevector that contains the UTF-8 encoding of the given string.

If the optional argument start is given, the procedure converts given string from start index (inclusive).

If the optional argument end is given, the procedure converts given string to end index (exclusive).

These optional arguments must be fixnum if it's given.

Function string->utf16 string :optional endianness

[R6RS] If endianness is specified, it must be the symbol `big`or the symbol `little`. The `string->utf16` procedure returns a newly allocated (unless empty) bytevector that contains the UTF-16BE or UTF-16LE encoding of the given string (with no byte-order mark). If _endianness_is not specified or is `big`, then UTF-16BE is used. If endianness is `little`, then UTF-16LE is used.

Function string->utf32 string :optional endianness

[R6RS] If endianness is specified, it must be the symbol `big`or the symbol `little`. The `string->utf32` procedure returns a newly allocated (unless empty) bytevector that contains the UTF-32BE or UTF-32LE encoding of the given string (with no byte-order mark). If _endianness_is not specified or is `big`, then UTF-32BE is used. If endianness is `little`, then UTF-32LE is used.

Function utf8->string bytevector

[R6RS] Returns a newly allocated (unless empty) string whose character sequence is encoded by the given bytevector.

If the optional argument start is given, the procedure converts given string from start index (inclusive).

If the optional argument end is given, the procedure converts given string to end index (exclusive).

These optional arguments must be fixnum if it's given.

Function utf16->string bytevector endianness :optional endianness-mandatory?

[R6RS] Endianness must be the symbol `big` or the symbol `little`. The `utf16->string` procedure returns a newly allocated (unless empty) string whose character sequence is encoded by the given bytevector. Bytevector is decoded according to UTF-16BE or UTF-16LE: If endianness-mandatory? is absent or #f, `utf16->string` determines the endianness according to a UTF-16 BOM at the beginning of _bytevector_if a BOM is present; in this case, the BOM is not decoded as a character. Also in this case, if no UTF-16 BOM is present, endianness specifies the endianness of the encoding. If endianness-mandatory? is a true value, _endianness_specifies the endianness of the encoding, and any UTF-16 BOM in the encoding is decoded as a regular character.

Function utf32->string bytevector endianness :optional endianness-mandatory?

[R6RS] Endianness must be the symbol `big` or the symbol `little`. The `utf32->string` procedure returns a newly allocated (unless empty) string whose character sequence is encoded by the given bytevector. Bytevector is decoded according to UTF-32BE or UTF-32LE: If endianness-mandatory? is absent or #f, `utf32->string` determines the endianness according to a UTF-32 BOM at the beginning of _bytevector_if a BOM is present; in this case, the BOM is not decoded as a character. Also in this case, if no UTF-32 BOM is present, endianness specifies the endianness of the encoding. If endianness-mandatory? is a true value, _endianness_specifies the endianness of the encoding, and any UTF-32 BOM in the encoding is decoded as a regular character.

## List utilities

Library (rnrs lists (6))

[R6RS] The `(rnrs lists (6))`library, which contains various useful procedures that operate on lists.

Function find proc list

[R6RS] Proc should accept one argument and return a single value. Proc should not mutate list. The `find` procedure applies _proc_to the elements of list in order. If proc returns a true value for an element, find immediately returns that element. If proc returns #f for all elements of the list, find returns #f.

Function for-all pred list1 list2 ...

[R6RS+] Applies pred across each element of lists, and returns #f as soon as pred returns #f. If all application of pred return a non-false value, `for-all` returns the last result of the applications.

Function exists pred list1 list2 ...

[R6RS+] Applies pred across each element of lists, and returns as soon as pred returns a non-false value. The return value of any is the non-false value pred returned. If lists are exhausted before _pred_returns a non-false value, #f is returned.

Note: R6RS requires the same length list for `for-all` and `exists`. On Sagittarius, however, these can accept different length list and it will finish to process when the shortest list is finish to process.

Function filter proc list
Function partition proc list

[R6RS] Proc should accept one argument and return a single value.

The `filter` procedure applies proc to each element of list and returns a list of the elements of list for which proc returned a true value. The `partition` procedure also applies proc to each element of list, but returns two values, the first one a list of the elements of _list_for which proc returned a true value, and the second a list of the elements of list for which proc returned #f. In both cases, the elements of the result list(s) are in the same order as they appear in the input list. If multiple returns occur from `filter` or `partitions`, the return values returned by earlier returns are not mutated.

Function fold-left combine nil list1 list2 ...

[R6RS+] Combine must be a procedure. It should accept one more argument than there are lists and return a single value. It should not mutate the list arguments. The `fold-left` procedure iterates the _combine_procedure over an accumulator value and the elements of the lists from left to right, starting with an accumulator value of nil. More specifically, `fold-left` returns nil if the lists are empty. If they are not empty, combine is first applied to nil and the respective first elements of the lists in order. The result becomes the new accumulator value, and combine is applied to the new accumulator value and the respective next elements of the list. This step is repeated until the end of the list is reached; then the accumulator value is returned.

Function fold-right combine nil list1 list2 ...

[R6RS+] Combine must be a procedure. It should accept one more argument than there are lists and return a single value. Combine should not mutate the list arguments. The `fold-right` procedure iterates the combine procedure over the elements of the lists from right to left and an accumulator value, starting with an accumulator value of nil. More specifically, `fold-right` returns nil if the lists are empty. If they are not empty, combine is first applied to the respective last elements of the lists in order and nil. The result becomes the new accumulator value, and combine is applied to the respective previous elements of the lists and the new accumulator value. This step is repeated until the beginning of the list is reached; then the accumulator value is returned.

Note: R6RS requires the same length list for `fold-left` and `fold-right`. On Sagittarius, however, these can accept different length list and it will finish to process when the shortest list is finish to process.

Function remp proc list
Function remove obj list
Function remv obj list
Function remq obj list

[R6RS] Proc should accept one argument and return a single value. _Proc_should not mutate list.

Each of these procedures returns a list of the elements of list that do not satisfy a given condition. The `remp` procedure applies proc to each element of list and returns a list of the elements of list for which proc returned #f. The `remove`, `remv`, and `remq` procedures return a list of the elements that are not obj. The `remq` procedure uses `eq?` to compare obj with the elements of list, while `remv` uses `eqv?` and `remove` uses `equal?`. The elements of the result list are in the same order as they appear in the input list. If multiple returns occur from `remp`, the return values returned by earlier returns are not mutated.

Function memp proc list
Function member obj list :optional =
Function memv obj list
Function memq obj list

[R6RS+] Proc should accept one argument and return a single value. Proc should not mutate list.

These procedures return the first sublist of list whose car satisfies a given condition, where the sublists of lists are the lists returned by `(list-tail _list_ _k_)` for k less than the length of list. The `memp` procedure applies proc to the cars of the sublists of list until it finds one for which proc returns a true value. The `member`, `memv`, and `memq` procedures look for the first occurrence of obj. If list does not contain an element satisfying the condition, then #f (not the empty list) is returned. The `member` procedure uses `equal?` or if = is given use it to compare obj with the elements of list, while `memv` uses `eqv?` and `memq` uses `eq?`.

Function assp proc alist
Function assc obj alist :optional =
Function assv obj alist
Function assq obj alist

[R6RS+] Alist (for "association list") should be a list of pairs. Proc should accept one argument and return a single value. _Proc_should not mutate alist.

These procedures find the first pair in alist whose car field satisfies a given condition, and returns that pair without traversing alist further. If no pair in alist satisfies the condition, then #f is returned. The `assp` procedure successively applies proc to the car fields of alist and looks for a pair for which it returns a true value. The `assoc`, `assv`, and `assq` procedures look for a pair that has obj as its car. The `assoc` procedure uses `equal?` or if _=_is given use it to compare obj with the car fields of the pairs in alist, while `assv` uses `eqv?` and `assq` uses `eq?`.

Note: `member` and `assoc` procedures are the same behaviour as SRFI-1.

Function cons* obj1 obj2 ...

[R6RS] Like `list`, but the last argument provides the tail of the constructed list.

## Sorting

Library (rnrs sorting (6))

The `(rnrs sorting (6))`library provides procedures for sorting lists and vectors.

Function list-sort proc list
Function vector-sort proc vector :optional (start 0) (end (vector-length vector))

[R6RS+][SRFI-132] Proc should accept any two elements of list or vector. Proc should return a true value when its first argument is strictly less than its second, and #f otherwise.

The `list-sort` and `vector-sort` procedures perform a stable sort of list or vector in ascending order according to proc, without changing list or vector in any way. The `list-sort` procedure returns a list, and `vector-sort` returns a vector. The results may be `eq?` to the argument when the argument is already sorted, and the result of `list-sort` may share structure with a tail of the original list. The sorting algorithm performs O(n lg n) calls to proc where n is the length of list or vector, and all arguments passed to proc are elements of the list or vector being sorted, but the pairing of arguments and the sequencing of calls to proc are not specified. If multiple returns occur from `list-sort` or `vector-sort`, the return values returned by earlier returns are not mutated.

If the optional argument start and end for `vector-sort`is specified, then the sorting range is restricted by the given start(inclusive) and end (exclusive).

Function vector-sort! proc vector :optional (start 0) (end (vector-length vector))

[R6RS+][SRFI-132] Proc should accept any two elements of the vector, and should not have any side effects. Proc should return a true value when its first argument is strictly less than its second, and #f otherwise.

The `vector-sort!` procedure destructively sorts vector in ascending order according to proc.

If the optional argument start and end is specified, then the sorting range is restricted by the given start (inclusive) and end (exclusive).

## Control structures

Library (rnrs control (6))

The `(rnrs control (6))`library, which provides useful control structures.

Syntax when test expression ...
Syntax unless test expression ...

[R6RS] Test must be an expression.

A `when` expression is evaluated by evaluating the test expression. If test evaluates to a true value, the remaining expressions are evaluated in order, and the results of the last expression are returned as the results of the entire `when` expression. Otherwise, the `when`expression returns unspecified values. An `unless` expression is evaluated by evaluating the test expression. If test evaluates to #f, the remaining expressions are evaluated in order, and the results of the last expression are returned as the results of the entire `unless`expression. Otherwise, the `unless` expression returns unspecified values.

Syntax do ((variable init step) ... ) (test expression ... ) commend

[R6RS] The inits, steps, tests, and commands must be expressions. The variables must be pairwise distinct variables.

The `do` expression is an iteration construct. It specifies a set of variables to be bound, how they are to be initialized at the start, and how they are to be updated on each iteration.

A `do` expression is evaluated as follows: The init expressions are evaluated (in some unspecified order), the variables are bound to fresh locations, the results of the init expressions are stored in the bindings of the variables, and then the iteration phase begins.

Each iteration begins by evaluating test if the result is #f, then the commands are evaluated in order for effect, the step expressions are evaluated in some unspecified order, the variables are bound to fresh locations holding the results, and the next iteration begins.

If test evaluates to a true value, the expressions are evaluated from left to right and the values of the last expression are returned. If no expressions are present, then the `do` expression returns unspecified values.

The region of the binding of a variable consists of the entire `do`expression except for the inits.

A step may be omitted, in which case the effect is the same as if (variable init variable) had been written instead of (variable init).

    (do ((vec (make-vector 5))
          (i 0 (+ i 1)))
         ((= i 5) vec)
      (vector-set! vec i i))

#(0 1 2 3 4)

    (let ((x '(1 3 5 7 9)))
      (do ((x x (cdr x))
            (sum 0 (+ sum (car x))))
           ((null? x) sum)))

25

Syntax case-lambda case-lambda-clause ...

[R6RS] Each case-lambda-clause must be of the form

    (_formals_ _body_)

Formals must be as in a `lambda` form.

A `case-lambda` expression evaluates to a procedure. This procedure, when applied, tries to match its arguments to the `case-lambda-clauses` in order. The arguments match a clause if one of the following conditions is fulfilled:

Formals has the form `(_variable_ ...)` and the number of arguments is the same as the number of formal parameters in formals.

Formals has the form

    (_variable1_ ... _variablen_ . _variablen+1_)

and the number of arguments is at least n.

Formals has the form variable.

For the first clause matched by the arguments, the variables of the _formals_are bound to fresh locations containing the argument values in the same arrangement as with `lambda`.

The last expression of a body in a `case-lambda` expression is in tail context.

If the arguments match none of the clauses, an exception with condition type `&assertion` is raised.

## Records syntactic layer

Library (rnrs records syntactic (6))

The `(rnrs records syntactic (6))`library. Some details of the specification are explained in terms of the specification of the procedural layer below.

Macro define-record-type name-spec record-clase ...
Auxiliary syntax fields field-spec ...
Auxiliary syntax parent parent-name
Auxiliary syntax protocol expression
Auxiliary syntax sealed boolean
Auxiliary syntax opaque boolean
Auxiliary syntax nongenerative :optional uid
Auxiliary syntax parent-rtd parent-rtd parent-cd

[R6RS] A `define-record-type` form defines a record type along with associated constructor descriptor and constructor, predicate, field accessors, and field mutators. The `define-record-type` form expands into a set of definitions in the environment where `define-record-type` appears; hence, it is possible to refer to the bindings (except for that of the record type itself) recursively.

The name-spec specifies the names of the record type, constructor, and predicate. It must take one of the following forms:

    (_record-name_ _constructor-name_ _predicate-name_)

    _record-name_

Record-name, constructor-name, and predicate-name must all be identifiers. Record-name, taken as a symbol, becomes the name of the record type. (See the description of `make-record-type-descriptor`.) Additionally, it is bound by this definition to an expand-time or run-time representation of the record type and can be used as parent name in syntactic record-type definitions that extend this definition. It can also be used as a handle to gain access to the underlying record-type descriptor and constructor descriptor (see `record-type-descriptor` and `record-constructor-descriptor`).

Constructor-name is defined by this definition to be a constructor for the defined record type, with a protocol specified by the `protocol` clause, or, in its absence, using a default protocol. For details, see the description of the `protocol` clause below.

Predicate-name is defined by this definition to a predicate for the defined record type.

The second form of name-spec is an abbreviation for the first form, where the name of the constructor is generated by prefixing the record name with `make-`, and the predicate name is generated by adding a question mark (`?`) to the end of the record name. For example, if the record name is `frob`, the name of the constructor is `make-frob`, and the predicate name is `frob?`. Each record-clause must take one of the auxiliary syntax forms; it is a syntax violation if multiple record-clauses of the same kind appear in a `define-record-type` form.

    (fields _field-spec_*)

Each field-spec has one of the following forms

    (immutable _field-name_ _accessor-name_)

    (mutable _field-name_ _accessor-name_ _mutator-name_)

    (immutable _field-name_)

    (mutable _field-name_)

    _field-name_

Field-name, accessor-name, and mutator-name must all be identifiers. The first form declares an immutable field called field-name>, with the corresponding accessor named accessor-name. The second form declares a mutable field called field-name, with the corresponding accessor named accessor-name, and with the corresponding mutator named mutator-name.

If field-spec takes the third or fourth form, the accessor name is generated by appending the record name and field name with a hyphen separator, and the mutator name (for a mutable field) is generated by adding a `-set!` suffix to the accessor name. For example, if the record name is `frob` and the field name is `widget`, the accessor name is `frob-widget` and the mutator name is `frob-widget-set!`.

If field-spec is just a field-name form, it is an abbreviation for `(immutable _field-name_)`.

The field-names become, as symbols, the names of the fields in the `record-type` descriptor being created, in the same order.

The `fields` clause may be absent; this is equivalent to an empty `fields`clause.

    (parent _parent-name_)

Specifies that the record type is to have parent type parent-name, where parent-name is the record-name of a record type previously defined using `define-record-type`. The record-type definition associated with parent-name must not be sealed. If no parent clause and no `parent-rtd`(see below) clause is present, the record type is a base type.

    (protocol _expression_)

Expression is evaluated in the same environment as the `define-record-type`form, and must evaluate to a protocol appropriate for the record type being defined.

The protocol is used to create a record-constructor descriptor as described below. If no `protocol` clause is specified, a constructor descriptor is still created using a default protocol. The clause can be absent only if the record type being defined has no parent type, or if the parent definition does not specify a protocol.

    (sealed _boolean_)

If this option is specified with operand #t, the defined record type is sealed, i.e., no extensions of the record type can be created. If this option is specified with operand #f, or is absent, the defined record type is not sealed.

    (opaque _boolean_)

If this option is specified with operand #t, or if an opaque parent record type is specified, the defined record type is opaque. Otherwise, the defined record type is not opaque. See the specification of record-rtd below for details.

    (nongenerative _uid_)

    (nongenerative)

This specifies that the record type is nongenerative with uid uid, which must be an identifier. If uid is absent, a unique uid is generated at macro-expansion time. If two record-type definitions specify the same uid, then the record-type definitions should be equivalent, i.e., the implied arguments to `make-record-type-descriptor` must be equivalent as described under `make-record-type-descriptor`. If this condition is not met, it is either considered a syntax violation or an exception with condition type `&assertion`is raised. If the condition is met, a single record type is generated for both definitions.

In the absence of a `nongenerative` clause, a new record type is generated every time a `define-record-type` form is evaluated:

    (let ((f (lambda (x)
               (define-record-type r ...)
               (if x r? (make-r ...)))))
      ((f #t) (f #f)))

    (parent-rtd _parent-rtd_ _parent-cd_)

Specifies that the record type is to have its parent type specified by parent-rtd, which should be an expression evaluating to a record-type descriptor, and parent-cd, which should be an expression evaluating to a constructor descriptor. The record-type definition associated with the value of parent-rtd must not be sealed. Moreover, a record-type definition must not have both a `parent` and a `parent-rtd` clause.

All bindings created by `define-record-typ`e (for the record type, the constructor, the predicate, the accessors, and the mutators) must have names that are pairwise distinct.

The constructor created by a `define-record-type` form is a procedure as follows:

- If there is no `parent` clause and no `protocol` clause, the constructor accepts as many arguments as there are fields, in the same order as they appear in the `fields` clause, and returns a record object with the fields initialized to the corresponding arguments.

- If there is no `parent` or `parent-rtd` clause and a `protocol`clause, the protocol expression must evaluate to a procedure that accepts a single argument. The protocol procedure is called once during the evaluation of the `define-record-type` form with a procedure p as its argument. It should return a procedure, which will become the constructor bound to constructor-name. The procedure p accepts as many arguments as there are fields, in the same order as they appear in the fields clause, and returns a record object with the fields initialized to the corresponding arguments. The constructor returned by the protocol procedure can accept an arbitrary number of arguments, and should call p once to construct a record object, and return that record object. For example, the following protocol expression for a record-type definition with three fields creates a constructor that accepts values for all fields, and initialized them in the reverse order of the arguments:

      (lambda (p)
        (lambda (v1 v2 v3)
          (p v3 v2 v1)))

- If there is both a `parent` clause and a `protocol` clause, then the protocol procedure is called once with a procedure _n_as its argument. As in the previous case, the protocol procedure should return a procedure, which will become the constructor bound to constructor-name. However, n is different from p in the previous case: It accepts arguments corresponding to the arguments of the constructor of the parent type. It then returns a procedure p that accepts as many arguments as there are (additional) fields in this type, in the same order as in the `fields` clause, and returns a record object with the fields of the parent record types initialized according to their constructors and the arguments to n, and the fields of this record type initialized to its arguments of p. The constructor returned by the protocol procedure can accept an arbitrary number of arguments, and should call n once to construct the procedure p, and call p once to create the record object, and finally return that record object. For example, the following protocol expression assumes that the constructor of the parent type takes three arguments:

      (lambda (n)
        (lambda (v1 v2 v3 x1 x2 x3 x4)
          (let ((p (n v1 v2 v3)))
            (p x1 x2 x3 x4))))

  The resulting constructor accepts seven arguments, and initializes the fields of the parent types according to the constructor of the parent type, with `v1`, `v2`, and `v3` as arguments. It also initializes the fields of this record type to the values of `x1`, ..., `x4`.

- If there is a `parent` clause, but no `protocol` clause, then the parent type must not have a `protocol` clause itself. The constructor bound to constructor-name is a procedure that accepts arguments corresponding to the parent types' constructor first, and then one argument for each field in the same order as in the `fields` clause. The constructor returns a record object with the fields initialized to the corresponding arguments.

- If there is a `parent-rtd` clause, then the constructor is as with a `parent` clause, except that the constructor of the parent type is determined by the constructor descriptor of the `parent-rtd` clause.

A protocol may perform other actions consistent with the requirements described above, including mutation of the new record or other side effects, before returning the record.

Any definition that takes advantage of implicit naming for the constructor, predicate, accessor, and mutator names can be rewritten trivially to a definition that specifies all names explicitly. For example, the implicit-naming record definition:

    (define-record-type frob
      (fields (mutable widget))
      (protocol
        (lambda (p)
          (lambda (n) (p (make-widget n))))))

is equivalent to the following explicit-naming record definition.

    (define-record-type (frob make-frob frob?)
      (fields (mutable widget
                       frob-widget
                       frob-widget-set!))
      (protocol
        (lambda (p)
          (lambda (n) (p (make-widget n))))))

Also, the implicit-naming record definition:

    (define-record-type point (fields x y))

is equivalent to the following explicit-naming record definition:

    (define-record-type (point make-point point?)
      (fields
        (immutable x point-x)
        (immutable y point-y)))

With implicit naming, it is still possible to specify some of the names explicitly; for example, the following overrides the choice of accessor and mutator names for the widget field.

    (define-record-type frob
      (fields (mutable widget getwid setwid!))
      (protocol
        (lambda (p)
          (lambda (n) (p (make-widget n))))))

Macro record-type-descriptor record-name

[R6RS] Evaluates to the record-type descriptor (see Records procedural layer) associated with the type specified by record-name.

Macro record-constructor-descriptor record-name

[R6RS] Evaluates to the record-type constructor (see Records procedural layer) associated with the type specified by record-name.

The following example uses the `record?` procedure from the `(rnrs records inspection (6))` library:

    (define-record-type (point make-point point?)
      (fields (immutable x point-x)
               (mutable y point-y set-point-y!))
      (nongenerative point-4893d957-e00b-11d9-817f-00111175eb9e))

    (define-record-type (cpoint make-cpoint cpoint?)
      (parent point)
      (protocol (lambda (n)
                     (lambda (x y c)
                       ((n x y) (color->rgb c)))))
      (fields (mutable rgb cpoint-rgb cpoint-rgb-set!)))

    (define (color->rgb c) (cons 'rgb c))

    (define p1 (make-point 1 2))

    (define p2 (make-cpoint 3 4 'red))

    (point? p1)

#t

    (point? p2)

#t

    (point? (vector))

    (point? (cons 'a 'b))

    (cpoint? p1)

    (cpoint? p2)

#t

    (point-x p1)

1

    (point-y p1)

2

    (point-x p2)

3

    (point-y p2)

4

    (cpoint-rgb p2)

(rgb . red)

    (set-point-y! p1 17)

unspecified

    (point-y p1)

17

    (record-rtd p1)

(record-type-descriptor point)

    (define-record-type (ex1 make-ex1 ex1?)
      (protocol (lambda (p) (lambda a (p a))))
      (fields (immutable f ex1-f)))

    (define ex1-i1 (make-ex1 1 2 3))

    (ex1-f ex1-i1)

(1 2 3)

    (define-record-type (ex2 make-ex2 ex2?)
      (protocol
        (lambda (p) (lambda (a . b) (p a b))))
      (fields (immutable a ex2-a)
               (immutable b ex2-b)))

    (define ex2-i1 (make-ex2 1 2 3))

    (ex2-a ex2-i1)

1

    (ex2-b ex2-i1)

(2 3)

    (define-record-type (unit-vector make-unit-vector unit-vector?)
      (protocol (lambda (p)
                     (lambda (x y z)
                       (let ((length (sqrt (+ (* x x) (* y y) (* z z)))))
                             (p (/ x length) (/ y length) (/ z length))))))
      (fields (immutable x unit-vector-x)
               (immutable y unit-vector-y)
               (immutable z unit-vector-z)))

    (define *ex3-instance* #f)

    (define-record-type ex3
      (parent cpoint)
      (protocol (lambda (n)
                     (lambda (x y t)
                       (let ((r ((n x y 'red) t)))
                         (set! *ex3-instance* r)
                         r))))
      (fields  (mutable thickness))
      (sealed #t) (opaque #t))

    (define ex3-i1 (make-ex3 1 2 17))

    (ex3? ex3-i1)

#t

    (cpoint-rgb ex3-i1)

(rgb . red)

    (ex3-thickness ex3-i1)

17

    (ex3-thickness-set! ex3-i1 18)

unspecified

    (ex3-thickness ex3-i1)

18

    *ex3-instance*

ex3-i1

    (record? ex3-i1)

## Records procedural layer

Library (rnrs records procedural (6))

The procedural layer is provided by the `(rnrs records procedural (6))`library.

Function make-record-type-descriptor name parent uid sealed? opaque? fields

[R6RS] Returns a record-type descriptor (rtd).

The name argument must be a symbol. It names the record type, and is intended purely for informational purposes.

The parent argument must be either #f or an rtd. If it is an rtd, the returned record type, t, extends the record type p represented by parent. An exception with condition type `&assertion` is raised if parent is sealed (see below).

The uid argument must be either #f or a symbol. If uid is a symbol, the record-creation operation is nongenerative i.e., a new record type is created only if no previous call to `make-record-type-descriptor` was made with the uid. If uid is #f, the record-creation operation is generative, .e., a new record type is created even if a previous call to `make-record-type-descriptor` was made with the same arguments.

If `make-record-type-descriptor` is called twice with the same _uid_symbol, the parent arguments in the two calls must be `eqv?`, the fields arguments `equal?`, the sealed? arguments boolean-equivalent (both #f or both true), and the opaque? arguments boolean-equivalent. If these conditions are not met, an exception with condition type `&assertion`is raised when the second call occurs. If they are met, the second call returns, without creating a new record type, the same record-type descriptor (in the sense of `eqv?`) as the first call.

The sealed? flag must be a boolean. If true, the returned record type is sealed, i.e., it cannot be extended.

The opaque? flag must be a boolean. If true, the record type is opaque. If passed an instance of the record type, record? returns #f. Moreover, if `record-rtd` (see (rnrs records inspection (6))) is called with an instance of the record type, an exception with condition type `&assertion` is raised. The record type is also opaque if an opaque parent is supplied. If opaque? is #f and an opaque parent is not supplied, the record is not opaque.

The fields argument must be a vector of field specifiers. Each field specifier must be a list of the form `(mutable _name_)` or a list of the form `(immutable _name_)`. Each name must be a symbol and names the corresponding field of the record type; the names need not be distinct. A field identified as mutable may be modified, whereas, when a program attempts to obtain a mutator for a field identified as immutable, an exception with condition type `&assertion`is raised. Where field order is relevant, e.g., for record construction and field access, the fields are considered to be ordered as specified, although no particular order is required for the actual representation of a record instance.

The specified fields are added to the parent fields, if any, to determine the complete set of fields of the returned record type. If fields is modified after `make-record-type-descriptor` has been called, the effect on the returned rtd is unspecified.

A generative record-type descriptor created by a call to `make-record-type-descriptor` is not `eqv?` to any record-type descriptor (generative or nongenerative) created by another call to `make-record-type-descriptor`. A generative record-type descriptor is `eqv?`only to itself, i.e., (eqv? rtd1 rtd2) iff (eq? rtd1 rtd2). Also, two nongenerative record-type descriptors are `eqv?` if they were created by calls to `make-record-type-descriptor` with the same uid arguments.

Function record-type-descriptor? obj

[R6RS] Returns #t if the argument is a record-type descriptor, #f otherwise.

Function make-record-constructor-descriptor rtd parent-constructor-descriptor protocol

[R6RS] Returns a record-constructor descriptor (or var{constructor descriptor} for short) that specifies a record constructor(or constructor for short), that can be used to construct record values of the type specified by rtd, and which can be obtained via `record-constructor`. A constructor descriptor can also be used to create other constructor descriptors for subtypes of its own record type. Rtd must be a record-type descriptor. Protocol must be a procedure or #f. If it is #f, a default protocol procedure is supplied.

If protocol is a procedure, it is handled analogously to the protocol expression in a `define-record-type` form.

If rtd is a base record type and protocol is a procedure, parent-constructor-descriptor must be #f. In this case, _protocol_is called by `record-constructor` with a single argument p. _P_is a procedure that expects one argument for every field of rtd and returns a record with the fields of rtd initialized to these arguments. The procedure returned by protocol should call p once with the number of arguments p expects and return the resulting record as shown in the simple example below:

    (lambda (p)
      (lambda (v1 v2 v3)
        (p v1 v2 v3)))

Here, the call to p returns a record whose fields are initialized with the values of `v1`, `v2`, and `v3`. The expression above is equivalent to `(lambda (p) p)`. Note that the procedure returned by protocol is otherwise unconstrained; specifically, it can take any number of arguments.

If rtd is an extension of another record type parent-rtd and protocol is a procedure, parent-constructor-descriptor must be a constructor descriptor of parent-rtd or #f. If parent-constructor-descriptor is a constructor descriptor, _protocol_it is called by record-constructor with a single argument n, which is a procedure that accepts the same number of arguments as the constructor of parent-constructor-descriptor and returns a procedure p that, when called, constructs the record itself. The p procedure expects one argument for every field of rtd (not including parent fields) and returns a record with the fields of rtd initialized to these arguments, and the fields of parent-rtd and its parents initialized as specified by parent-constructor-descriptor.

The procedure returned by protocol should call n once with the number of arguments n expects, call the procedure p it returns once with the number of arguments p expects and return the resulting record. A simple protocol in this case might be written as follows:

    (lambda (n)
      (lambda (v1 v2 v3 x1 x2 x3 x4)
        (let ((p (n v1 v2 v3)))
          (p x1 x2 x3 x4))))

This passes arguments `v1`, `v2`, `v3` to n for parent-constructor-descriptor and calls p with `x1`, ..., `x4` to initialize the fields of rtd itself.

Thus, the constructor descriptors for a record type form a sequence of protocols parallel to the sequence of record-type parents. Each constructor descriptor in the chain determines the field values for the associated record type. Child record constructors need not know the number or contents of parent fields, only the number of arguments accepted by the parent constructor.

Protocol may be #f, specifying a default constructor that accepts one argument for each field of rtd (including the fields of its parent type, if any). Specifically, if rtd is a base type, the default protocol procedure behaves as if it were `(lambda (p) p)`. If rtd is an extension of another type, then parent-constructor-descriptor must be either #f or itself specify a default constructor, and the default protocol procedure behaves as if it were:

    (lambda (n)
      (lambda (v1 ... vj x1 ... xk)
        (let ((p (n v1 ... vj)))
          (p x1 ... xk))))

The resulting constructor accepts one argument for each of the record type's complete set of fields (including those of the parent record type, the parent's parent record type, etc.) and returns a record with the fields initialized to those arguments, with the field values for the parent coming before those of the extension in the argument list. (In the example, j is the complete number of fields of the parent type, and k is the number of fields of rtd itself.)

If rtd is an extension of another record type, and _parent-constructor-descriptor_or the protocol of parent-constructor-descriptor is #f, protocol must also be #f, and a default constructor descriptor as described above is also assumed.

Function record-constructor constructor-descriptor

[R6RS] Calls the protocol of constructor-descriptor (as described for `make-record-constructor-descriptor`) and returns the resulting constructor constructor for records of the record type associated with constructor-descriptor.

Function record-predicate rtd

[R6RS] Returns a procedure that, given an object obj, returns #t if obj is a record of the type represented by rtd, and #f otherwise.

Function record-accessor rtd k

[R6RS] K must be a valid field index of rtd. The `record-accessor` procedure returns a one-argument procedure whose argument must be a record of the type represented by rtd. This procedure returns the value of the selected field of that record.

The field selected corresponds to the _k_th element (0-based) of the fields argument to the invocation of `make-record-type-descriptor` that created rtd. Note that k cannot be used to specify a field of any type rtd extends.

Function record-mutator rtd k

[R6RS] K must be a valid field index of rtd. The `record-mutator` procedure returns a two-argument procedure whose arguments must be a record record r of the type represented by rtd and an object obj. This procedure stores obj within the field of _r_specified by k. The k argument is as in `record-accessor`. If k specifies an immutable field, an exception with condition type `&assertion` is raised. The mutator returns unspecified values.

## Records inspection

Library (rnrs records syntactic (6))

The `(rnrs records inspection (6))`library provides procedures for inspecting records and their record-type descriptors. These procedures are designed to allow the writing of portable printers and inspectors.

Function record? obj

[R6RS] Returns #t if obj is a record, and its record type is not opaque, and returns #f otherwise.

Function record-rtd record

[R6RS] Returns the rtd representing the type of record if the type is not opaque. The rtd of the most precise type is returned; that is, the type t such that record is of type t but not of any type that extends t. If the type is opaque, an exception is raised with condition type `&assertion`.

Function record-type-name rtd
Function record-type-parent rtd
Function record-type-uid rtd

[R6RS] Returns the name/parent/uid of the record-type descriptor rtd.

Function record-type-generative? rtd
Function record-type-sealed? rtd
Function record-type-opaque? rtd

[R6RS] Returns #t if the record-type descriptor is generative/sealed/opaque, and #f if not.

Function record-type-field-names rtd

[R6RS] Returns a vector of symbols naming the fields of the type represented by rtd (not including the fields of parent types) where the fields are ordered as described under `make-record-type-descriptor`.

Function record-type-mutable? rtd k

[R6RS] Returns #t if the field specified by k of the type represented by rtd is mutable, and #f if not. K is as in `record-accessor`.

## Exceptions

Library (rnrs exceptions (6))

This section describes exception-handling and exception-raising constructs provided by the `(rnrs exceptions (6))`library.

Function with-exception-handler handler thunk

[R6RS] Handler must be a procedure and should accept one argument. Thunk must be a procedure that accepts zero arguments. The `with-exception-handler` procedure returns the results of invoking thunk. When an exception is raised, handler will be invoked with the exception.

Macro guard (variable cond-clause ... ) body

[R6RS] Each cond-clause is as in the specification of `cond`. and `else` are the same as in the `(rnrs base (6))` library.

Evaluating a `guard` form evaluates body with an exception handler that binds the raised object to variable and within the scope of that binding evaluates the clauses as if they were the clauses of a `cond`expression. If every cond-clause's test evaluates to #f and there is no `else` clause, then raise is re-invoked on the raised object.

Function raise obj

[R6RS] Raises a non-continuable exception by invoking the current exception handler on obj.

Function raise-continuable obj

[R6RS] Raises a continuable exception by invoking the current exception handler on obj.

## Conditions

Library (rnrs conditions (6))

The section describes `(rnrs conditions (6))`library for creating and inspecting condition types and values. A condition value encapsulates information about an exceptional situation.

Function condition condition ...

[R6RS] The `condition` procedure returns a condition object with the components of the conditions as its components, in the same order. The returned condition is compound if the total number of components is zero or greater than one. Otherwise, it may be compound or simple.

Function simple-condition condition

[R6RS] The `simple-conditions` procedure returns a list of the components of condition, in the same order as they appeared in the construction of condition.

Function condition? obj

[R6RS] Returns #t if obj is a (simple or compound) condition, otherwise returns #f.

Function condition-predicate rtd

[R6RS] Rtd must be a record-type descriptor of a subtype of `&condition`. The `condition-predicate` procedure returns a procedure that takes one argument. This procedure returns #t if its argument is a condition of the condition type represented by rtd, i.e., if it is either a simple condition of that record type (or one of its subtypes) or a compound conditition with such a simple condition as one of its components, and #f otherwise.

Function condition-accessor rtd proc

[R6RS] Rtd must be a record-type descriptor of a subtype of `&condition`. Proc should accept one argument, a record of the record type of rtd. The `condition-accessor` procedure returns a procedure that accepts a single argument, which must be a condition of the type represented by rtd. This procedure extracts the first component of the condition of the type represented by rtd, and returns the result of applying proc to that component.

Macro define-condition-type condition-type supertypes constructor predicate field-spec ...

[R6RS] Condition-type, supertypes, constructor, and predicate must all be identifiers. Each field-spec must be of the form

    (_field_ _accessor_)

where both field and accessor must be identifiers.

The `define-condition-type` form expands into a record-type definition for a record type condition-type. The record type will be non-opaque, non-sealed, and its fields will be immutable. It will have supertype has its parent type. The remaining identifiers will be bound as follows:

- Constructor is bound to a default constructor for the type : It accepts one argument for each of the record type's complete set of fields (including parent types, with the fields of the parent coming before those of the extension in the arguments) and returns a condition object initialized to those arguments.

- Predicate is bound to a predicate that identifies conditions of type condition-type or any of its subtypes.

- Each accessor is bound to a procedure that extracts the corresponding field from a condition of type condition-type.

### Standard condition types

Hierarchy of standard condition types:

    + &condition
        + &warning
        + &serious
              + &error
              + &violation
                    + &assertion
                    + &non-continuable
                    + &implementation-restriction
                    + &lexical
                    + &syntax
                    + &undefined
        + &message
        + &irritants

Condition Type &message
Function make-message-condition message
Function message-condition? obj
Function condition-message condition

[R6RS] It carries a message further describing the nature of the condition to humans.

Condition Type &warning
Function make-warning
Function warning? obj

[R6RS] This type describes conditions that do not, in principle, prohibit immediate continued execution of the program, but may interfere with the program's execution later.

Condition Type &serious
Function make-serious-condition
Function serious-condition? obj

[R6RS] This type describes conditions serious enough that they cannot safely be ignored. This condition type is primarily intended as a supertype of other condition types.

Condition Type &error
Function make-error
Function error? obj

[R6RS] This type describes errors, typically caused by something that has gone wrong in the interaction of the program with the external world or the user.

Condition Type &violation
Function make-violation
Function violation? obj

[R6RS] This type describes violations of the language standard or a library standard, typically caused by a programming error.

Condition Type &assertion
Function make-assertion-violation
Function assertion-violation? obj

[R6RS] This type describes an invalid call to a procedure, either passing an invalid number of arguments, or passing an argument of the wrong type.

Condition Type &irritants
Function make-irritants-condition irritants
Function irritants-condition? obj
Function condition-irritants condition

[R6RS] Irritants should be a list of objects. This condition provides additional information about a condition, typically the argument list of a procedure that detected an exception. Conditions of this type are created by the `error` and `assertion-violation` procedures.

Condition Type &who
Function make-who-condition who
Function who-condition? obj
Function condition-who condition

[R6RS] Who should be a symbol or string identifying the entity reporting the exception. Conditions of this type are created by the `error`and `assertion-violation` procedures, and the `syntax-violation`procedure.

Condition Type &non-continuable
Function make-non-continuable-violation
Function non-continuable-violation? obj

[R6RS] This type indicates that an exception handler invoked via raise has returned.

Condition Type &implementation-restriction
Function make-implementation-restriction-violation
Function implementation-restriction-violation? obj

[R6RS] This type describes a violation of an implementation restriction allowed by the specification, such as the absence of representations for NaNs and infinities.

Condition Type &lexical
Function make-lexical-violation
Function lexical-violation? obj

[R6RS] This type describes syntax violations at the level of the datum syntax.

Condition Type &syntax
Function make-syntax-violation form subform
Function syntax-violation? obj
Function syntax-violation-form condition
Function syntax-violation-subform condition

[R6RS] This type describes syntax violations. Form should be the erroneous syntax object or a datum representing the code of the erroneous form. Subform should be an optional syntax object or datum within the erroneous form that more precisely locates the violation. It can be #f to indicate the absence of more precise information.

Condition Type &undefined
Function make-undefined-violation
Function undefined-violation? obj

[R6RS] This type describes unbound identifiers in the program.

## I/O condition types

The condition types and corresponding predicates and accessors are exported by both the `(rnrs io ports (6))` and `(rnrs io simple (6))` libraries. They are also exported by the `(rnrs files (6))` library.

Condition Type &i/o
Function make-i/o-error
Function i/o-error? obj

[R6RS] This is a supertype for a set of more specific I/O errors.

Condition Type &i/o-read
Function make-i/o-read-error
Function i/o-read-error? obj

[R6RS] This condition type describes read errors that occurred during an I/O operation.

Condition Type &i/o-write
Function make-i/o-write-error
Function i/o-write-error? obj

[R6RS] This condition type describes write errors that occurred during an I/O operation.

Condition Type &i/o-invalid-position
Function make-i/o-invalid-position-error position
Function i/o-invalid-position-error? obj
Function i/o-error-position condition

[R6RS] This condition type describes attempts to set the file position to an invalid position. Position should be the file position that the program intended to set. This condition describes a range error, but not an assertion violation.

Condition Type &i/o-filename
Function make-i/o-filename-error filename
Function i/o-filename-error? obj
Function i/o-error-filename condition

[R6RS] This condition type describes an I/O error that occurred during an operation on a named file. Filename should be the name of the file.

Condition Type &i/o-file-protection
Function make-i/o-file-protection-error filename
Function i/o-file-protection-error? obj

[R6RS] A condition of this type specifies that an operation tried to operate on a named file with insufficient access rights.

Condition Type &i/o-file-is-read-only
Function make-i/o-file-is-read-only-error filename
Function i/o-file-is-read-only-error? obj

[R6RS] A condition of this type specifies that an operation tried to operate on a named read-only file under the assumption that it is writeable.

Condition Type &i/o-file-already-exists
Function make-i/o-file-already-exists-error filename
Function i/o-file-already-exists-error? obj

[R6RS] A condition of this type specifies that an operation tried to operate on an existing named file under the assumption that it did not exist.

Condition Type &i/o-file-does-not-exist
Function make-i/o-file-does-not-exist-error filename
Function i/o-file-does-not-exist-error? obj

[R6RS] A condition of this type specifies that an operation tried to operate on an non-existent named file under the assumption that it existed.

Condition Type &i/o-port
Function make-i/o-port-error port
Function i/o-port-error? obj
Function i/o-error-port condition

[R6RS] This condition type specifies the port with which an I/O error is associated. Port should be the port. Conditions raised by procedures accepting a port as an argument should include an `&i/o-port-error`condition.

Here I describe the conditions hierarchy.

    + &error([See (rnrs conditions (6))](#rnrs.conditions.6))
        + &i/o
              + &i/o-read
              + &i/o-write
              + &i/o-invalid-position
              + &i/o-filename
                    + &i/o-file-protection
                          + &i/o-file-is-read-only
                    + &i/o-file-already-exists
                    + &i/o-file-does-not-exist
              + &i/o-port-error

### Port I/O

Library (rnrs io ports (6))

The `(rnrs io ports (6))`library defines an I/O layer for conventional, imperative buffered input and output. A port represents a buffered access object for a data sink or source or both simultaneously. The library allows ports to be created from arbitrary data sources and sinks.

The `(rnrs io ports (6))` library distinguishes between _input ports_and output ports. An input port is a source for data, whereas an output port is a sink for data. A port may be both an input port and an output port; such a port typically provides simultaneous read and write access to a file or other data.

The `(rnrs io ports (6))` library also distinguishes between binary ports, which are sources or sinks for uninterpreted bytes, and textual ports, which are sources or sinks for characters and strings.

This section uses input-port, output-port, binary-port, textual-port, binary-input-port, textual-input-port, binary-output-port, textual-output-port, and port as parameter names for arguments that must be input ports (or combined input/output ports), output ports (or combined input/output ports), binary ports, textual ports, binary input ports, textual input ports, binary output ports, textual output ports, or any kind of port, respectively.

#### Filename

In this world, unfortunately there are a lot of operating systems. However, as far as I know there are only two file separators, one is Windows style back slash, the other is UNIX style slash. On Sagittarius both of it can be used as file path. Inside of the resolution of file path, Sagittarius replaces those file separators to OS specific one. Even though programmer does not have to care about it, I think it's better to use slash as file separator on script files.

A filename parameter name means that the corresponding argument must be a file name.

#### File options

When opening a file, the various procedures in this library accept a `file-options` object that encapsulates flags to specify how the file is to be opened. A `file-options` object is an enum-set (see (rnrs enums (6))) over the symbols constituting valid file options. A file-options parameter name means that the corresponding argument must be a file-options object.

Macro file-options file-options-symbol ...

[R6RS+] Each file-option-symbol must be a symbol. The file-options macro returns a file-options object that encapsulates the specified options.

When supplied to an operation that opens a file for output, the file-options object returned by `(file-options)` specifies that the file is created if it does not exist and an exception with condition type `&i/o-file-already-exists` is raised if it does exist. The following standard options can be included to modify the default behaviour.

- `no-create` If the file does not already exist, it is not created; instead, an exception with condition type `&i/o-file-does-not-exist` is raised. If the file already exists, the exception with condition type `&i/o-file-already-exists` is not raised and the file is truncated to zero length.

- `no-fail` If the file already exists, the exception with condition type `&i/o-file-already-exists` is not raised, even if `no-create` is not included, and the file is truncated to zero length.

- `no-truncate` If the file already exists and the exception with condition type `&i/o-file-already-exists` has been inhibited by inclusion of `no-create` or `no-fail`, the file is not truncated, but the port's current position is still set to the beginning of the file.

- `append` Among with `no-truncate`, set the opened port's position the end of the file. This is not a part of R6RS specification.

#### Buffer modes

Each port has an associated buffer mode. For an output port, the buffer mode defines when an output operation flushes the buffer associated with the output port. For an input port, the buffer mode defines how much data will be read to satisfy read operations. The possible buffer modes are the symbols none for no buffering, line for flushing upon line endings and reading up to line endings, or other implementation-dependent behavior, and block for arbitrary buffering. This section uses the parameter name buffer-mode for arguments that must be buffer-mode symbols.

If two ports are connected to the same mutable source, both ports are unbuffered, and reading a byte or character from that shared source via one of the two ports would change the bytes or characters seen via the other port, a lookahead operation on one port will render the peeked byte or character inaccessible via the other port, while a subsequent read operation on the peeked port will see the peeked byte or character even though the port is otherwise unbuffered.

In other words, the semantics of buffering is defined in terms of side effects on shared mutable sources, and a lookahead operation has the same side effect on the shared source as a read operation.

Macro buffer-mode buffer-mode-symbol

[R6RS] Buffer-mode-symbol must be a symbol whose name is one of `none`, `line`, and `block`. The result is the corresponding symbol, and specifies the associated buffer mode.

Function buffer-mode? obj

Returns #t if the argument is a valid buffer-mode symbol, and returns #f otherwise.

#### Transcoders

Several different Unicode encoding schemes describe standard ways to encode characters and strings as byte sequences and to decode those sequences. Within this document, a codec is an immutable Scheme object that represents a Unicode or similar encoding scheme.

An end-of-line style is a symbol that, if it is not none, describes how a textual port transcodes representations of line endings.

A transcoder is an immutable Scheme object that combines a codec with an end-of-line style and a method for handling decoding errors. Each transcoder represents some specific bidirectional (but not necessarily lossless), possibly stateful translation between byte sequences and Unicode characters and strings. Every transcoder can operate in the input direction (bytes to characters) or in the output direction (characters to bytes). A transcoder parameter name means that the corresponding argument must be a transcoder.

A binary port is a port that supports binary I/O, does not have an associated transcoder and does not support textual I/O. A textual port is a port that supports textual I/O, and does not support binary I/O. A textual port may or may not have an associated transcoder.

Function latin-1-codec
Function utf-8-codec
Function utf-16-codec

[R6RS] These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16 encoding schemes.

A call to any of these procedures returns a value that is equal in the sense of `eqv?` to the result of any other call to the same procedure.

Macro eol-style eol-style-symbol

[R6RS] Eol-style-symbol should be a symbol whose name is one of `lf`, `cr`, `crlf`, `nel`, `crnel`, `ls`, and `none`. The form evaluates to the corresponding symbol. If the name of eol-style-symbol is not one of these symbols, it still returns given symbol, however `make-transcoder` does not accept it.

Function native-eol-style

[R6RS] Returns the default end-of-line style of the underlying platform.

Condition Type &i/o-decoding
Function make-i/o-decoding-error port
Function i/o-decoding-error? obj

[R6RS] An exception with this type is raised when one of the operations for textual input from a port encounters a sequence of bytes that cannot be translated into a character or string by the input direction of the port's transcoder.

When such an exception is raised, the port's position is past the invalid encoding.

Condition Type &i/o-encoding
Function make-i/o-encoding-error port
Function i/o-encoding-error? obj

[R6RS] An exception with this type is raised when one of the operations for textual output to a port encounters a character that cannot be translated into bytes by the output direction of the port's transcoder. Char is the character that could not be encoded.

Macro error-handling-mode error-handling-mode-symbol

[R6RS] Error-handling-mode-symbol should be a symbol whose name is one of `ignore`, `raise`, and `replace`. The form evaluates to the corresponding symbol.

The `error-handling` mode of a transcoder specifies the behavior of textual I/O operations in the presence of encoding or decoding errors.

If a textual input operation encounters an invalid or incomplete character encoding, and the error-handling mode is `ignore`, an appropriate number of bytes of the invalid encoding are ignored and decoding continues with the following bytes. If the error-handling mode is `replace`, the replacement character U+FFFD is injected into the data stream, an appropriate number of bytes are ignored, and decoding continues with the following bytes. If the error-handling mode is `raise`, an exception with condition type `&i/o-decoding` is raised.

If a textual output operation encounters a character it cannot encode, and the error-handling mode is `ignore`, the character is ignored and encoding continues with the next character. If the error-handling mode is `replace`, a codec-specific replacement character is emitted by the transcoder, and encoding continues with the next character. The replacement character is U+FFFD for transcoders whose codec is one of the Unicode encodings, but is the `?`character for the Latin-1 encoding. If the error-handling mode is `raise`, an exception with condition type `&i/o-encoding` is raised.

Function make-transcoder codec :optional eol-style handling-mode

[R6RS] Codec must be a codec; eol-style, if present, an eol-style symbol; and handling-mode, if present, an error-handling-mode symbol. Eol-style may be omitted, in which case it defaults to the native end-of-line style of the underlying platform. Handling-mode may be omitted, in which case it defaults to `replace`. The result is a transcoder with the behaviour specified by its arguments.

Function native-transcoder

[R6RS] Returns platform dependent transcoder.

Function transcoder-codec transcoder
Function transcoder-eol-style transcoder
Function transcoder-error-handlingmode transcoder

[R6RS] These are accessors for transcoder objects; when applied to a transcoder returned by `make-transcoder`, they return the codec, eol-style, and handling-mode arguments, respectively.

Function bytevector->string bytevector transcoder :optional start end

[R6RS+] Returns the string that results from transcoding the bytevector according to the input direction of the transcoder.

If the optional argument start is given, the procedure converts given string from start index (inclusive).

If the optional argument end is given, the procedure converts given string to end index (exclusive).

These optional arguments must be fixnum if it's given.

Function string->bytevector string transcoder :optional start end

[R6RS] Returns the bytevector that results from transcoding the string according to the output direction of the transcoder.

If the optional argument start is given, the procedure converts given string from start index (inclusive).

If the optional argument end is given, the procedure converts given string to end index (exclusive).

These optional arguments must be fixnum if it's given.

#### End-of-file object

The end-of-file object is returned by various I/O procedures when they reach end of file.

Function eof-object

[R6RS] Returns the end-of-file object

Function eof-object? obj

Returns #t if obj is the end-of-file object, #f otherwise.

#### Input and output ports

The operations described in this section are common to input and output ports, both binary and textual. A port may also have an associated position that specifies a particular place within its data sink or source, and may also provide operations for inspecting and setting that place.

Function port? obj

Returns #t if the argument is a port, and returns #f otherwise.

Function port-transcoder port

[R6RS] Returns the transcoder associated with port if port is textual and has an associated transcoder, and returns #f if port is binary or does not have an associated transcoder.

Function textual-port? obj
Function binary-port? obj

[R6RS+] [R7RS] The `textual-port?` procedure returns #t if _obj_is textual port, otherwise #f.

The `binary-port?` procedure returns #t if obj is binary port, otherwise #f.

Function transcoded-port binary-port transcoder

[R6RS] The `transcoded-port` procedure returns a new textual port with the specified transcoder. Otherwise the new textual port's state is largely the same as that of binary-port. If binary-port is an input port, the new textual port will be an input port and will transcode the bytes that have not yet been read from binary-port. If binary-port is an output port, the new textual port will be an output port and will transcode output characters into bytes that are written to the byte sink represented by binary-port.

Function port-has-port-position? port
Function port-position port

[R6RS] The `port-has-port-position?` procedure returns #t if the port supports the port-position operation, and #f otherwise.

The port-position procedure returns the index of the position at which the next position would be read from or written to the port as an exact non-negative integer object.

Function port-has-set-port-position!? port
Function set-port-position! port pos :optional (whence 'begin)

[R6RS+] The `port-has-set-port-position!?` procedure returns #t if the port supports the `set-port-position!` operation, and #f otherwise.

The `set-port-position!` procedure raises an exception with condition type `&assertion` if the port does not support the operation, and an exception with condition type `&i/o-invalid-position` if pos is not in the range of valid positions of port. Otherwise, it sets the current position of the port to pos. If port is an output port, set-port-position! first flushes port.

The optional argument whence must be one of the following symbols;

`begin`

  Set position from the beginning of the given port.

`current`

  Set position from the current position of the given port.

`end`

  Set position from the end of the given port.

NOTE: for R6RS custom port, the procedure doesn't accept the optional argument, so it will be always considered `begin` even though user specified it as `current` or `end`.

Function close-port port

[R6RS] Closes the port, rendering the port incapable of delivering or accepting data. If port is an output port, it is flushed before being closed. This has no effect if the port has already been closed. A closed port is still a port. The `close-port` procedure returns unspecified values.

Function call-with-port port proc

[R6RS] Proc must accept one argument. The `call-with-port`procedure calls proc with port as an argument. If _proc_returns, port is closed automatically and the values returned by proc are returned. If proc does not return, port is not closed automatically, except perhaps when it is possible to prove that port will never again be used for an input or output operation.

#### Input ports

An input port allows the reading of an infinite sequence of bytes or characters punctuated by end-of-file objects. An input port connected to a finite data source ends in an infinite sequence of end-of-file objects.

It is unspecified whether a character encoding consisting of several bytes may have an end of file between the bytes. If, for example, `get-char` raises an `&i/o-decoding` exception because the character encoding at the port's position is incomplete up to the next end of file, a subsequent call to `get-char` may successfully decode a character if bytes completing the encoding are available after the end of file.

Function input-port? obj

Returns #t if the argument is an input port (or a combined input and output port), and returns #f otherwise.

Function port-eof? input-port

[R6RS] Returns #t if the `lookahead-u8` procedure (if input-port is a binary port) or the `lookahead-char` procedure (if input-port is a textual port) would return the end-of-file object, and #f otherwise.

Function open-file-input-port filename :optiona file-options buffer-mode maybe-transcoder

[R6RS] Maybe-transcoder must be either a transcoder or #f.

The file-options argument, which may determine various aspects of the returned port, defaults to the value of `(file-options)`.

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to `block`.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the returned port.

If maybe-transcoder is #f or absent, the port will be a binary port, otherwise the port will be textual port.

Function open-bytevector-input-port bytevector :optional (transcoder #f) _

_ (start 0) (end (bytevector-length bytevector))

[R6RS+] transcoder must be either a transcoder or #f. The `open-bytevector-input-port` procedure returns an input port whose bytes are drawn from bytevector. If transcoder is specified, it becomes the transcoder associated with the returned port.

If transcoder is #f or absent, the port will be a binary port, otherwise the port will be textual port.

Optional arguments start and end restricts the range of input bytevector. It is almost the same as following code but doesn't allocate extra memory;

    (open-bytevector-input-port (bytevector-copy bytevector start end))

Function open-string-input-port string :optional (start 0) (end (string-length string))

[R6RS+] Returns a textual input port whose characters are drawn from string.

Optional arguments start and end restricts the range of input string. It is almost the same as following code but doesn't allocate extra memory;

    (open-string-input-port (substring string start end))

These procedures reuse the given arguments, thus if bytevector is modified after `open-bytevector-input-port` has been called, it affects the result of the port. So does `open-string-input-port`.

Function standard-input-port

[R6RS] Returns a fresh binary input port connected to standard input.

Function current-input-port :optional port

[R6RS+] If port is given, the `current-input-port` sets the port as a default port for input. Otherwise it returns a default input port.

Function make-custom-binary-input-port id read! get-position set-position! close :optional (ready #f)

[R6RS+] Returns a newly created binary input port whose byte source is an arbitrary algorithm represented by the read! procedure. Id must be a string naming the new port, provided for informational purposes only. Read! must be a procedure and should behave as specified below; it will be called by operations that perform binary input.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified below.

- (read! bytevector start count) Start will be a non-negative exact integer object, count will be a positive exact integer object, and bytevector will be a bytevector whose length is at least start + count. The read! procedure should obtain up to count bytes from the byte source, and should write those bytes into bytevector starting at index start. The _read!_procedure should return an exact integer object. This integer object should represent the number of bytes that it has read. To indicate an end of file, the read! procedure should write no bytes and return 0.

- (get-position) The get-position procedure (if supplied) should return an exact integer object representing the current position of the input port. If not supplied, the custom port will not support the `port-position` operation.

- (set-position! pos) Pos will be a non-negative exact integer object. The set-position! procedure (if supplied) should set the position of the input port to pos. If not supplied, the custom port will not support the set-port-position! operation.

- (close) The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.

- (ready) The ready procedure (if supplied) should indicate the port data are ready or not.

Function make-custom-textual-input-port id read! get-position set-position! close :optional (ready #f)

[R6RS+] Returns a newly created textual input port whose character source is an arbitrary algorithm represented by the read! procedure. _Id_must be a string naming the new port, provided for informational purposes only. Read! must be a procedure and should behave as specified below; it will be called by operations that perform textual input.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified below.

- (read! string start count) Start will be a non-negative exact integer object, count will be a positive exact integer object, and string will be a string whose length is at least start + count. The read! procedure should obtain up to count characters from the character source, and should write those characters into string starting at index start. The _read!_procedure should return an exact integer object representing the number of characters that it has written. To indicate an end of file, the _read!_procedure should write no bytes and return 0.

- (get-position) The get-position procedure (if supplied) should return a single value. The return value should represent the current position of the input port. If not supplied, the custom port will not support the `port-position` operation.

- (set-position! pos) The set-position! procedure (if supplied) should set the position of the input port to pos if pos is the return value of a call to get-position. If not supplied, the custom port will not support the `set-port-position!` operation.

- (close) The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.

- (ready) The ready procedure (if supplied) should indicate the port characters are ready or not.

#### Binary input

Function get-u8 binary-input-port :optional reckless

[R6RS] Reads from binary-input-port, blocking as necessary, until a byte is available from binary-input-port or until an end of file is reached.

If a byte becomes available, `get-u8` returns the byte as an octet and updates binary-input-port to point just past that byte. If no input byte is seen before an end of file is reached, the end-of-file object is returned.

Function lookahead-u8 binary-input-port :optional reckless

[R6RS] The `lookahead-u8` procedure is like `get-u8`, but it does not update binary-input-port to point past the byte.

Function get-bytevector-n binary-input-port count :optional reckless

[R6RS+] Count must be an exact, non-negative integer object representing the number of bytes to be read.

The `get-bytevector-n` procedure reads from binary-input-port, blocking as necessary, until count bytes are available from binary-input-port or until an end of file is reached. If _count_bytes are available before an end of file, `get-bytevector-n` returns a bytevector of size count.

If fewer bytes are available before an end of file, `get-bytevector-n`returns a bytevector containing those bytes. In either case, the input port is updated to point just past the bytes read. If an end of file is reached before any bytes are available, `get-bytevector-n` returns the end-of-file object.

Function get-bytevector-n! binary-input-port bytevector start count :optional reckless

[R6RS+] Count must be an exact, non-negative integer object, representing the number of bytes to be read. bytevector must be a bytevector with at least start + count elements.

The `get-bytevector-n!` procedure reads from binary-input-port, blocking as necessary, until count bytes are available from binary-input-port or until an end of file is reached. If count bytes are available before an end of file, they are written into _bytevector_starting at index start, and the result is count. If fewer bytes are available before the next end of file, the available bytes are written into bytevector starting at index start, and the result is a number object representing the number of bytes actually read. In either case, the input port is updated to point just past the bytes read. If an end of file is reached before any bytes are available, `get-bytevector-n!` returns the end-of-file object.

Function get-bytevector-some binary-input-port :optional reckless

[R6RS+] Reads from binary-input-port, blocking as necessary, until bytes are available from binary-input-port or until an end of file is reached. If bytes become available, `get-bytevector-some` returns a freshly allocated bytevector containing the initial available bytes (at least one and maximum 512 bytes), and it updates binary-input-port to point just past these bytes. If no input bytes are seen before an end of file is reached, the end-of-file object is returned.

Function get-bytevector-all binary-input-port :optional reckless

[R6RS+] Attempts to read all bytes until the next end of file, blocking as necessary. If one or more bytes are read, `get-bytevector-all` returns a bytevector containing all bytes up to the next end of file. Otherwise, `get-bytevector-all` returns the end-of-file object.

These procedures can take optional argument reckless. If this is given, these procedures can read bytes from textual port. This optional argument is for socket programming. Users needs to make sure that the given port can be read as textual port after reading port recklessly.

#### Textual input

Function get-char textual-input-port

[R6RS] Reads from textual-input-port, blocking as necessary, until a complete character is available from textual-input-port, or until an end of file is reached.

If a complete character is available before the next end of file, `get-char`returns that character and updates the input port to point past the character. If an end of file is reached before any character is read, `get-char`returns the end-of-file object.

Function lookahead-char textual-input-port

[R6RS] The `lookahead-char` procedure is like `get-char`, but it does not update textual-input-port to point past the character.

Function get-string-n textual-input-port count

[R6RS] Count must be an exact, non-negative integer object, representing the number of characters to be read.

The `get-string-n` procedure reads from textual-input-port, blocking as necessary, until count characters are available, or until an end of file is reached.

If count characters are available before end of file, `get-string-n`returns a string consisting of those count characters. If fewer characters are available before an end of file, but one or more characters can be read, `get-string-n` returns a string containing those characters. In either case, the input port is updated to point just past the characters read. If no characters can be read before an end of file, the end-of-file object is returned.

Function get-string-n! textual-input-port string start count

[R6RS] Start and count must be exact, non-negative integer objects, with count representing the number of characters to be read. String must be a string with at least start + count characters.

The `get-string-n!` procedure reads from textual-input-port in the same manner as `get-string-n`. If count characters are available before an end of file, they are written into string starting at index start, and count is returned. If fewer characters are available before an end of file, but one or more can be read, those characters are written into string starting at index start and the number of characters actually read is returned as an exact integer object. If no characters can be read before an end of file, the end-of-file object is returned.

Function get-string-all textual-input-port

[R6RS] Reads from textual-input-port until an end of file, decoding characters in the same manner as `get-string-n` and `get-string-n!`.

If characters are available before the end of file, a string containing all the characters decoded from that data are returned. If no character precedes the end of file, the end-of-file object is returned.

Function get-line textual-input-port

[R6RS] Reads from textual-input-port up to and including the linefeed character or end of file, decoding characters in the same manner as `get-string-n` and `get-string-n!`.

If a linefeed character is read, a string containing all of the text up to (but not including) the linefeed character is returned, and the port is updated to point just past the linefeed character. If an end of file is encountered before any linefeed character is read, but some characters have been read and decoded as characters, a string containing those characters is returned. If an end of file is encountered before any characters are read, the end-of-file object is returned.

Function get-datum textual-input-port

[R6RS] Reads an external representation from textual-input-port and returns the datum it represents. The `get-datum` procedure returns the next datum that can be parsed from the given textual-input-port, updating textual-input-port to point exactly past the end of the external representation of the object.

If a character inconsistent with an external representation is encountered in the input, an exception with condition types `&lexical` and `&i/o-read`is raised. Also, if the end of file is encountered after the beginning of an external representation, but the external representation is incomplete and therefore cannot be parsed, an exception with condition types `&lexical`and `&i/o-read` is raised.

#### Output ports

An output port is a sink to which bytes or characters are written. The written data may control external devices or may produce files and other objects that may subsequently be opened for input.

Function output-port? obj

[R6RS] Returns #t if obj is an output port (or a combined input and output port), #f otherwise.

Function flush-output-port output-port

[R6RS+][R7RS] Flushes any buffered output from the buffer of output-port to the underlying file, device, or object. The `flush-output-port` procedure returns unspecified values.

If the optional argument is omitted then `(current-output-port)` will be used.

Function output-port-buffer-mode output-port

[R6RS] Returns the symbol that represents the buffer mode of output-port.

Function open-file-output-port filename :optional file-options buffer-mode maybe-transcoder

[R6RS] Maybe-transcoder must be either a transcoder or #f.

The `open-file-output-port` procedure returns an output port for the named file.

The file-options argument, which may determine various aspects of the returned port, defaults to the value of `(file-options)`.

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to `block`.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the port.

If maybe-transcoder is #f or absent, the port will be a binary port, otherwise the port will be textual port.

Function open-bytevector-output-port :optional maybe-transcoder

[R6RS] Maybe-transcoder must be either a transcoder or #f.

The `open-bytevector-output-port` procedure returns two values: an output port and an extraction procedure. The output port accumulates the bytes written to it for later extraction by the procedure.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the port. If maybe-transcoder is #f or absent, the port will be a binary port, otherwise the port will be textual port.

The extraction procedure takes no arguments. When called, it returns a bytevector consisting of all the port's accumulated bytes (regardless of the port's current position), removes the accumulated bytes from the port, and resets the port's position.

Function call-with-bytevector-output-port proc :optional maybe-transcoder

[R6RS] Proc must accept one argument. Maybe-transcoder must be either a transcoder or #f.

The `call-with-bytevector-output-port` procedure creates an output port that accumulates the bytes written to it and calls proc with that output port as an argument. Whenever proc returns, a bytevector consisting of all of the port's accumulated bytes (regardless of the port's current position) is returned and the port is closed.

The transcoder associated with the output port is determined as for a call to `open-bytevector-output-port`.

Function open-string-output-port

[R6RS] Returns two values: a textual output port and an extraction procedure. The output port accumulates the characters written to it for later extraction by the procedure.

The extraction procedure takes no arguments. When called, it returns a string consisting of all of the port's accumulated characters (regardless of the current position), removes the accumulated characters from the port, and resets the port's position.

Function call-with-string-output-port proc

[R6RS] Proc must accept one argument.

The `call-with-string-output-port` procedure creates a textual output port that accumulates the characters written to it and calls proc with that output port as an argument. Whenever proc returns, a string consisting of all of the port's accumulated characters (regardless of the port's current position) is returned and the port is closed.

Function standard-output-port
Function standard-error-port

[R6RS] Returns a fresh binary output port connected to the standard output or standard error respectively.

Function current-output-port :optional port
Function current-error-port :optional port

[R6RS+] If port is given, these procedures set the port as a default port for output and error. These return default ports for regular output and error output.

Function make-custom-binary-output-port id write! get-position set-position! close

[R6RS] Returns a newly created binary output port whose byte sink is an arbitrary algorithm represented by the write! procedure. Id must be a string naming the new port, provided for informational purposes only. _Write!_must be a procedure and should behave as specified below; it will be called by operations that perform binary output.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified in the description of `make-custom-binary-input-port`.

- (write! bytevector start count) Start and count will be non-negative exact integer objects, and bytevector will be a bytevector whose length is at least start + count. The write! procedure should write up to count bytes from bytevector starting at index start to the byte sink. If count is 0, the write! procedure should have the effect of passing an end-of-file object to the byte sink. In any case, the write! procedure should return the number of bytes that it wrote, as an exact integer object.

Function make-custom-string-output-port id write! get-position set-position! close

[R6RS] Returns a newly created textual output port whose byte sink is an arbitrary algorithm represented by the write! procedure. Id must be a string naming the new port, provided for informational purposes only. _Write!_must be a procedure and should behave as specified below; it will be called by operations that perform textual output.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified in the description of `make-custom-textual-input-port`.

- (write! string start count) Start and count will be non-negative exact integer objects, and string will be a string whose length is at least start + count. The write! procedure should write up to count characters from string starting at index start to the character sink. If _count_is 0, the write! procedure should have the effect of passing an end-of-file object to the character sink. In any case, the write! procedure should return the number of characters that it wrote, as an exact integer object.

#### Binary output

Function put-u8 binary-output-port octet

[R6RS] Writes octet to the output port and returns unspecified values.

Function put-bytevector binary-output-port bytevector :optional start count

[R6RS] Start and count must be non-negative exact integer objects that default to 0 and `(bytevector-length _bytevector_)` - start, respectively. Bytevector must have a length of at least start + count. The `put-bytevector` procedure writes the count bytes of the bytevector bytevector starting at index start to the output port. The `put-bytevector` procedure returns unspecified values.

#### Textual output

Function put-char textual-output-port char

[R6RS] Writes char to the port and returns unspecified values.

Function put-string textual-output-port string :optional start count

[R6RS] Start and count must be non-negative exact integer objects. String must have a length of at least start + count. Start defaults to 0. Count defaults to `(string-length _string_)` - start. The `put-string` procedure writes the count characters of string starting at index start to the port. The `put-string` procedure returns unspecified values.

Function put-datum textual-output-port datum

[R6RS] Datum should be a datum value. The `put-datum` procedure writes an external representation of datum to textual-output-port.

#### Input/output ports

Function open-file-input/output-port filename :optional file-options buffer-mode transcoder

[R6RS] Returns a single port that is both an input port and an output port for the named file. The optional arguments default as described in the specification of `open-file-output-port`. If the input/output port supports `port-position` and/or `set-port-position!`, the same port position is used for both input and output.

Function make-custom-binary-input/output-port id read! write! get-position set-position! close :optional (ready #f)

[R6RS+] Returns a newly created binary input/output port whose byte source and sink are arbitrary algorithms represented by the read! and write! procedures. Id must be a string naming the new port, provided for informational purposes only. Read! and write! must be procedures, and should behave as specified for the `make-custom-binary-input-port` and `make-custom-binary-output-port` procedures.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified in the description of `make-custom-binary-input-port`.

Function make-custom-textual-input/output-port id read! write! get-position set-position! close :optional (ready #f)

[R6RS+] Returns a newly created textual input/output port whose byte source and sink are arbitrary algorithms represented by the _read!_and write! procedures. Id must be a string naming the new port, provided for informational purposes only. Read! and write! must be procedures, and should behave as specified for the `make-custom-textual-input-port` and `make-custom-textual-output-port` procedures.

Each of the remaining arguments may be #f; if any of those arguments is not #f, it must be a procedure and should behave as specified in the description of `make-custom-textual-input-port`.

### Simple I/O

This section describes the `(rnrs io simple (6))`library, which provides a somewhat more convenient interface for performing textual I/O on ports.

Library (rnrs io simple (6))

This library also exports the same procedures as `(rnrs io posts (6))` library. I do not write the documentation of it, if you want to import only this library, make sure which procedures are exported. You can see it on R6RS.

Function call-with-input-file filename proc . opt
Function call-with-output-file filename proc . opt

[R6RS+] Proc should accept one argument.

These procedures open the file named by filename for input or for output, with no specified file options, and call proc with the obtained port as an argument. If proc returns, the port is closed automatically and the values returned by proc are returned. If proc does not return, the port is not closed automatically, unless it is possible to prove that the port will never again be used for an I/O operation.

NOTE: opt will be passed to `open-input-file` or `open-output-file`.

Function with-input-from-file filename thunk . opt
Function with-output-to-file filename thunk . opt

[R6RS+] Thunk must be a procedure and must accept zero arguments.

The file is opened for input or output using empty file options, and _thunk_is called with no arguments. These procedure replace current input/output port during thunk is being called. When thunk returns, the port is closed automatically. The values returned by thunk are returned.

NOTE: opt will be passed to `open-input-file` or `open-output-file`.

Function open-input-file filename :key (transcoder (native-transcoder))
Function open-output-file filename :key (transcoder (native-transcoder))

[R6RS+] Opens filename for input/output, with empty file options, and returns the obtained port.

If keyword argument transcoder is given, it must be an transcoder or #f and will be used to specify the transcoder to open input/output port. If it is #f, then returned port will be binary port.

Function close-input-file port
Function close-output-file port

[R6RS] Closes input-port or output-port, respectively.

Function read-char :optional textual-input-port
Function peak-char :optional textual-input-port

[R6RS] These work the same as `get-char` and `lookahead-char`. If textual-input-port is omitted, it defaults to the value returned by `current-input-port`.

Function read :optional textual-input-port

[R6RS] Reads an external representation from _textual-input-port_and returns the datum it represents. The read procedure operates in the same way as get-datum.

If textual-input-port is omitted, it defaults to the value returned by `current-input-port`.

Function write-char char :optional textual-input-port

[R6RS] Writes an encoding of the character char to the textual-output-port, and returns unspecified values.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

Function newline :optional textual-input-port

[R6RS] This is equivalent to using `write-char` to write `#\linefeed` to textual-output-port.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

Function display obj :optional textual-input-port

[R6RS] Writes a representation of obj to the given textual-output-port. Strings that appear in the written representation are not enclosed in double quotes, and no characters are escaped within those strings. Character objects appear in the representation as if written by write-char instead of by write. The display procedure returns unspecified values.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

Function write obj :optional textual-input-port

[R6RS] Writes the external representation of obj to textual-output-port. The `write` procedure operates in the same way as `put-datum`.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

## File system

Library (rnrs files (6))

This library, in addition to the procedures described here, also exports the I/O condition types described in I/O condition types.

Function file-exists? filename

[R6RS] Filename must be a file name (see Port I/O). The `file-exists?` procedure returns #t if the named file exists at the time the procedure is called, #f otherwise.

Function delete-file filename

[R6RS] Filename must be a file name (see Port I/O). The `delete-file` procedure deletes the named file if it exists and can be deleted, and returns unspecified values. If the file does not exist or cannot be deleted, an exception with condition type `&i/o-filename` is raised.

## Command-line access and exit values

Library (rnrs programs (6))

This library provides command-line arguments access and exit procedures.

Function command-line

[R6RS] Returns a nonempty list of strings. The first element is the running script file name or '() on REPL. The remaining elements are command-line arguments according to the operating system's conventions.

Function exit :optional obj

[R6RS] Exits the running program and communicates an exit value to the operating system. If no argument is supplied, the exit procedure should communicate to the operating system that the program exited normally. If an argument is supplied and if it is fixnum, the exit procedure translates it into an appropriate exit value for the operating system. Otherwise the exit is assumed to be abnormal.

## Arithmetic libraries

This section describes Scheme's libraries for more specialized numerical operations: fixnum and flonum arithmetic, as well as bitwise operations on exact integer objects.

### Bitwise operations

A number of procedures operate on the binary two's-complement representations of exact integer objects: Bit positions within an exact integer object are counted from the right, i.e. bit 0 is the least significant bit. Some procedures allow extracting bit fields, i.e., number objects representing subsequences of the binary representation of an exact integer object. Bit fields are always positive, and always defined using a finite number of bits.

### Fixnums

Library (rnrs arithmetic fixnums (6))

On Sagittarius Scheme, fixnum is 30 bits or 62 bits depending on platform. On 32 bits platform it fixnum is 30 bits, and 64 bits platform it is 62 bits. However, non 32 bits platform is not well tested so if you find a bug please send a report.

This section uses fx, fx1 fx2, etc., as parameter names for arguments that must be fixnums.

Function fixnum? obj

[R6RS] Returns #t if obj is an exact integer object within the fixnum range, #f otherwise.

Function fixnum-width
Function least-fixnum
Function greatest-fixnum

[R6RS] These procedures returns bit size of fixnum, minimum and maximum value of the fixnum range, respectively.

Function fx=? fx1 fx2 fx3 ...
Function fx>? fx1 fx2 fx3 ...
Function fx<? fx1 fx2 fx3 ...
Function fx>=? fx1 fx2 fx3 ...
Function fx<=? fx1 fx2 fx3 ...

[R6RS] These procedures return #t if their arguments are: equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, #f otherwise.

Function fxzero? fx
Function fxpositive? fx
Function fxnegative? fx
Function fxodd? fx
Function fxeven? fx

[R6RS] These numerical predicates test a fixnum for a particular property, returning #t or #f. The five properties tested by these procedures are: whether the number object is zero, greater than zero, less than zero, odd, or even.

Function fxmax fx1 fx2 ...
Function fxmin fx1 fx2 ...

[R6RS] These procedures return the maximum or minimum of their arguments.

Function fx+ fx1 fx2
Function fx* fx1 fx2

[R6RS] These procedures return the sum or product of their arguments, provided that sum or product is a fixnum. An exception with condition type `&implementation-restriction` is raised if that sum or product is not a fixnum.

Function fx- fx1 :optional fx2

[R6RS] With two arguments, this procedure returns the difference fx1- fx2, provided that difference is a fixnum.

With one argument, this procedure returns the additive inverse of its argument, provided that integer object is a fixnum.

An exception with condition type `&implementation-restriction` is raised if the mathematically correct result of this procedure is not a fixnum.

NOTE: R6RS says it raises `&assertion` if the result is not fixnum, however Sagittarius raises `&implementation-restriction` for consistency with `fx+` and `fx*`.

Function fxdiv-and-mod fx1 fx2
Function fxdiv fx1 fx2
Function fxmod fx1 fx2
Function fxdiv0-and-mod0 fx1 fx2
Function fxdiv0 fx1 fx2
Function fxmod0 fx1 fx2

[R6RS] Fx2 must be nonzero. These procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations specified in `(rnrs base (6))` section.

Function fx+/carry fx1 fx2 fx3

[R6RS] Returns the two fixnum results of the following computation:

    (let* ((s (+ _fx1_ _fx2_ _fx3_))
           (s0 (mod0 s (expt 2 (fixnum-width))))
           (s1 (div0 s (expt 2 (fixnum-width)))))
      (values s0 s1))

Function fx-/carry fx1 fx2 fx3

[R6RS] Returns the two fixnum results of the following computation:

    (let* ((d (- _fx1_ _fx2_ _fx3_))
           (d0 (mod0 d (expt 2 (fixnum-width))))
           (d1 (div0 d (expt 2 (fixnum-width)))))
      (values d0 d1))

Function fx*/carry fx1 fx2 fx3

[R6RS] Returns the two fixnum results of the following computation:

    (let* ((s (+ (* _fx1_ _fx2_) _fx3_))
           (s0 (mod0 s (expt 2 (fixnum-width))))
           (s1 (div0 s (expt 2 (fixnum-width)))))
      (values s0 s1))

Function fxnot fx

[R6RS] Returns bitwise not of fixnum fx.

Function fxand fx1 ...
Function fxior fx1 ...
Function fxxor fx1 ...

[R6RS] These procedures return the fixnum that is the bit-wise "and", "inclusive or", or "exclusive or" of the two's complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the fixnum (either - 1 or 0) that acts as identity for the operation.

Function fxif fx1 fx2 fx3

[R6RS] Returns the fixnum that is the bit-wise "if" of the two's complement representations of its arguments, i.e. for each bit, if it is 1 in fx1, the corresponding bit in fx2 becomes the value of the corresponding bit in the result, and if it is 0, the corresponding bit in fx3 becomes the corresponding bit in the value of the result. This is the fixnum result of the following computation:

    (fxior (fxand _fx1_ _fx2_)
           (fxand (fxnot _fx1_) _fx3_))

Function fxbit-count fx

[R6RS] If fx is non-negative, this procedure returns the number of 1 bits in the two's complement representation of fx. Otherwise it returns the result of the following computation:

    (fxnot (fxbit-count (fxnot _ei_)))

Function fxlength fx

[R6RS] Returns the number of bits needed to represent fx if it is positive, and the number of bits needed to represent `(fxnot _fx_)` if it is negative, which is the fixnum result of the following computation:

    (do ((result 0 (+ result 1))
         (bits (if (fxnegative? _fx_)
                   (fxnot _fx_)
                   _fx_)
               (fxarithmetic-shift-right bits 1)))
        ((fxzero? bits)
         result))

Function fxfirst-bit-set fx

[R6RS] Returns the index of the least significant 1 bit in the two's complement representation of fx. If fx is 0, then - 1 is returned.

Function fxbit-set? fx1 fx2

[R6RS] Fx2 must be non-negative and less than `(fixnum-width)`. The `fxbit-set?` procedure returns #t if the _fx2_th bit is 1 in the two's complement representation of fx1, and #f otherwise. This is the fixnum result of the following computation:

    (not
      (fxzero?
        (fxand _fx1_           (fxarithmetic-shift-left 1 _fx2_))))

Function fxcopy-bit fx1 fx2 fx3

[R6RS] Fx2 must be non-negative and less than `(fixnum-width)`. Fx3 must be 0 or 1. The `fxcopy-bit` procedure returns the result of replacing the _fx2_th bit of fx1 by fx3, which is the result of the following computation:

    (let* ((mask (fxarithmetic-shift-left 1 _fx2_)))
      (fxif mask
            (fxarithmetic-shift-left _fx3_ _fx2_)
            _fx1_))

Function fxbit-field fx1 fx2 fx3

[R6RS] Fx2 and fx3 must be non-negative and less than `(fixnum-width)`. Moreover, fx2 must be less than or equal to fx3. The `fxbit-field` procedure returns the number represented by the bits at the positions from fx2 (inclusive) to fx3 (exclusive), which is the fixnum result of the following computation:

    (let* ((mask (fxnot
                  (fxarithmetic-shift-left -1 _fx3_))))
      (fxarithmetic-shift-right (fxand _fx1_ mask)
                                _fx2_))

Function fxcopy-bit-field fx1 fx2 fx3 fx4

[R6RS] Fx2 and fx3 must be non-negative and less than `(fixnum-width)`. Moreover, fx2 must be less than or equal to fx3. The `fxcopy-bit-field` procedure returns the result of replacing in fx1 the bits at positions from fx2 (inclusive) to fx3(exclusive) by the corresponding bits in fx4, which is the fixnum result of the following computation:

    (let* ((to    _fx1_)
           (start _fx2_)
           (end   _fx3_)
           (from  _fx4_)
           (mask1 (fxarithmetic-shift-left -1 start))
           (mask2 (fxnot
                   (fxarithmetic-shift-left -1 end)))
           (mask (fxand mask1 mask2)))
      (fxif mask
            (fxarithmetic-shift-left from start)
            to))

Function fxarithmetic-shift fx1 fx2

[R6RS] The absolute value of fx2 must be less than `(fixnum-width)`. If

    (floor (* _fx1_ (expt 2 _fx2_)))

is a fixnum, then that fixnum is returned. Otherwise an exception with condition type `&implementation-restriction` is raised.

Function fxarithmetic-shift-left fx1 fx2
Function fxarithmetic-shift-right fx1 fx2

[R6RS] Fx2 must be non-negative, and less than `(fixnum-width)`. The `fxarithmetic-shift-left` procedure behaves the same as `fxarithmetic-shift`, and `(fxarithmetic-shift-right _fx1_ _fx2_)`behaves the same as `(fxarithmetic-shift _fx1_ (fx- _fx2_))`.

Function fxrotate-bit-field fx1 fx2 fx3 fx4

[R6RS] Fx2, fx3, and fx4 must be non-negative and less than `(fixnum-width)`. Fx2 must be less than or equal to fx3. Fx4 must be less than the difference between fx3 and fx2. The `fxrotate-bit-field` procedure returns the result of cyclically permuting in fx1 the bits at positions from fx2 (inclusive) to fx3(exclusive) by fx4 bits towards the more significant bits, which is the result of the following computation:

    (let* ((n     _fx1_)
           (start _fx2_)
           (end   _fx3_)
           (count _fx4_)
           (width (fx- end start)))
      (if (fxpositive? width)
          (let* ((count (fxmod count width))
                 (field0
                   (fxbit-field n start end))
                 (field1
                   (fxarithmetic-shift-left
                     field0 count))
                 (field2
                   (fxarithmetic-shift-right
                     field0 (fx- width count)))
                 (field (fxior field1 field2)))
            (fxcopy-bit-field n start end field))
          n))

Function fxreverse-bit-field fx1 fx2 fx3

[R6RS] Fx2 and fx3 must be non-negative and less than `(fixnum-width)`. Moreover, fx2 must be less than or equal to fx3. The `fxreverse-bit-field` procedure returns the fixnum obtained from fx1 by reversing the order of the bits at positions from fx2(inclusive) to fx3 (exclusive).

### Flonums

This section describes the `(rnrs arithmetic flonums (6))`library.

This section uses fl, fl1, fl2, etc., as parameter names for arguments that must be flonums, and ifl as a name for arguments that must be integer-valued flonums, i.e., flonums for which the `integer-valued?`predicate returns true.

Library (rnrs arithmetic flonums (6))

[R6RS] This library exports procedures for flonum operations.

Function flonum? obj

[R6RS] Returns #t if obj is a flonum, #f otherwise.

Function fl=? fl1 fl2 fl3 ...
Function fl>? fl1 fl2 fl3 ...
Function fl<? fl1 fl2 fl3 ...
Function fl>=? fl1 fl2 fl3 ...
Function fl<=? fl1 fl2 fl3 ...

[R6RS] These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, #f otherwise.

Function flinteger? fl
Function flzero? fl
Function flpositive? fl
Function flnegative? fl
Function flodd? fl
Function fleven? fl
Function flfinite? fl
Function flinfinite? fl
Function flnan? fl

[R6RS] These numerical predicates test a flonum for a particular property, returning #t or #f. The `flinteger?` procedure tests whether the number object is an integer, `flzero?` tests whether it is `fl=?` to zero, `flpositive?` tests whether it is greater than zero, `flnegative?`tests whether it is less than `zero`, `flodd?` tests whether it is odd, `fleven?` tests whether it is even, `flfinite?` tests whether it is not an infinity and not a NaN, `flinfinite?` tests whether it is an infinity, and `flnan?` tests whether it is a NaN.

Function flmax fl1 fl2 ...
Function flmin fl1 fl2 ...

[R6RS] These procedures return the maximum or minimum of their arguments. They always return a NaN when one or more of the arguments is a NaN.

Function fl+ fl1 ...
Function fl* fl1 ...

[R6RS] These procedures return the flonum sum or product of their flonum arguments. In general, they should return the flonum that best approximates the mathematical sum or product.

Function flabs fl

[R6RS] Returns the absolute value of fl.

Function fldiv-and-mod fl1 fl2
Function fldiv fl1 fl2
Function flmod fl1 fl2
Function fldiv0-and-mod0 fl1 fl2
Function fldiv0 fl1 fl2
Function flmod0 fl1 fl2

[R6RS] These procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations (see `(rnrs base (6))` . For zero divisors, these procedures may return a NaN or some unspecified flonum.

Function flnumerator fl
Function fldenominator fl

[R6RS] These procedures return the numerator or denominator of fl as a flonum; the result is computed as if fl was represented as a fraction in lowest terms. The denominator is always positive. The denominator of 0.0 is defined to be 1.0.

Function flfloor fl
Function flceiling fl
Function fltruncate fl
Function flround fl

[R6RS] These procedures return integral flonums for flonum arguments that are not infinities or NaNs. For such arguments, `flfloor` returns the largest integral flonum not larger than fl. The `flceiling` procedure returns the smallest integral flonum not smaller than fl. The `fltruncate`procedure returns the integral flonum closest to fl whose absolute value is not larger than the absolute value of fl. The `flround` procedure returns the closest integral flonum to fl, rounding to even when _fl_represents a number halfway between two integers.

Although infinities and NaNs are not integer objects, these procedures return an infinity when given an infinity as an argument, and a NaN when given a NaN.

Function flexp fl
Function fllog fl1 :optional fl2
Function flsin fl
Function flcos fl
Function fltan fl
Function flasin fl
Function flacos fl
Function flatan fl1 :optional fl2

[R6RS] These procedures compute the usual transcendental functions. The `flexp`procedure computes the base-e exponential of fl. The `fllog` procedure with a single argument computes the natural logarithm of `fl1` (not the base ten logarithm); `(fllog _fl1_ _fl2_)` computes the base-_fl2_logarithm of fl1. The `flasin`, `flacos`, and `flatan`procedures compute arcsine, arccosine, and arctangent, respectively. `(flatan _fl1_ _fl2_)` computes the arc tangent of fl1/fl2.

Function flsqrt fl

[R6RS] Returns the principal square root of fl. For - 0.0, `flsqrt`returns 0.0; for other negative arguments, the result unspecified flonum.

Function flexpt fl1 fl2

[R6RS] Either fl1 should be non-negative, or, if fl1 is negative, fl2 should be an integer object. The `flexpt` procedure returns _fl1_raised to the power fl2. If fl1 is negative and fl2 is not an integer object, the result is a NaN. If fl1 is zero, then the result is zero.

Condition Type &no-infinities
Function make-no-infinities-violation obj
Function no-invinities-violation? obj
Condition Type &no-nans
Function make-no-nans-violation obj
Function no-nans-violation? obj

[R6RS] These types describe that a program has executed an arithmetic operations that is specified to return an infinity or a NaN, respectively.

Here is the hierarchy of these conditions.

    + &implementation-restriction (see ["Conditions"](#rnrs.conditions.6))
        + &no-infinities
        + &no-nans

Function fixnum->flonum fx

[R6RS] Returns a flonum that is numerically closest to fx.

### Exact bitwise arithmetic

This section describes the `(rnrs arithmetic bitwise (6))`library. The exact bitwise arithmetic provides generic operations on exact integer objects. This section uses ei, ei1, ei2, etc., as parameter names that must be exact integer objects.

Library (rnrs arithmetic bitwise (6))

[R6RS] This library exports procedures for exact bitwise arithmetic operations.

Function bitwise-not ei

[R6RS] Returns the exact integer object whose two's complement representation is the one's complement of the two's complement representation of ei.

Function bitwise-and ei1 ...
Function bitwise-ior ei1 ...
Function bitwise-xor ei1 ...

[R6RS] These procedures return the exact integer object that is the bit-wise "and", "inclusive or", or "exclusive or" of the two's complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the integer object (either - 1 or 0) that acts as identity for the operation.

Function bitwise-if ei1 ei2 ei3

[R6RS] Returns the exact integer object that is the bit-wise "if" of the two's complement representations of its arguments, i.e. for each bit, if it is 1 in ei1, the corresponding bit in ei2 becomes the value of the corresponding bit in the result, and if it is 0, the corresponding bit in ei3 becomes the corresponding bit in the value of the result. This is the result of the following computation:

    (bitwise-ior (bitwise-and _ei1_ _ei2_)
                 (bitwise-and (bitwise-not _ei1_) _ei3_))

Function bitwise-bit-count ei

[R6RS] If ei is non-negative, this procedure returns the number of 1 bits in the two's complement representation of ei. Otherwise it returns the result of the following computation:

    (bitwise-not (bitwise-bit-count (bitwise-not _ei_)))

Function bitwise-length ei

[R6RS] Returns the number of bits needed to represent ei if it is positive, and the number of bits needed to represent `(bitwise-not _ei_)` if it is negative, which is the exact integer object that is the result of the following computation:

    (do ((result 0 (+ result 1))
         (bits (if (negative? _ei_)
                   (bitwise-not _ei_)
                   _ei_)
               (bitwise-arithmetic-shift bits -1)))
        ((zero? bits)
         result))

Function bitwise-first-bit-set ei

[R6RS] Returns the index of the least significant 1 bit in the two's complement representation of ei. If ei is 0, then - 1 is returned.

Function bitwise-bit-set? ei1 ei2

[R6RS] Ei2 must be non-negative. The `bitwise-bit-set?`procedure returns #t if the _ei2_th bit is 1 in the two's complement representation of ei1, and #f otherwise. This is the result of the following computation:

    (not (zero?
           (bitwise-and
             (bitwise-arithmetic-shift-left 1 _ei2_)
             _ei1_)))

Function bitwise-copy-bit ei1 ei2 ei3

[R6RS] Ei2 must be non-negative, and ei3 must be either 0 or 1. The `bitwise-copy-bit` procedure returns the result of replacing the _ei2_th bit of ei1 by the _ei2_th bit of ei3, which is the result of the following computation:

    (let* ((mask (bitwise-arithmetic-shift-left 1 _ei2_)))
      (bitwise-if mask
                (bitwise-arithmetic-shift-left _ei3_ _ei2_)
                _ei1_))

Function bitwise-bit-field ei1 ei2 ei3

[R6RS] Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. The `bitwise-bit-field` procedure returns he number represented by the bits at the positions from ei2 (inclusive) to ei3 (exclusive), which is the result of the following computation:

    (let ((mask
           (bitwise-not
            (bitwise-arithmetic-shift-left -1 _ei3_))))
      (bitwise-arithmetic-shift-right
        (bitwise-and _ei1_ mask)
        _ei2_))

Function bitwise-copy-bit-field ei1 ei2 ei3 ei4

[R6RS] Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. The `bitwise-copy-bit-field` procedure returns the result of replacing in ei1 the bits at positions from var{ei2} (inclusive) to ei3 (exclusive) by the corresponding bits in ei4, which is the fixnum result of the following computation:

    (let* ((to    _ei1_)
           (start _ei2_)
           (end   _ei3_)
           (from  _ei4_)
           (mask1
             (bitwise-arithmetic-shift-left -1 start))
           (mask2
             (bitwise-not
               (bitwise-arithmetic-shift-left -1 end)))
           (mask (bitwise-and mask1 mask2)))
      (bitwise-if mask
                  (bitwise-arithmetic-shift-left from
                                                 start)
                  to))

Function bitwise-arithmetic-shift ei1 ei2

[R6RS] Returns the result of the following computation:

    (floor (* _ei1_ (expt 2 _ei2_)))

ei2 must be a fixnum. This is implementation restriction.

Function bitwise-arithmetic-shift-left ei1 ei2
Function bitwise-arithmetic-shift-right ei1 ei2

[R6RS] Ei2 must be non-negative. The `bitwise-arithmetic-shift-left` procedure returns the same result as `bitwise-arithmetic-shift`, and

    (bitwise-arithmetic-shift-right _ei1_ _ei2_)

returns the same result as

    (bitwise-arithmetic-shift _ei1_ (- _ei2_))

.

ei2 must be a fixnum. This is implementation restriction.

Function bitwise-rotate-bit-field ei1 ei2 ei3 ei4

[R6RS] Ei2, ei3, ei4 must be non-negative, _ei2_must be less than or equal to ei3, and ei4 must be non-negative. The `bitwise-rotate-bit-field` procedure returns the result of cyclically permuting in ei1 the bits at positions from ei2 (inclusive) to ei3 (exclusive) by ei4 bits towards the more significant bits, which is the result of the following computation:

    (let* ((n     _ei1_)
           (start _ei2_)
           (end   _ei3_)
           (count _ei4_)
           (width (- end start)))
      (if (positive? width)
          (let* ((count (mod count width))
                 (field0
                   (bitwise-bit-field n start end))
                 (field1 (bitwise-arithmetic-shift-left
                           field0 count))
                 (field2 (bitwise-arithmetic-shift-right
                           field0
                           (- width count)))
                 (field (bitwise-ior field1 field2)))
            (bitwise-copy-bit-field n start end field))
          n))

ei4 must be a fixnum. This is implementation restriction.

Function bitwise-reverse-bit-field ei1 ei2 ei3

[R6RS] Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. The `bitwise-reverse-bit-field` procedure returns the result obtained from ei1 by reversing the order of the bits at positions from ei2 (inclusive) to ei3 (exclusive).

## Syntax-case

Library (rnrs syntax-case (6))

[R6RS] The `(rnrs syntax-case (6))`library provides support for writing low-level macros in a high-level style, with automatic syntax checking, input destructuring, output restructuring, maintenance of lexical scoping and referential transparency (hygiene), and support for controlled identifier capture.

Syntax syntax-case expression (literal ... ) clause ...

[R6RS] Each literal must be an identifier. Each clause must take one of the following two forms.

    (_pattern_ _output-expression_)

    (_pattern_ _fender_ _output-expression_)

Fender and output-expression must be expressions.

Pattern is the same as `syntax-rules`. See (rnrs base (6)) section.

A `syntax-case` expression first evaluates expression. It then attempts to match the pattern from the first clause against the resulting value, which is unwrapped as necessary to perform the match. If the _pattern_matches the value and no fender is present, output-expression is evaluated and its value returned as the value of the `syntax-case` expression. If the pattern does not match the value, `syntax-case` tries the second clause, then the third, and so on. It is a syntax violation if the value does not match any of the patterns.

If the optional fender is present, it serves as an additional constraint on acceptance of a clause. If the pattern of a given clause matches the input value, the corresponding fender is evaluated. If fender evaluates to a true value, the clause is accepted; otherwise, the clause is rejected as if the pattern had failed to match the value. Fenders are logically a part of the matching process, i.e., they specify additional matching constraints beyond the basic structure of the input.

Pattern variables contained within a clause's pattern are bound to the corresponding pieces of the input value within the clause's fender (if present) and output-expression. Pattern variables can be referenced only within syntax expressions (see below). Pattern variables occupy the same name space as program variables and keywords.

If the `syntax-case` form is in tail context, the `output-expressions`are also in tail position.

Syntax syntax template

[R6RS] A template is a pattern variable, an identifier that is not a pattern variable, a pattern datum, or one of the following.

    (_subtemplate_ ...)

    (_subtemplate_ ... . _template_)

    #(_subtemplate_ ...)

A subtemplate is a template followed by zero or more ellipses.

The value of a `syntax` form is a copy of template in which the pattern variables appearing within the template are replaced with the input subforms to which they are bound. Pattern data and identifiers that are not pattern variables or ellipses are copied directly into the output. A subtemplate followed by an ellipsis expands into zero or more occurrences of the subtemplate. Pattern variables that occur in subpatterns followed by one or more ellipses may occur only in subtemplates that are followed by (at least) as many ellipses. These pattern variables are replaced in the output by the input subforms to which they are bound, distributed as specified. If a pattern variable is followed by more ellipses in the subtemplate than in the associated subpattern, the input form is replicated as necessary. The subtemplate must contain at least one pattern variable from a subpattern followed by an ellipsis, and for at least one such pattern variable, the subtemplate must be followed by exactly as many ellipses as the subpattern in which the pattern variable appears.

Function identifier? obj

[R6RS] Returns #t if obj is an identifier, i.e., a syntax object representing an identifier, and #f otherwise.

Function bound-identifier=? id1 id2

[R6RS] Id1 and id2 must be identifiers. The procedure `bound-identifier=?` returns #t if given arguments are exactly the same object.

The bound-identifier=? procedure can be used for detecting duplicate identifiers in a binding construct or for other preprocessing of a binding construct that requires detecting instances of the bound identifiers.

Function free-identifier=? id1 id2

[R6RS] Id1 and id2 must be identifiers. The `free-identifier=?`procedure returns #t if given arguments are indicating the same bindings.

Function syntax->datum syntax-object

[R6RS] Strips all syntactic information from a syntax object and returns the corresponding Scheme datum.

Function datum->syntax template-id datum

[R6RS] Template-id must be a template identifier and _datum_should be a datum value.

The `datum->syntax` procedure returns a syntax-object representation of datum that contains the same contextual information as template-id, with the effect that the syntax object behaves as if it were introduced into the code when template-id was introduced.

The `datum->syntax` procedure allows a transformer to "bend" lexical scoping rules by creating implicit identifiers that behave as if they were present in the input form, thus permitting the definition of macros that introduce visible bindings for or references to identifiers that do not appear explicitly in the input form. For example, the following defines a `loop` expression that uses this controlled form of identifier capture to bind the variable break to an escape procedure within the loop body.

    (define-syntax loop
      (lambda (x)
        (syntax-case x ()
          [(k e ...)
           (with-syntax
               ([break (datum->syntax (syntax k) 'break)])
             (syntax
    	  (call-with-current-continuation
    	   (lambda (break)
    	     (let f () e ... (f))))))])))

    (let ((n 3) (ls '()))
      (loop
        (if (= n 0) (break ls))
        (set! ls (cons 'a ls))
        (set! n (- n 1))))

(a a a)

Function generate-temporaries l

[R6RS] L must be a list or syntax object representing a list-structured form. The number of temporaries generated is the number of elements in l. Each temporary is guaranteed to be unique.

NOTE: If you want to create just one temporary symbol and do not think about portability, it's better to use `gensym` in `(sagittarius)` library.

Macro with-syntax ((pattern expression) ... ) body

[R6RS] The `with-syntax` form is used to bind pattern variables, just as `let` is used to bind variables. This allows a transformer to construct its output in separate pieces, then put the pieces together.

Each pattern is identical in form to a `syntax-case` pattern. The value of each expression is computed and destructured according to the corresponding pattern, and pattern variables within the pattern are bound as with `syntax-case` to the corresponding portions of the value within body.

Macro quasisyntax template
Auxiliary Macro unsyntax
Auxiliary Macro unsyntax-splicing

[R6RS] The `quasisyntax` form is similar to `syntax`, but it allows parts of the quoted text to be evaluated, in a manner similar to the operation of `quasiquote`.

Within a `quasisyntax` template, subforms of `unsyntax` and `unsyntax-splicing` forms are evaluated, and everything else is treated as ordinary template material, as with `syntax`. The value of each `unsyntax` subform is inserted into the output in place of the `unsyntax`form, while the value of each `unsyntax-splicing` subform is spliced into the surrounding list or vector structure. Uses of `unsyntax` and `unsyntax-splicing` are valid only within `quasisyntax` expressions.

A `quasisyntax` expression may be nested, with each `quasisyntax`introducing a new level of syntax quotation and each `unsyntax` or `unsyntax-splicing` taking away a level of quotation. An expression nested within n `quasisyntax` expressions must be within n `unsyntax` or `unsyntax-splicing` expressions to be evaluated.

Function syntax-violation who message form :optional subform

[R6RS] Who must be #f or a string or a symbol. Message must be a string. Form must be a syntax object or a datum value. Subform must be a syntax object or a datum value.

The `syntax-violation` procedure raises an exception, reporting a syntax violation. Who should describe the macro transformer that detected the exception. The message argument should describe the violation. _Form_should be the erroneous source syntax object or a datum value representing a form. The optional subform argument should be a syntax object or datum value representing a form that more precisely locates the violation.

## Hashtables

The `(rnrs hashtables (6))`library provides a set of operations on hashtables. A hashtable is a data structure that associates keys with values. Any object can be used as a key, provided a hash function and a suitable equivalence function is available. A hash function is a procedure that maps keys to exact integer objects. It is the programmer's responsibility to ensure that the hash function is compatible with the equivalence function, which is a procedure that accepts two keys and returns true if they are equivalent and #f otherwise. Standard hashtables for arbitrary objects based on the `eq?` and `eqv?` predicates are provided. Also, hash functions for arbitrary objects, strings, and symbols are provided.

This section uses the hashtable parameter name for arguments that must be hashtables, and the key parameter name for arguments that must be hashtable keys.

Library (rnrs hashtable (6))

[R6RS] This library exports a set of operations on hashtables.

### Constructors

Function make-eq-hashtable :optional k weakness
Function make-eqv-hashtable :optional k weakness

[R6RS+] Returns a newly allocated mutable hashtable that accepts arbitrary objects as keys, and compares those keys with `eq?`(`make-eq-hashtable`) or `eqv?` (`make-eqv-hashtable`).

If optional argument k is given, it must be exact non-negative integer or `#f`. If it's `#f`, then the procedure picks up default initial capacity, otherwise the initial capacity of the hashtable is set to approximately k elements.

If optional argument weakness is given, then it must be one of the symbols `key`, `value` or `both`, or `#f`. If the value is one of the symbols, then the procedure creates weak hashtable of given symbol's weakness. If the symbol is `key`, then entries whose keys are refered only from this hashtable might be removed when garbage collection is occurred. `value` is for entry values. `both` is for both.

Function make-hashtable hash-function equiv :optional k weakness

[R6RS] Hash-function and equiv must be procedures.

Hash-function should accept a key as an argument and should return a non-negative exact integer object. Equiv should accept two keys as arguments and return a single value.

The `make-hashtable` procedure returns a newly allocated mutable hashtable using hash-function as the hash function and equiv as the equivalence function used to compare keys.

If optional argument k and weakness are the same as `make-eq-hashtable` and `make-eqv-hashtable`.

### Procedures

Function hashtable? obj

[R6RS] Returns #t if obj is a hashtable, #f otherwise.

Function hashtable-size hashtable

[R6RS] Returns the number of keys contained in hashtable as an exact integer object.

Function hashtable-ref hashtable key :optional (default #f)

[R6RS+] Returns the value in hashtable associated with key. If hashtable does not contain an association for key, default is returned.

Since Sagittarius version 0.3.4, this procedure's default argument is optional to implement SRFI-17 efficiently.

Function hashtable-set! hashtable key obj

[R6RS] Changes hashtable to associate key with obj, adding a new association or replacing any existing association for key, and returns unspecified values.

Function hashtable-delete! hashtable key

[R6RS] Removes any association for key within hashtable and returns unspecified values.

Function hashtable-contains? hashtable key

[R6RS] Returns #t if hashtable contains an association for key, #f otherwise.

Note: On Sagittarius, `hashtable-ref` and `hashtable-contains?` do not make any difference fot the performance.

Function hashtable-update! hashtable key proc default

desc{[R6RS] Proc should accept one argument, should return a single value.

The `hashtable-update!` procedure applies proc to the value in hashtable associated with key, or to default if hashtable does not contain an association for key. The hashtable is then changed to associate key with the value returned by proc. }

Function hashtable-copy hashtable :optional mutable

[R6RS] Returns a copy of hashtable. If the mutable argument is provided and is true, the returned hashtable is mutable; otherwise it is immutable.

Function hashtable-clear hashtable :optional k

[R6RS] Removes all associations from hashtable and returns unspecified values.

If a second argument is given, the current capacity of the hashtable is reset to approximately k elements.

Function hashtable-keys hashtable
Function hashtable-entries hashtable

[R6RS] Returns a vector of all keys or entries in hashtable, respectively. The order of the vector is unspecified.

### Inspection

Function hashtable-equivalence-function hashtable
Function hashtable-hash-function hashtable

[R6RS] Returns the equivalence or hash function used by _hashtable_respectively.

Function hashtable-mutable? hashtable

[R6RS] Returns #t if hashtable is mutable, otherwise #f.

### Hash functions

Function equal-hash obj
Function symbol-hash symbol

[R6RS] Returns hash value of given argument. Each procedures return the hash values suitable for `equal?` and symbols.

Function string-hash string :optional bound start end
Function string-ci-hash string :optional bound start end

[R6RS+][SRFI-13] Returns hash value of given argument. Each procedures return the hash values suitable for `string=?` and `string-ci=?`.

If the optional argument start and end is given, then the given string will be substringed with start and end.

If the optional argument bound is given, it must be exact integer and hash function will also use the given value.

## Enumerations

This section describes the `(rnrs enums (6))`library for dealing with enumerated values and sets of enumerated values. Enumerated values are represented by ordinary symbols, while finite sets of enumerated values form a separate type, known as the enumeration sets. The enumeration sets are further partitioned into sets that share the same universe and enumeration type. These universes and enumeration types are created by the `make-enumeration`procedure. Each call to that procedure creates a new enumeration type.

Library (rnrs enums (6))

[R6RS] This library interprets each enumeration set with respect to its specific universe of symbols and enumeration type. This facilitates efficient implementation of enumeration sets and enables the complement operation.

In the descriptions of the following procedures, enum-set ranges over the enumeration sets, which are defined as the subsets of the universes that can be defined using make-enumeration.

Function make-enumeration symbol-list

[R6RS] Symbol-list must be a list of symbols.

The `make-enumeration` procedure creates a new enumeration type whose universe consists of those symbols (in canonical order of their first appearance in the list) and returns that universe as an enumeration set whose universe is itself and whose enumeration type is the newly created enumeration type.

Function enum-set-universe enum-set

[R6RS] Returns the set of all symbols that comprise the universe of its argument, as an enumeration set.

Function enum-set-indexer enum-set

[R6RS] Returns a unary procedure that, given a symbol that is in the universe of enum-set, returns its 0-origin index within the canonical ordering of the symbols in the universe; given a value not in the universe, the unary procedure returns #f.

Function enum-set-constructor enum-set

[R6RS] Returns a unary procedure that, given a list of symbols that belong to the universe of enum-set, returns a subset of that universe that contains exactly the symbols in the list. The values in the list must all belong to the universe.

Function enum-set->list enum-set

[R6RS] Returns a list of the symbols that belong to its argument, in the canonical order of the universe of enum-set.

Function enum-set-member symbol enum-set
Function enum-set-subst? enum-set1 enum-set2
Function enum-set=? enum-set1 enum-set2

[R6RS] The `enum-set-member?` procedure returns #t if its first argument is an element of its second argument, #f otherwise.

The `enum-set-subset?` procedure returns #t if the universe of enum-set1 is a subset of the universe of enum-set2 (considered as sets of symbols) and every element of enum-set1 is a member of enum-set2. It returns #f otherwise.

The `enum-set=?` procedure returns #t if enum-set1 is a subset of enum-set2 and vice versa, as determined by the `enum-set-subset?`procedure. This implies that the universes of the two sets are equal as sets of symbols, but does not imply that they are equal as enumeration types. Otherwise, #f is returned.

Function enum-set-union enum-set1 enum-set2
Function enum-set-intersection enum-set1 enum-set2
Function enum-set-difference enum-set1 enum-set2

[R6RS] Enum-set1 and enum-set2 must be enumeration sets that have the same enumeration type.

The `enum-set-union` procedure returns the union of enum-set1 and enum-set2.

The `enum-set-intersection` procedure returns the intersection of enum-set1 and enum-set2.

The `enum-set-difference` procedure returns the difference of _enum-set1_and enum-set2.

Function enum-set-complement enum-set

[R6RS] Returns enum-set's complement with respect to its universe.

Function enum-set-projection enum-set1 enum-set2

[R6RS] Projects enum-set1 into the universe of enum-set2, dropping any elements of enum-set1 that do not belong to the universe of enum-set2. (If enum-set1 is a subset of the universe of its second, no elements are dropped, and the injection is returned.)

Macro define-enumeration type-name (symbol ... ) constructor-syntax

[R6RS] The `define-enumeration` form defines an enumeration type and provides two macros for constructing its members and sets of its members.

A `define-enumeration` form is a definition and can appear anywhere any other definition can appear.

Type-name is an identifier that is bound as a syntactic keyword; symbol ... are the symbols that comprise the universe of the enumeration (in order).

`(_type-name_ _symbol_)` checks at macro-expansion time whether the name of symbol is in the universe associated with type-name. If it is, `(_type-name_ _symbol_)` is equivalent to symbol. It is a syntax violation if it is not.

Constructor-syntax is an identifier that is bound to a macro that, given any finite sequence of the symbols in the universe, possibly with duplicates, expands into an expression that evaluates to the enumeration set of those symbols.

`(_constructor-syntax_ _symbol ..._)` checks at macro-expansion time whether every symbol ... is in the universe associated with type-name. It is a syntax violation if one or more is not. Otherwise

    (_constructor-syntax_ _symbol ..._)

is equivalent to

    ((enum-set-constructor (_constructor-syntax_))
     '(_symbol ..._))

.

## Composite libraries

### eval

Library (rnrs eval (6))

[R6RS]The `(rnrs eval (6))` library allows a program to create Scheme expressions as data at run time and evaluate them.

Function eval expression environment

[R6RS] Evaluates expression in the specified environment and returns its value. Expression must be a syntactically valid Scheme expression represented as a datum value.

R6RS requires envionment an envitonment which must be created by the `environment` procedure. However on Sagittarius, environment can be anything. This behaviour might be fixed in future.

Function environment import-spec ...

[R6RS] Import-spec must be a datum representing an import spec. The `environment` procedure returns an environment corresponding to import-spec.

### Mutable pairs

Library (rnrs mutable-pairs (6))

[R6RS] This library exports `set-car!` and `set-cdr!`.

Function set-car! pair obj
Function set-cdr! pair obj

[R6RS] Store obj in the car/cdr field of pair. These procedures return unspecified value.

On Sagittarius Scheme, these procedures can modify immutable pairs.

### Mutable strings

Library (rnrs mutable-stringss (6))

[R6RS] This library exports `string-set!` and `string-fill!`.

Function string-set! string k char

[R6RS] K must be a valid index of string.

The `string-set!` procedure stores char in element k of string and returns unspecified values.

Function string-fill! string char :optional (start 0) (end `(string-length _string_)` )

[R6RS+] Stores char in every element of the given string and returns unspecified values. Optional arguments start and end restrict the ragne of filling.

Passing an immutable string to these procedures cause an exception with condition type `&assertion` to be raised.

### R5RS compatibility

Library (rnrs r5rs (6))

This library provides R5RS compatibility procedures such as `exact->inexact`.

Function exact->inexect z
Function inexact->exect z

[R6RS] These are the same as the `inexact` and `exact` procedures.

Function quotient n1 n2
Function remainder n1 n2
Function modulo n1 n2

[R6RS] Returns the quotient, remainder and modulo of dividing an integer n1 by an integer n2, respectively. The result is an exact number only if both n1 and n2 are exact numbers.

Macro delay expression

[R6RS] The `delay` construct is used together with the procedure `force` to implement lazy evaluation or call by need. `(delay _expression_)` returns an object called a promise which at some point in the future may be asked (by the `force` procedure) to evaluate expression, and deliver the resulting value. The effect of expression returning multiple values is unspecified.

Function force promise

[R6RS] Promise must be a promise.

The `force` procedure forces the value of promise. If no value has been computed for the promise, then a value is computed and returned. The value of the promise is cached (or "memoized") so that if it is forced a second time, the previously computed value is returned.

Function null-environment n
Function scheme-report-environment n

[R6RS] N must be the exact integer object 5. These procedures return an environment which is suitable to use with `eval`.

# R7RS Support

Sagittarius supports the latest Scheme standard R7RS. Even though the R7RS has incompatible from R6RS, however users can use both R6RS and R7RS libraries seamlessly.

## R7RS library system

On Sagittarius, user can call R7RS libraries on R6RS script and also other way around. However syntaxes are different. User can choose which syntax use.

Syntax define-library name clauses

[R7RS]name must be a list which can only contains symbol or exact integer.

clauses may be one of these:

- (`export` export-spec ...)

- (`import` import-set ...)

- (`begin` command-or-definition ...)

- (`include` filenames ...)

- (`include-ci` filenames ...)

- (`include-library-declarations` filenames ...)

- (`cond-expand` cond-expand-clause ...)

`export` and `import` are the same as R6RS. And on R7RS renaming export syntax is different from R6RS, however on Sagittarius both can be accepted.

`begin` starts the library contents. However it can appear more than once.

`include` and `include-ci` includes the files which are specified filenames. filenames must be string. This resolves file path from current loading file. If the library file is /usr/local/lib/lib1.scm, then search path will be /usr/local/lib. It can also take absolute path. `include-ci` reads the file case insensitive.

`cond-exnpand` is the same as builtin syntax `cond-expand`. For more detail, see Builtin Syntax.

## R7RS libraries

Sagittarius supports all R7RS libraries. However to avoid duplication, this section only describes the different procedures from R6RS. The same procedures are explicitly said 'the same as R6RS'.

### Base library

Library (scheme base)

[R7RS]R7RS base library.

These procedures/macros are the same as R6RS;

     * + - ... / < <= = => > >=

     abs and append apply assoc assq assv

     begin binary-port? boolean=? boolean?
     bytevector-copy bytevector-length bytevector-u8-ref
     bytevector-u8-set! bytevector?

     caar cadr call-with-current-continuation call-with-port
     call-with-values call/cc car case cdar cddr cdr ceiling
     char->integer char<=? char<? char=? char>=? char>? char?
     close-input-port close-output-port close-port complex?
     cond cons current-error-port current-input-port current-output-port

     define define-record-type define-syntax denominator do dynamic-wind

     else eof-object eof-object? eq? eqv? error even?
     exact exact-integer-sqrt exact? expt

     floor flush-output-port for-each

     gcd guard

     if inexact inexact? input-port? integer->char integer?

     lambda lcm length let let* let*-values let-values
     letrec letrec* list list->string list->vector
     list-ref list-tail list?

     make-bytevector make-string make-vector map max member memq memv min
     modulo

     negative? newline not null? number->string number? numerator

     odd? or output-port?

     pair? peek-char port? positive? procedure?

     quasiquote quote quotient

     raise raise-continuable rational? rationalize
     read-char real? remainder reverse round

     set! set-car! set-cdr!
     string string->list string->number string->symbol string->utf8
     string-append string-copy string-for-each string-length string-ref
     string-fill! string-set!
     string<=? string<? string=? string>=? string>? string? substring
     symbol->string symbol=? symbol? syntax-rules

     textual-port? truncate

     unless unquote unquote-splicing utf8->string

     values vector vector->list vector-fill! vector-for-each vector-length
     vector-map vector-ref vector-set! vector?

     when with-exception-handler write-char

     zero?

This is defined in (sagittarius);

    cond-expand

#### Bytevectors

Function bytevector bytes ...

bytes must be a list of non negative exact integer and its value is up to 255.

Creates a bytevector whose content is values of bytes.

Function bytevector-append bytevectors ...

Returns a newly allocated bytevector whose contents are the concatenation of the contents in bytevectors.

NOTE: R6RS also has the same named procedure and does the same however the arguments lists are different.

Function bytevector-copy! to at from :optional (start 0) (end (bytevector-length from))

to and from must be bytevectors. at must be a non negative exact integer in range of to size. Optional arguments start and end must be non negative exact integer in range of from and end must be bigger than end.

Copies content of from starting from start until end (exclusive) to to starting at. The operation is done destructively.

#### Lists

Function list-copy obj

Returns a newly allocated copy of obj if it is a list. The list elements stays intact. So changing element's content affects original obj.

Function list-set! list index value

Stores value in element index of list.

Function make-list k :optional fill

Creates a list whose size is k.

If the optional argument fill is given then returning list is filled with fill, otherwise unspecified value is used.

#### Vectors

Function vector->string vector :optional (start 0) (end (vector-length vector))

vector must be a vector whose elements of range from _start_to end (exclusive) are characters.

Returns a string constructed with the above range of characters.

Function string->vector string :optional (start 0) (end (string-length string))

Returns a vector whose elements are characters of string in range of start and end (exclusive).

Function vector-append vectors ...

Returns a newly allocated vector whose contents are the concatenation of the contents in vectors.

Function vector-copy vector :optional (start 0) (end (vector-length vector))

Returns a vector whose elements are elements of given _vector_between start and end.

Function vector-copy! to at from :optional (start 0) (end (vector-length from))

to and from must be vectors. at must be a non negative exact integer in range of to size. Optional arguments start and end must be non negative exact integer in range of from and end must be bigger than end.

Copies content of from starting from start until end (exclusive) to to starting at. The operation is done destructively.

#### Strings

Function string-copy! to at from :optional (start 0) (end (vector-length from))

to and from must be strings. at must be a non negative exact integer in range of to size. Optional arguments start and end must be non negative exact integer in range of from and end must be bigger than end.

Copies content of from starting from start until end (exclusive) to to starting at. The operation is done destructively.

Function string-map proc string strings ...

Calls proc with given strings elements and returns a string whose content is constructed by the results of proc.

#### Parameters

Function make-parameter init :optional converter

[SRFI-39] Returns a parameter object, which is an applicable object that can take zero or one argument.

The initial value is `(_converter_ _init_)` if _converter_is given, otherwise init.

If the parameter object is applied without an argument, then it returns the value associated with the parameter object.

If the parameter object is applied with an argument, then it changes the associated value with the given value which may converted by _converter_if the parameter object is created with converter.

Macro parameterize ((param1 value1) ... ) body ...

[SRFI-39] A `parameterize` expression is used to change the values returned by specified parameter objects during the evaluation of body.

#### Inclusion

Syntax include file files ...
Syntax include-ci file files ...

files must be strings.

Includes files as if it's written there. `include-ci` reads files case insensitively.

#### Multiple-value definition

Macro define-values formals expression

expression is evaluated and the formals are bound to the return values in the same way that the formals in `lambda`expression are matched to the arguments in a procedure call.

#### Numerical operations

Function exact-integer? obj

Returns #t if obj is exact integer. Otherwise #f.

Function floor/ n1 n2
Function floor-quotient n1 n2
Function floor-remainder n1 n2
Function truncate/ n1 n2
Function truncate-quotient n1 n2
Function truncate-remainder n1 n2

These procedures implement number-theoretic (integer) division. It is an error if n2 is zero.

The procedure ending `/` returns two integers; the other procedures return an integer. All the procedures compute a quotient nq and remainder nr such that `_n1_ = _n2_*_nq_ + _nr_`. for each of the division operators, there are three procedures defined as follows;

    (<operator>/ _n1_ _n2_)

nq nr

    (<operator>-quotient _n1_ _n2_)

nq

    (<operator>-remainder _n1_ _n2_)

nr

The remainder nr is determined by the choice of integer `_nq_:_nr_ = _n1_ - _n2_*_nq_`. Each set of operations uses a different choice of nq:

`floor`: `_nq_ = [_n1_/_n2_]``truncate`: `_nq_ = truncate(_n1_/_n2_)`Examples;

    (floor/ 5 2)

2 1

    (floor/ -5 2)

-3 1

    (floor/ 5 -2)

-3 -1

    (floor/ -5 -2)

2 -1

    (truncate/ 5 2)

2 1

    (truncate/ -5 2)

-2 -1

    (truncate/ 5 -2)

-2 1

    (truncate/ -5 -2)

2 -1

    (truncate/ -5.0 -2)

2.0 -1.0
Function square z

Returns the square of z.

#### Error objects

Macro syntax-error msg forms ...

Raises an `&syntax` with `syntax-violation`.

The macro is defined like this;

    (define-syntax syntax-error
      (syntax-rules ()
        ((_ msg args ...)
         (syntax-violation 'syntax-error msg (quote args ...)))))

Function error-object? obj

Returns #t if obj is condition object. This is a renaming exported procedure of `consition?`.

Function error-object-irritants err

Returns irritants if the given err satisfies `irritants-condition?`. Otherwise #f.

Function error-object-message err

Returns error message if the given err satisfies `message-condition?`. Otherwise #f.

#### I/O

Function file-error? obj

Returns #t if obj is a file related condition, otherwise #f.

Function read-error? obj

Renaming export of `i/o-read-error?`.

Function input-port-open? input-port
Function output-port-open? output-port

Return #t if given input-port or output-port is open, respectively. Otherwise #f.

Function u8-ready? input-port
Function char-ready? input-port

Renaming export of `port-ready?`.

Function peek-u8 :optional (input-port (current-input-port))
Function read-u8 :optional (input-port (current-input-port))

input-port must be a binary input port.

Peeks or reads a byte from given input-port.

Function read-bytevector len :optional (input-port (current-input-port))

input-port must be a binary input port.

Reads len from input-port and returns a bytevector.

Function read-bytevector! bv :optional (input-port (current-input-port)) _

_ _ _ (start 0) (end (bytevector-length bv))

input-port must be a binary input port.

Reads end - start size of data from input-port and put it into bv from start index.

Function write-u8 u8 :optional (output-port (current-output-port))

u8 must be a byte. output-port must be a binary output port.

Writes u8 to output-port.

Function write-bytevector bv :optional (output-port (current-output-port)) _

_ _ _ (start 0) (end (bytevector-length bv))

output-port must be a binary output port.

Writes bv from start to end (exclusive) to output-port.

Function read-line :optional (input-port (current-input-port))

input-port must be a textual input port.

Reads line from input-port. For convenience, `\n`, `\r`and `\r\n` are considered end of line.

Function read-string k :optional (input-port (current-input-port))

input-port must be a textual input port.

Reads k length of string from input-port.

Function write-string str :optional (output-port (current-output-port)) _

_ _ _ (start 0) (end (string-length str))

output-port must be a binary output port.

Writes bv from start to end (exclusive) to output-port.

Function open-input-bytevector bv
Function open-input-string string

Returns binary or textual input port whose source is _bv_or string, respectively.

Function open-output-bytevector
Function open-output-string

Returns binary or textual output port. The port is opened on memory.

Function get-output-bytevector output-port
Function get-output-string output-port

Retrieves buffered bytevector or string from given output-ports, respectively.

#### System interface

Function features

Returns a list of the feature identifiers which `cond-expand`treas as true.

#### Differ from R6RS

The following procedures or macros are re-defined to strictly follow either R6RS or R7RS. It is users' responsibility to make sure proper ones are used in their script.

Function equal? a b

Returns #t if a and b are equivalent.

The difference between the one from `(rnrs base)` is that this procedure inspect record fields as well. For example:

    (import (rnrs))
    (define-record-type (<pare> kons pare?)
      (fields (mutable a kar set-kar!)
    	  (mutable d kdr set-kdr!)))

    (let ((a (kons 'a 'b))
          (b (kons 'a 'b)))
      (equal? a b))

    (import (scheme base))
    (define-record-type (<pare> kons pare?)
      (fields (mutable a kar set-kar!)
    	  (mutable d kdr set-kdr!)))

    (let ((a (kons 'a 'b))
          (b (kons 'a 'b)))
      (equal? a b))

#t

Macro let-syntax ((var trans) ... ) expr ...
Macro letrec-syntax ((var trans) ... ) expr ...

Binds macro transformer trans to var.

The difference between the one from `(rnrs base)` and these macros is that these macro create scope. Thus the following is unbound variable error:

    (import (scheme base))
    (let-syntax ()
      (define foo 'foo))
    foo

&undefined

### Case-lambda library

Library (scheme case-lambda)

[R7RS] This library exports the `case-lambda` syntax.

Exported macro is the same as R6RS;

`case-lambda`

### Char library

Library (scheme char)

[R7RS]This library exports procedures for dealing with Unicode character operations.

These procedures are the same as R6RS;

     char-alphabetic? char-ci<=? char-ci<? char-ci=? char-ci>=? char-ci>?
     char-downcase char-foldcase char-lower-case? char-numeric? char-upcase
     char-upper-case? char-whitespace? string-ci<=? string-ci<?
     string-ci=? string-ci>=? string-ci>? string-downcase string-foldcase
     string-upcase

Function digit-value c

[R7RS+] Converts given character to it's numeric value. If the given character does not have numeric value, then it returns #f.

This procedure is extended from R7RS definition.

    (digit-value #\1)

1

    (digit-value #\x0664)

4

    (digit-value #\x0EA6)

#f

    (digit-value #\xbc)

1/4

    (digit-value #\xbf0)

10

### Complex library

Library (scheme complex)

[R7RS]This library exports procedures for complex numbers.

These procedures are the same as R6RS;

`angle imag-part magnitude make-polar make-rectangular real-part`

### CxR library

Library (scheme cxr)

[R7RS]This library exports twenty-four procedures which are the compositions of from three to four car and cdr operations.

These procedures are the same as R6RS;

    caaaar caaadr
    caaar caadar
    caaddr caadr
    cadaar cadadr
    cadar caddar
    cadddr caddr
    cdaaar cdaadr
    cdaar cdadar
    cdaddr cdadr
    cddaar cddadr
    cddar cdddar
    cddddr cdddr

### Eval library

Library (scheme eval)

[R7RS]This library exports exports procedures for evaluating Scheme data as programs.

These procedures are the same as R6RS;

`environment eval`

### File library

Library (scheme file)

[R7RS]This library exports procedures for accessing files.

These procedures are the same as R6RS;

     call-with-input-file call-with-output-file
     delete-file file-exists?
     open-input-file open-output-file
     with-input-from-file with-output-to-file

Function open-binary-input-file file
Function open-binary-output-file file

Returns file binary input or output port associated with given file, respectively.

### Inexact library

Library (scheme inexact)

[R7RS]This library exports procedures for inexact value.

These procedures are the same as R6RS;

`acos asin atan cos exp finite? infinite? log nan? sin sqrt tan`

### Lazy library

Library (scheme lazy)

[R7RS]This library exports procedures and syntax keywords for lazy evaluation.

These procedures/macros are the same as R6RS;

`delay force make-promise promise?`

Macro delay-force expression

The expression `(delay-force _expression_)` is conceptually similar to `(delay (force _expression_))`, with the difference that forcing the result of `delay-force` will in effect result in a tail call to `(force _expression_)`, while forcing the result of `(delay (force _expression_))` might not.

### Load library

Library (scheme load)

[R7RS]This library exports procedures for loading Scheme expressions from files.

Function load file :optional environment

Reads expression in file and evaluates it until it gets to end of file. If environment is passed, then the evaluation is done in that environment. Otherwise it is done in current environment.

### Process-Context library

Library (scheme process-context)

[R7RS] This library exports procedures for accessing with the program's calling context.

These procedures are the same as R6RS; `command-line exit`

Function emergency-exit :optional obj

Exist process without any cleanup. The optional argument _obj_is given then it's translated to proper return value of the process.

Function get-enviromnent-variable name

name must be a string.

Retrieves environment variable associated to name.

Function get-enviromnent-variables

Returns alist of environment variables.

### Read library

Library (scheme read)

[R7RS]This library exports procedures for reading Scheme objects.

Function read :optional port

Renaming export of `read/ss`.

### Repl library

Library (scheme repl)

[R7RS]This library library exports the `interaction-environment` procedure.

Function interaction-environment

Returns interaction environment.

### Time library

Library (scheme time)

[R7RS]This library provides access to time-related values.

Function current-jiffy

Returns the number of jiffies as an exact integer.

Function jiffies-per-second

Returns an exact integer representing the number of jiffies per SI second.

Function current-second

Returns an inexact number representing the current time on International Atomic Time (TAI) scale.

### Write library

Library (scheme write)

[R7RS]This library exports procedures for writing Scheme objects.

This procedures is the same as R6RS `display`

Function write obj :optional (output-port (current-output-port))

Writes a representation of obj to output-port.

If the obj contains cyclic, the procedure writes with datum label.

Function write-shared obj :optional (output-port (current-output-port))
Function write-simple obj :optional (output-port (current-output-port))

Renaming export of `write/ss` and `write`, respectively.

### R5RS library

Library (scheme r5rs)

[R7RS]The (scheme r5rs) library provides the identifiers defined by R5RS, except that `transcript-on` and `transcript-off` are not present. Note that the `exact` and `inexact` procedures appear under their R5RS names `inexact->exact` and `exact->inexact` respectively. However, if an implementation does not provide a particular library such as the complex library, the corresponding identifiers will not appear in this library either. This library exports procedures for writing Scheme objects.

## R7RS-large

R7RS-large makes Scheme specification more practical. It contains lots of useful libraries as well. This section lists supporting R7RS-large libraries.

### List library

Library (scheme list)

This library exports the procedures and macros defined in SRFI-1 `(srfi :1)`.

### Vector library

Library (scheme vector)

This library exports the procedures and macros defined in SRFI-133 `(srfi :133)`.

### Sorting library

Library (scheme sort)

This library exports the procedures and macros defined in SRFI-132 `(srfi :132)`.

### Set library

Library (scheme set)

This library exports the procedures and macros defined in SRFI-113 `(srfi :113)`.

### Character set library

Library (scheme charset)

This library exports the procedures and macros defined in SRFI-14 `(srfi :14)`.

### Hashtable library

Library (scheme hash-table)

This library exports the procedures and macros defined in SRFI-125 `(srfi :125)`.

### Immutable list library

Library (scheme ilist)

This library exports the procedures and macros defined in SRFI-116 `(srfi :116)`.

### Random access list library

Library (scheme rlist)

This library exports the procedures and macros defined in SRFI-101 `(srfi :101)` with the following exceptions:

`make-list` is renamed to `make-rlist`.

`random-access-list->linear-access-list` is renamed to `rlist->list`.

`linear-access-list->random-access-list` is renamed to `list->rlist`.

All other procedures are prefixed with `r`. For example, `pair?`exported from `(srfi :101)` is `rpair?`.

### Immutable deque library

Library (scheme ideque)

This library exports the procedures and macros defined in SRFI-134 `(srfi :134)`.

### Immutable text library

Library (scheme text)

This library exports the procedures and macros defined in SRFI-135 `(srfi :135)`.

### Generator library

Library (scheme generator)

This library exports the procedures and macros defined in SRFI-158 `(srfi :158)`.

### Lazy sequence library

Library (scheme lazy-seq)

This library exports the procedures and macros defined in SRFI-127 `(srfi :127)`.

### Stream library

Library (scheme stream)

This library exports the procedures and macros defined in SRFI-41 `(srfi :41)`.

### Box library

Library (scheme box)

This library exports the procedures and macros defined in SRFI-111 `(srfi :111)`.

### List queue library

Library (scheme list queue)

This library exports the procedures and macros defined in SRFI-117 `(srfi :117)`.

### Ephemeron library

Library (scheme ephemeron)

This library exports the procedures and macros defined in SRFI-124 `(srfi :124)`.

### Comparator library

Library (scheme comparator)

This library exports the procedures and macros defined in SRFI-128 `(srfi :128)`.

### Division library

Library (scheme division)

This library exports the procedures and macros defined in SRFI-141 `(srfi :141)`.

### Fixnum library

Library (scheme fixnum)

This library exports the procedures and macros defined in SRFI-143 `(srfi :143)`.

### Flonum library

Library (scheme flonum)

This library exports the procedures and macros defined in SRFI-144 `(srfi :144)`.

### Mapping library

Library (scheme mapping)

This library exports the procedures and macros defined in SRFI-146 `(srfi :146)`.

### Hash mapping library

Library (scheme mapping hash)

This library exports the procedures and macros defined in SRFI-146 `(srfi :146 hash)`.

### Bitwise library

Library (scheme bitwise)

This library exports the procedures and macros defined in SRFI-151 `(srfi :151)`.

### Format library

Library (scheme format)

This library exports the procedures and macros defined in SRFI-159 `(srfi :159)`.

### Homogeneous vector library base

Library (scheme vector base)

This library exports the procedures and macros defined in SRFI-160 `(srfi :160 base)`.

### Homogeneous vector library per types

Library (scheme vector @ )

This library exports the procedures and macros defined in SRFI-160 `(srfi :160 @)`. Where `@` is one of `u8 s8 u16 s16 u32 s32 u64 s64 f32 f64 c64 c128`

### Bytevector library

Library (scheme bytevector)

This library exports the procedures and macros defined in R6RS bytevectors library `(rnrs bytevectors)`.

NOTE: The exporting names may conflicts with the ones exported from R7RS libraries (e.g. `bytevector-copy!` from `(scheme base)`).

# CLOS

Since Sagittarius version 0.3.0, we supports CLOS so that all Scheme objects have its class. For example `1` is instance of `<integer>` class.

However CLOS has huge features and I don't have intension to implement all of it.

This section does not describe CLOS itself.

## (clos user) -CLOS user APIs

Library (clos user)

User level CLOS API collection library.

Macro define-class name supers slots . options

Name must be symbol or identifier.

Supers must be list of class.

Slots must be following structure:

    _slots_ ::= (_slot_ ...)
    _slot_  ::= (_slot-name_ _specifiers_*)
    _specifiers_ ::= `:init-keyword` _keyword_
                  | `:init-value` _value_
                  | `:init-form` _form_
                  | `:reader` _reader-function_
                  | `:writer` _writer-function_

Defines a new class.

Slot specifiers:

`:init-keyword`

  This keyword specifies initialisation keyword argument used by the `make` procedure. Following code describes how to use:

      (make <a-class> :slot-a 'slot-a-value)

  `<a-class>` has a slot which slot definition contains the keyword `:init-keyword` with the keyword :slot-a. The code initialises an instance of the slot with given value slot-a-value.
`:init-value`

  This keyword specifies an initial value of target slot.

`:init-form`

  Similar with `:init-keyword` but this keyword takes expression which will be evaluated at initialiation time.

`:reader`

  This keyword creates a procedure takes 1 argument an instance of the class to access the slot, so users can read the slot without using `slot-ref` procedure.

`:writer`

  This keyword creates a procedure takes 2 argument an instance of the class and object to set the slot value with given object, so users can set the slot without using `slot-set!` procedure.

opttions can specify the metaclass of this class with keyword `:metaclass`.

NOTE: Current implementation does not support `:allocation` keyword by default. If you need it, see (sagittarius mop allocation).

Macro define-generic name :key class

Name must be symbol.

Creates a new generic function.

By specifying class keyword argument, users can customize the behaviour of the method specialization.

We provide `<predicate-specializable-generic>` for `memq`, `memv`, `member` and `predicate` specializer.

Macro define-method name specifiers body ...

Name must be symbol.

Specifiers must be following structure:

    _specifiers_ ::= (_spec_ ... _rest_)
    _spec_ ::= (_argument-name_ _class_)
           | (_argument-name_)
           | (_argument-name_ (_specializer_ value))
    _rest_ ::= '() | symbol
    _specializer_ ::= `eq` | `eql` | `equal` | `eq?` | `eqv?` | `equal?`

Adds defined method to name generic. If the generic does not exist, this will create a new generic function implicitly.

Function slot-ref obj slot-name

Returns the slot value specified slot-name.

Function slot-set! obj slot-name value

Sets the slot value value with specified slot-name.

Function slot-bound? obj slot-name

Returns #t if the slot value specified slot-name is bounded, otherwise #f.

Generic make class args ...

Creates a new instance of class

Function is-a? object class

Returns #t if object is an instance of class, otherwise #f.

Function subtype? class1 class2

Returns #t if class1 is a subclass of class2, otherwise #f.

Function slot-ref-using-accessor object accessor

This procedure is for MOP.

Returns the slot value got by accessor.

Function slot-set-using-accessor! object accessor value

This procedure is for MOP.

Sets the slot value value to object using accessor.

Function slot-ref-using-class class object slot-name

This procedure is for MOP.

Returns the slot value according to the given class.

It is an error if the given slot-name doesn't exist in the class.

Function slot-set-using-accessor! class object slot-name value

This procedure is for MOP.

Sets the slot value value to object accoring to the given class.

It is an error if the given slot-name doesn't exist in the class.

Function slot-bound-using-class? class object slot-name

This procedure is for MOP.

Returns #t if the slot is bounded according to the given class, otherwise #f.

It is an error if the given slot-name doesn't exist in the class.

Generic write-object object (out )

This method will be called when writing the given object.

Defines how user defined class should be written.

Generic object-equal? object1 object2

This method will be called when `equal?` is called.

Defines how user defined class should be compared.

## (clos core) - CLOS core library

Library (clos core)

Low level CLOS API collection library.

Generic add-method generic method

Generic must be generic function. method must be method object.

Adds method to generic.

Generic compute-getter-and-setter class slot

Returns a list of getter, setter and bound check for the given class's slot slot.

The returning list must have 3 elements, getter, setter and bound? respectively. Each element must be either #f or procedure. If #f is used then the default procedure will be used.

For the example code, see Sagittarius MOP.

Generic compute-getters-and-setters class slots

Returns all getters and setters for the given class's slots.

The upper layer of `compute-getter-and-setter`. This method should only be used if users absolutely need to use accessor to access the target slots.

Function slot-definition-name slot

Returns slot name of given slot.

Function slot-definition-options slot

Returns slot options of given slot.

Function slot-definition-option slot keyword . default

Returns slot option's value of given slot if it has the keyword.

If default is given, then it will be the fallback value when _keyword_is not found. Otherwise this procedure raises an error.

# Sagittarius extensions

Sagittarius has its own extension libraries because even R6RS is huge however I know it is not sufficient to write practical program. To support to write it, Sagittarius provides some useful libraries.

## (sagittarius) - builtin library

Library (sagittarius)

This library has Sagittarius specific functionalities such as extra file system functions and so.

### Builtin Syntax

Syntax define-constant variable expression

Similar to the `define` however the `define-constant` binds variable as a constant value and the compiler try to fold it if it is constant value i.e. literal string, literal vector, literal number and so.

If the defined variable is being overwritten, the VM shows a warning message on the standard error. If overwriten is forbidden by `#!no-overwite` or other directives, then compiler raises an error.

Syntax receive formals expression body

[SRFI-8] formals and body are the same as `lambda`. Expression must be an expression.

`receive` binds values which are generated by expressions to formals.

The expressions in body are evaluated sequentially in the extended environment. The results of the last expression in the body are the values of the `receive`-expression.

Syntax cond-expand clauses ...

[R7RS][SRFI-0] Compile time condition. The `cond-expand` resolves platform dependencies such as C's `#ifdef` preprocessor.

clauses must be one of these forms:

- (feature-identifier body ...)

- ((`version` (compare _version)) body ...) 0.9.12

- ((`library` library-name) body ...)

- ((`and` feature-identifier ...) body ...)

- ((`or` feature-identifier ...) body ...)

- (`not` feature-identifier)

`version` clause checks the Sagittarius version. The compare must be one of `>`, `>=`, `=`, `<=` or `<`. And version must be a string which represents the target version.
This feature is since `0.9.12` and provides `cond-expand.version` feature identifier.
This is Sagittarius' extension. See the below example how to use it.

`library` clause searches the given library-name and if it is found, then compiles body.

`and`, `or` and `not` are the same as usual syntax.

Users can check possible _feature-identifier_s via `cond-features`procedure.

    ;; version clause example
    (cond-expand
     ;; For backward compatible way among other Sagittarius versions
     ((and cond-expand.version (version (>= "0.9.12")))
      ;; Code for higher than or equal to the version 0.9.12
      )
     ;; In case other Scheme implementations support the same thing
     ((and sagittarius cond-expand.version (version (>= "0.9.12")))
      ;; Sagittarius 0.9.12 or higher specific code
      )
     (else
      ;; Version lower than 0.9.12 code
      ))

### Macro transformer

Function er-macro-transformer proc

Proc must be a procedure which accepts 3 arguments, form, rename and compare.

form

  The input form of this macro. It is mere s-expression.

rename

  A procedure. It takes an object as its argument and convert it to a syntax object. The procedure is similar with `datum->syntax`, it doesn't require template identifier.

compare

  A procedure. It takes 2 arguments and compares if they are the same object in sense of `free-identifier=?`. If the given arguments are list or vector, then the procedure checks its elements.

The `er-macro-transformer` returns explicit renaming macro transformer, so you can write both hygine and non-hygine macro with it. For example:

    (define-syntax loop
      (er-macro-transformer
       (lambda (form rename compare)
         (let ((body (cdr form)))
           `(,(rename 'call/cc)
    	 (,(rename 'lambda) (break)
    	  (,(rename 'let) ,(rename 'f) () ,@body (,(rename 'f)))))))))

    (let ((n 3) (ls '()))
      (loop
        (if (= n 0) (break ls))
        (set! ls (cons 'a ls))
        (set! n (- n 1))))

(a a a)

This example has the same functionality as the example written in `datum->syntax` description. The basic of `er-macro-transformer` is the opposite way of the `syntax-case`. The `syntax-case` always makes macro hygine, however the `er-macro-transformer` can make macro hygine. Moreover, if you do not use rename, it always makes it non-hygine.

### Arithmetic operations

Function +. z ...
Function *. z ...
Function -. z ...
Function -. z1 z2 ...
Function /. z ...
Function /. z1 z2 ...

The same as `+`, `*`, `-` and `/`. The difference is these procedures converts given arguments inexact number.

Function mod-inverse x m

x and m must be exact integer.

Returns `_x_ ^ -1 mod _m_`

Function mod-expt x e m

x, e and m must be exact integer.

Returns `_x_ ^ _e_ mod _m_`

### File system operations

Function file-size-in-bytes filename

Returns file size of filename in bytes. If filename does not exist, it raises `&i/o` condition.

Function file-regular? filename
Function file-directory? filename
Function file-symbolic-link? filename
Function file-readable? filename
Function file-writable? filename
Function file-executable? filename

Returns file type or permission of given filename.

Function file-stat-ctime filename
Function file-stat-mtime filename
Function file-stat-atime filename

Returns file statistics time in nano sec.

The `file-stat-ctime` procedure returns last change time of filename.

The `file-stat-mtime` returns last modified time of filename.

The `file-stat-atime` returns last accesse time of filename.

Function change-file-timestamp! filename atime mtime

Changes given filename's access time and modify time.

atime specifies the access time of the filename.

mtime specifies the modify time of the filename.

If atime and/or mtime are time object, then the setting timestamp is the absolute time represented by the arguments.

If atime and/or mtime are real number, then the setting timestamp is the difference of the arguments from current time.

If atime and/or mtime are #f, then the timestamp is intact.

If atime and/or mtime are true value other then time or real number, then the timestamp is set to current time.

Function change-file-mode filename mode

Changes given filename's file mode.

mode must be a fixnum encoded with POSIX file permission.

NOTE: On Windows, only the owner permission is considered.

Function create-symbolic-link old-filename new-filename

Creates symbolic link of old-filename as new-filename.

Function rename-file old-filename new-filename

Renames given old-filename to new-filename.

If old-filename does not exist, it raises `&i/o`.

If new-filename exists, it overwrite the existing file.

Function create-directory path
Function delete-directory path

Creates/deletes given directory. If it fails, it raises condition `&i/o`.

Function read-directory path

Reads directory and returns contents as a string list. If path does not exist, it returns #f.

Function copy-file src dst :optional overwrite

src and dst must be string and src must indicate existing file path.

Copies given src file to dst and returns #t if it's copied otherwise #f.

If optional argument overwrite is #t then it will over write the file even if it exists.

Function current-directory :optional path

Returns current working directory.

If optional argument path is given, the `current-directory` sets current working directory to path and returns unspecified value.

Function set-current-directory path

Sets current working directory to path.

Function build-path path1 path2

path1 and path2 must be string.

Concatenate given parameter with platform dependent path separator.

### Hashtables

Function make-equal-hashtable :optional k weakness
Function make-string-hashtable :optional k weakness

Creates a hashtable.

The same as `make-eq-hashtable` and `make-eqv-hashtable`. It uses `equal?` or `string=?` as comparing procedure, respectively.

Function hashtable-values hashtable

Returns all hashtable's values. This procedure is for consistancy of `hashtable-keys`.

Function hashtable-keys-list hashtable
Function hashtable-values-list hashtable

Returns given hashtable's keys or values, respectively.

The R6RS required procedure `hashtable-keys` and `hashtable-values`are implemented with these procedures.

Function hashtable-type hashtable

Returns hashtable's hash type as a symbol. The possible return values are `eq`, `eqv`, `equal`, `string` and `general`.

Function hashtable-weakness hashtable

Returns hashtable's hash weakness as a symbol if the given hashtable is weak hashtable, otherwise #f. The possible return values are `key`, `value` and `both`.

### I/O

Function port-closed? port

Returns #t if given port is closed, otherwise #f.

Function put-u16 out v endian
Function put-s16 out v endian
Function put-u32 out v endian
Function put-s32 out v endian

out must be binary output port. endian must be a value returned from `endianness` macro.

Write v to out as unsigned/signed 16/32 bit integer.

Function get-u16 in endian
Function get-s16 in endian
Function get-u32 in endian
Function get-s32 in endian

in must be binary input port. endian must be a value returned from `endianness` macro.

Read a number from in as unsigned/signed 16/32.

NOTE: above `put-*` and `get-*` have only 16 and 32 bit integers. This is because benchmark told us there's not much difference between C and Scheme implementation. We may add 64 bit integers and floting number versions in future if there's enough demand.

Function read/ss :optional (port `(current-input-port)` )
Function write/ss obj :optional (port `(current-output-port)` )

[SRFI-38] The `read/ss` reads a datum from given port.

The `write/ss` writes obj to given port.

These are the same as `read` and `write` procedure, but it can handle circular list.

Function format port string arg ...
Function format string arg ...

[SRFI-28+] Formats arg accoding to string. _Port_specifies the destination; if it is an output port, the formatted result is written to it; if it is #t, the result is written to current output port; if it is #f, the formatted result is returned as a string. Port can be omitted and the result is the same as when #f is given.

String is a string that contains format directives. A format directive is a character sequence begins with tilda `'~'`, and ends with some specific characters. A format directive takes the corresponding arg and formats it. The rest of string is copied to the output as is.

    (format #f "the answer is ~a" 48)

the anser is 48

The format directive can take one or more parameters, separated by comma characters. A parameter may be an integer or a character; if it is a character, it should be preceded by a quote character. Parameter can be omitted, in such case the system default value is used. The interpretation of the parameters depends on the format directive.

Furthermore, a format directive can take two additional flags: atmark `'@'` and colon `':'`. One or both of them may modify the behaviour of the format directive. Those flags must be placed immediately before the directive character.

The following complete list of the supported directives. Either upper case or lower case character can be used for the format directive; usually they have no distinction, except noted.

~mincol,colinc,minpad,padchar,maxcol A

  Ascii output. The corresponding argument is printed by `display`. If an integer mincol is given, it specifies the minimum number of characters to be output; if the formatted result is shorter than mincol, a whitespace is padded to the right (i.e. the result is left justified). The colinc, minpad and padchar parameters control, if given, further padding. A character padchar replaces the padding character for the whitespace. If an integer minpad is given and greater than 0, at least minpad padding character is used, regardless of the resulting width. If an integer colinc is given, the padding character is added (after minpad) in chunk of colinc characters, until the entire width exceeds mincol. If atmark-flag `'@'` is given, the format result is right justified, i.e. padding is added to the left. The maxcol parameter, if given, limits the maximum number of characters to be written. If the length of formatted string exceeds maxcol, only maxcol characters are written. If colon-flag is given as well and the length of formatted string exceeds maxcol, maxcol - 4 characters are written and a string `" ..."` is attached after it.

      (format #f "|~a|" "oops")

  |oops|

      (format #f "|~10a|" "oops")

  |oops |

      (format #f "|~10@a|" "oops")

  | oops|

      (format #f "|~10,,,'*@a|" "oops")

  |\*\*\*\*\*\*oops|

      (format #f "|~,,,,10a|" '(abc def ghi jkl))

  |abc def gh|

      (format #f "|~,,,,10:a|" '(abc def ghi jkl))

  |abc de ...|
~mincol,colinc,minpad,padchar,maxcol S

  S-expression output. The corresponding argument is printed by `write`. The semantics of parameters and flags are the same as ~A directive.

      (format #f "|~s|" "oops")

  |"oops"|

      (format #f "|~10s|" "oops")

  |"oops" |

      (format #f "|~10@s|" "oops")

  | "oops"|

      (format #f "|~10,,,'*@s|" "oops")

  |\*\*\*\*"oops"|
~mincol,padchar,commachar,interval D

  Decimal output. The argument is formatted as an decimal integer. If the argument is not an integer, all parameters are ignored and it is formatted by ~Adirective. If an integer parameter mincol is given, it specifies minimum width of the formatted result; if the result is shorter than it, padchar is padded on the left (i.e. the result is right justified). The default of padchar is a whitespace.

      (format #f "|~d|" 12345)

  |12345|

      (format #f "|~10d|" 12345)

  | 12345|

      (format #f "|~10,'0d|" 12345)

  |0000012345|
  If atmark-flag is given, the sign `'+'` is printed for the positive argument. If colon-flag is given, every _interval_th digit of the result is grouped and commachar is inserted between them. The default of commachar is `','`, and the default of interval is 3.

      (format #f "|~:d|" 12345)

  |12,345|

      (format #f "|~,,'_,4:d|" -12345678)

  |-1234_5678|
~mincol,padchar,commachar,interval B

  Binary output. The argument is formatted as a binary integer. The semantics of parameters and flags are the same as the ~D directive.

~mincol,padchar,commachar,interval O

  Octet output. The argument is formatted as a octal integer. The semantics of parameters and flags are the same as the ~D directive.

~mincol,padchar,commachar,interval X
~mincol,padchar,commachar,interval x

  Hexadecimal output. The argument is formatted as a hexadecimal integer. If `'X'` is used, upper case alphabets are used for the digits larger than 10. If `'x'` is used, lower case alphabets are used. The semantics of parameters and flags are the same as the ~D directive.

      (format #f "~8,'0x" 259847592)

  0f7cf5a8

      (format #f "~8,'0X" 259847592)

  0F7CF5A8

Note: The format procedure's implementation and most of documentation is quoted from Gauche.

Function port-ready? :optional (port (current-input-port))

Returns #t when port data are ready, otherwise #f.

If the given port implementation does not support this functionality, the return value will be always #t. Following example describes when this always returns #t;

    ;; Assume read! is provided.
    (define user-port (make-custom-binary-input-port "my-port" read! #f #f))
    (port-ready user-port)

#t

Function buffered-port port buffer-mode :key buffer

port must be binary port.

Converts given port to buffered port if the port is not buffered port.

Buffered port is a type of port which does not read or write immediately but uses internal buffer. For example, file port with `(buffer-mode block)` or `(buffer-mode line)` uses the buffered port. This is useful when actual I/O is more expensive than memory access.

The buffer-mode must be a symbol the macro `buffer-mode` can return. If the `buffer-mode` is `none`, then the procedure does not convert the given port.

If the keyword argument buffer is specified, it must be a bytevector, then the converted buffered port uses specified bytevector as its internal buffer. If the bytevector size is zero or literal bytevector then `&assertion` is raised.

Function make-codec symbol getc putc data

Creates a custom codec. Symbol is the name of the codec. _Getc_and putc must be procedures. Data is an user data used in _getc_and putc.

Getc must take 4 arguments, input-port, error-handling-mode, check-bom? and userdata. Input-port is binary input port. Error-handling-mode is symbol can be `ignore`, `raise` or `replace` depending on a transcoder which uses this custom codec. Check-bom? is boolean, if getc is being called first time, it is #t, otherwise #f. Userdata is user defined data which is given when the codec is created.

The basic process of getc is reading binary data from input-port and converting the data to UCS4. Returning UCS4 must be integer and does not have to be 4 byte.

Putc must take 4 arguments, output-port, char, error-handling-mode and userdata. Output-port is binary output port. Char is character object which needs to be converted from UCS4. Error-handling-mode is symbol can be `ignore`, `raise` or `replace` depending on a transcoder which uses this custom codec. Userdata is user defined data which is given when the codec is created.

The basic process of putc is converting given UCS4 charactner to target encoding data and putting it to output-port as binary data.

For sample implementation, see sitelib/encoding directory. You can find some custom codecs.

### Symbols

Function symbol<? symbol1 symbol2 symbols ...
Function symbol<=? symbol1 symbol2 symbols ...
Function symbol>? symbol1 symbol2 symbols ...
Function symbol>=? symbol1 symbol2 symbols ...

Return #t if given symbol1 is less than, less than or equal to, greater than or greater than or equal to symbol2. If symbols are not null, then the procedures continue to compare until the given arguments are exhausted.

These procedures are analogy of `string<?`, `string<=?`, `string>?` and `string>=?`.

These can also be implemented as follows:

    (define (symbol<? . syms) (apply string<? (map symbol->string syms)))

However, this build-in version won't converts given symbols to strings.

### Keywords

Sagittarius has keyword objects which starts with `':'`. It has almost the same feature as symbol, however it can not be bounded with any values. The keyword objects are self quoting so users don't have to put `'` explicitly.

The keyword notation is *NOT* available on R6RS or R7RS reader mode. Thus `#!r6rs` or `#!r7rs` directive and `-r6` or `-r7`command line option disable it.

Function make-keyword symbol
Function symbol->keyword symbol

Creates a new keyword from symbol.

Function string->keyword string

Creates a new keyword from string.

Function keyword? obj

Returns #t if obj is keyword, otherwise #f.

Function keyword->symbol keyword

Returns a symbol representation of given keyword keyword.

Function keyword->string keyword

Returns a string representation of given keyword keyword.

Function get-keyword keyword list :optional fallback

Returns the element after given keyword from given list.

The elements count of the list should be even number, otherwise the procedure might raise `&error` when keyword is not found in list.

If fallback is given and the procedure could not find the _keyword_from the list, the fallback will be return. Otherwise it raises `&error`.

    (get-keyword :key '(a b c :key d))

d

    (get-keyword :key '(a b c d e))

&error

    (get-keyword :key '(a b c d e) 'fallback)

&error

    (get-keyword :key '(a b c d e f) 'fallback)

fallback

### Weak box

A weak box is a reference to an object that doesn’t prevent the object from being garbage-collected.

Function weak-box? obj

Returns #t if obj is weak box otherwise #f.

Function make-weak-box obj

Returns a weak box whose value is obj.

Function weak-box-empty? wb

Returns #t if the value of given weak box wb is garbage collocted. Otherwise #f.

Function weak-box-ref wb :optional (fallback #f)

Returns the value of given weak box wb if it's not garbage collocted. Otherwise returns fallback.

Function weak-box-set! wb obj

Replace the value of given wb with obj.

### Weak vector

A weak vector is like a vector of objects, except each object can be garbage collected if it is not referenced from objects other than weak vectors. If the object is collected, the entry of the weak vector is replaced to #f.

Function weak-vector? obj

Returns #t if obj is weak vector otherwise #f.

Function make-weak-vector size

Creates and returns a weak vector of size size.

Function weak-vector-length wvec

Returns the length of given weak vector wvec

Function weak-vector-ref wvec k :optional fallback

Returns k-th element of a weak vector wvec.

By default, `weak-vector-ref` raise an `&assertion` if k is negative, or greater than or equal to the size of wvec. However, if an optional argument fallback is given, it is returned for such case.

If the element has been garbage collected, this procedure returns _fallback_if it is given, #f otherwise.

Function weak-vector-set! wvec k value

Sets k-th element of the weak vector wvec to value. It raises an `&assertion` if k is negative or greater than or equal to the size of wvec.

### Weak hashtable

A weak hashtable contains references to an object that doesn't prevent the object from being garbage-collected the same as weak vector. A weak hashtable is like a hashtable, except each entry can be garbage collected if it is not referenced from objects other than weak hashtable according to the constructed condition.

Function weak-hashtable? obj

Returns #t if obj is weak hashtable otherwise #f.

Function make-weak-eq-hashtable :key (init-size 200) (weakness 'both) default
Function make-weak-eqv-hashtable :key (init-size 200) (weakness 'both) default

Make a weak hashtable with the hash procedure `eq?` and `eqv?`, respectively.

The keyword argument init-size specifies the initial size of the weak hashtable.

The kwyword argument weakness specifies the place where the weak pointer is. This must be one of the `key`, `value` and `both`. If the `key` is specified, then weak hashtable's weak pointer will be the key so is `value`. If the `both` is specified, then it will be both.

The keyword argument default specifies the default value when the entry is garbage collected. If this is not spceified, then undefined value will be used.

Function weak-hashtable-ref weak-hashtable key :optional (default #f)

Returns the value in weak-hashtable associated with key. If weak-hashtable does not contain an association for key, default is returned.

Function weak-hashtable-set! weak-hashtable key obj

Changes weak-hashtable to associate key with obj, adding a new association or replacing any existing association for key, and returns unspecified values.

Function weak-hashtable-delete! weak-hashtable key

Removes any association for key within weak-hashtable and returns unspecified values.

Function weak-hashtable-keys-list weak-hashtable
Function weak-hashtable-values-list weak-hashtable

Returns a list of keys and values in the given weak-hashtable, respectively.

Function weak-hashtable-copy weak-hashtable

Returns a copy of weak-hashtable.

Function weak-hashtable-shrink weak-hashtable

Shrink the given weak-hashtable and returns the number of removed entry. This is only for GC friendliness.

### Bytevector operations

Function bytevector->sinteger bytevector :optional start end
Function bytevector->uinteger bytevector :optional start end
Function bytevector->integer bytevector :optional start end

Converts given bytevector bytevector to exact integer. If optional argument start is given, conversion starts with index start. If optional argument end is given, convertion ends by index end. The conversion only happens in big endian.

The first form converts to signed integer and the rest convert to unsigned integer.

Function sinteger->bytevector ei :optional size
Function uinteger->bytevector ei :optional size
Function integer->bytevector ei :optional size

Ei must be exact integer. Converts exact integer ei to a bytevector.

The first form can accept signed integer and converts with two's complement form. The rest forms only accept unsigned integer and simply convert to bytes.

If optional argument size is given, then the procedure returns _size_size bytevector.

NOTE: The conversion is processed from right most byte so if the size is smaller than given ei bytes, then the rest of left bytes will be dropped.

NOTE: the endianness is always big endianness.

    (integer->bytevector #x12345678 5)

#vu8(#x00 #x12 #x34 #x56 #x78)

    (integer->bytevector #x12345678 3)

#vu8(#x34 #x56 #x78)
Function bytevector-append bvs ...

Returns a newly allocated bytevector that contains all elements in order from the subsequent locations in bvs ....

Function bytevector-concatenate list-of-bytevectors

Appends each bytevectors in list-of-bytevectors. This is equivalent to:

    (apply bytevector-append _list-of-bytevectors_)

### List operations

Function circular-list? list
Function dotted-list? list

[SRFI-1] Returns #t if list is circular or dotted list, respectively. Otherwise #f.

Function acons obj1 obj2 obj3

Returns `(cons (cons _obj1_ _obj2_) _obj3_)`. Useful to put an entry at the head of an associative list.

Function append! list ...

[SRFI-1] Returns a list consisting of the elements of the first _list_followed by the elements of the other lists. The cells in the lists except the last one may be reused to construct the result. The last argument may be any object.

Function reverse! list ...

[SRFI-1] Returns a list consisting of the elements of list in reverse order. The cells of list may be reused to construct the returned list.

### Vector operations

Function vector-copy vector :optional start end fill

[SRFI-43] Copies a vector vector. Optional start and _end_arguments can be used to limit the range of vector to be copied. If the range specified by start and end falls outside of the original vector, the fill value is used to fill the result vector.

    (vector-copy '#(0 1 2 3 4) 1 4)

#(1 2 3)

    (vector-copy '#(0 1 2 3 4) 4 6 #f)

#(4 #f)

    (vector-copy '#() 0 2 #t)

#(#t #t)
Function vector-append vector ...

[SRFI-43] Returns a newly allocated vector that contains all elements in order from the subsequent locations in vector ....

    (vector-append '#(1 2) '#(a b) '#(5))

#(1 2 a b 5)
Function vector-concatenate list-of-vectors

[SRFI-43] Appends each vectors in list-of-vectors. This is equivalent to:

    (apply vector-append _list-of-vectors_)

Function vector-reverse vector :optional start end
Function vector-reverse! vector :optional start end

[SRFI-43] Reverse the given vector's elements.

The second form reverses the given vector destructively.

Optional arguments start and end must be non negative integer if it's given. And it restricts the range of the target elements.

### String operations

Function string-scan string item :optional return

Scan item (either a string or a character) in string.

The return argument specified what value should be returned when item is found in string. It must be one of the following symbols;

`index`

  Returns the index in string if item is found, or `#f`. This is the default behaviour.

`before`

  Returns a substring of string before item, or `#f` if item is not found.

`after`

  Returns a substring of string after item, or `#f` if item is not found.

`before*`

  Returns a substring of string before item, and the substring after it. If item is not found then return `(values #f #f)`.

`after*`

  Returns a substring of string up to the end of item, and the rest. after it. If item is not found then return `(values #f #f)`.

`both`

  Returns a substring of string before item and after item. If item is not found, return `(values #f #f)`.

Function string-concatenate list-of-strings

[SRFI-13] Appends each strings in list-of-strings. This is equivalent to:

    (apply string-append _list-of-strings_)

Function istring? obj

Returns #t if the given obj is an immutable string, otherwise #f.

Immutable strings are one of the followings:

- String literals. (i.e. `"abc"`)

- Strings converted to immutable string by `string->istring`

Function string->istring string :optional start end

Returns copy of the given string. The returning string is converted to immutable string.

The optional argument start and end are given, then the returing string is contains only the range of given string.

### Load path

Function add-load-path path :key (append #f)

Add given path to current loading path list.

If keyword argument append is `#t`, then given path is appended to the current loading path list, otherwise prepend to the list.

Function add-load-suffix suffix :key (append #f)

Add given suffix to current suffix list.

If keyword argument append is `#t`, then given suffix is appended to the current suffix list, otherwise prepend to the list.

The suffix should contain `.` as well.

Function load-path
Function load-path paths

Retrives/sets current loading path.

If the latter form is used, then the given path list paths is set to current loading path list. Otherwise retrieves the list.

The returning value is not copied, thus modifying the list may cause unexpected results.

### System and platform

Function uname

Return a vector which contains the following information.

System name

  Operating system name. E.g. "Linux"

Node name

  The name of the computer.

Release

  Release number of the system if availabel.

Version

  Version number of the system if availabel.

Machine

  Machine architecture of the system.

On POSIX environment, this is the result of `uname(2)`.

On Windows environment, this is the result of couple of Win32 API calls and formatted to look like the result of `uname(2)`.

Function get-mac-address :optional (position 0)

Retrieves MAC address. The returning value is a bytevector which contains 6 elements.

If optional argument specifies which NIC's MAC address should be returned.

Function get-process-times
Function get-thread-times :optional thread

Returns a vector having 3 elements; user time, _system time_and tick.

The first procedure returns process CPU time, the second procedure returns thread CPU time. If the optional argument thread is given, then the procedure retrieves CPU time of given thread. Otherwise current thread.

tick is a clock tick. Users can compute CPU second Dividing user time or system time by this value.

NOTE: tick may not be the same even on the same platform. For example, `get-process-times` returns value of `_SC_CLK_TCK`, and `get-thread-times` returns 1000000 (on OSX), 1000000000 (on other POSIX environments which have `pthread_getcpuclockid`), or `_SC_CLK_TCK`(on other POSIX environments which don't have `pthread_getcpuclockid`). So users must not assume the value is one of them and calculate CPU second with assumed value.

Function gc

Invokes garbage collection manually.

Function cpu-count

Returns number of CPUs. The result contains hyperthreading, for example, if the CPU is Core i5 which have 2 cores and hyperthreading is enabled, then the returning value is 4.

On Linux environment, the procedure also considers `taskset(1)`.

This procedure returns static value initialised during initialisation of Sagittarius process. Thus, if the process is restricted after its initialisation by `taskset(1)`, for example the environment has 4 CPUs but restricted to 1, then this process, however, returns 4.

### Debugging aid

Function disasm closure

Disassembles the compiled body of closure and print it.

Function arity procedure

Returns arity of given procedure.

It returns a pair whose car part is required arguments count and cdr part is boolean which indicates if the procedure accepts optional arguments or not.

Library (time)

Exports `time` macro

Macro time expr

Evaluate expr and shows time usage.

The macro return the result of expr.

## (sagittarius control) - control library

Library (sagittarius control)

This library provides some useful macros using Sagittarius specific functions.

Macro define-macro name procedure
Macro define-macro (name . formals) body ...

Defines name to be a macro whose transformer is procedure. The second form is a shorthand notation of the following form:

    (define-macro _name_ (lambda _formals_ _body_ ...))

Macro let-optionals* restargs (var-spec ... ) body ...
Macro let-optionals* restargs (var-spec ... . restvar) body ...

Given a list of values restargs, binds variables according to var-spec, then evaluates body.

Var-spec can be either a symbol, or a list of two elements and its car is a symbol. The symbol is the bound variable name. The values in _restargs_are bound to the symbol in order. If there are not as many values in restargs as var-spec, the rest of symbols are bound to the default values, determined as follows:

If var-spec is just a symbol, the default value is undefined.

If var-spec is a list, the default value is the result of evaluation of the second element of the list.

In the latter case the second element is only evaluated when there are not enough arguments. The binding proceeds in the order of var-spec, so the second element may refer to the bindings of previous var-spec.

In the second form, restvar must be a symbol and bound to the list of values whatever left from restargs after binding to var-spec.

It is not an error if restarg has more values than var-specs. The extra values are simply ignored in the first form.

Macro get-optionals restargs default
Macro get-optionals restargs default test

This is a short version of `let-optionals*` where you have only one optional argument. Given the optional argument list restargs, this macro returns the value of optional argument if one is given, or the result of default otherwise.

If latter form is used, test must be procedure which takes one argument and it will be called to test the given argument. If the test failed, it raises `&error` condition.

Default is not evaluated unless restargs is an empty list.

Macro let-keywords restargs (var-spec ... ) body ...
Macro let-keywords restargs (var-spec ... . restvar) body ...

This macro is for keyword arguments. Var-spec can be one of the following forms:

    (_symbol_ _expr_)

If the restrag contains keyword which has the same name as symbol, binds symbol to the corresponding value. If such a keyword doesn't appear in restarg, binds symbol to the result of expr.

    (_symbol_ _keyword_ _expr_)

If the restarg contains keyword keyword, binds symbol to the corresponding value. If such a keyword doesn't appear in restarg, binds symbol to the result of expr.

The default value expr is only evaluated when the keyword is not given to the restarg.

If you use the first form, `let-keyword` raises `&error` condition when restarg contains a keyword argument that is not listed in var-specs. When you want to allow keyword arguments other than listed in var-specs, use the second form.

In the second form, restvar must be either a symbol or #f. If it is a symbol, it is bound to a list of keyword arguments that are not processed by var-specs. If it is #f, such keyword arguments are just ignored.

    (define (proc x . options)
      (let-keywords options ((a 'a)
                             (b :beta 'b)
                             (c 'c)
                             . rest)
        (list x a b c rest)))

    (proc 0)

(0 a b c ())

    (proc 0 :a 1)

(0 1 b c ())

    (proc 0 :beta 1)

(0 a 1 c ())

    (proc 0 :beta 1 :c 3 :unknown 4)

(0 a 1 3 (unknown 4))
Macro let-keywords* restargs (var-spec ... ) body ...
Macro let-keywords* restargs (var-spec ... . restvar) body ...

Like `let-keywords`, but the binding is done in the order of var-specs. So each expr can refer to the variables bound by preceding var-specs.

These let-keywords and let-keywords* are originally from Gauche.

Macro define-with-key variable expression
Macro define-with-key variable
Macro define-with-key (variable formals) body ...
Macro define-with-key (variable . formals) body ...

The `define-with-key` is synonym of `define`.

See more detail Variable definitions.

Macro begin0 exp0 exp1 ...

Evaluate exp0, exp1, ..., then returns the result(s) of exp0.

Macro let1 var expr body ...

A convenient macro when you have only one variable. Expanded as follows:

    (let ((_var_ _expr_)) _body_ ...)

Macro rlet1 var expr body ...

A convenient macro when you have only one variable and is the returning value. Expanded as follows:

    (let ((_var_ _expr_)) _body_ ... _var_)

Macro dotimes (variable limit [result]) body ...
Macro dolist (variable lexpr [result]) body ...

Imported from Common List. These are equivalent to the following forms, respectively.

    (dotimes (variable limit result) body ...)

=>

    (do ((tlimit limit)
         (variable 0 (+ variable 1)))
        ((>= variable tlimit) result)
      body ...)

    (dolist (variable lexpr result) body ...)

=>

    (begin
      (for-each (lambda (variable) body ...) lexpr)
      (let ((variable '())) result))

Macro push! place item

Conses item and the value of place. The place must be either a variable or a form (proc arg ...), as the second argument of `set!`. The result will be the same as `set!`.

Macro pop! place

Retrieves the value of place, sets its cde back to place.

Macro check-arg pred val proc

Check the given val satisfies pred. If the pred returns #f then `&assertion` is raised.

The proc should be the procedure name which uses this macro and is for debugging purpose.

Macro with-library library exprs ...

library must be a library name. ex. (srfi :1 lists)

exprs must be expressions.

Evaluate given expressions one by one in the specified library and returns the last result of the expressions.

This should not be used casually however you want to use some procedures or variables which are not exported, such as a procedure written in C but not exported or non exported record accessor. For thoese purpose, this might be a quick solution.

Macro unwind-protect body cleanups ...

Execute body then execute cleanups and returns the result(s) of body.

It is not guaranteed to invoke the cleanups only once if a continuation is captured in body and call it.

Macro datum x

Short form of `syntax->datum`.

Macro with-syntax* ((p e0) ...) e1 e2 ...

The macro is similar with `with-syntax`, the only difference is that this macro can refer previous pattern of p as if `let*` can.

This can reduce nest level when users need to write multiple `with-syntax` to refer bound syntax object.

Macro ^ formals body ...

The alias of `lambda`.

Macro ^c body ...

Shortened notation of `(lambda (c) body ...)`. Where `c`can be any character of lower case of ASCII alphabet.

    (map (^z (* z z)) '(1 2 3 4 5))

(1 4 9 16 25)
Macro ^c* body ...

Shortened notation of `(lambda c body ...)`. Where `c`can be any character of lower case of ASCII alphabet.

    (map (^z* z*) '(1 2 3 4 5))

((1) (2) (3) (4) (5))

## (sagittarius ffi) - Foreign Function Interface

Library (sagittarius ffi)

This library provides FFI (Foreign Function Interface) procedures. The library is constructed on libffi.

This library makes user to be able to re-use existing useful C library. However it might cause SEGV or unexpected behaviours. It is users responsibility to avoid those errors.

Following is the simple example to use;

    /* C file, must be compiled as a shared library and named 'my-quick-sort.so' */
    #include <stdlib.h>
    #include <string.h>

    #ifdef _MSC_VER
    # define EXPORT __declspec(dllexport)
    #else
    # define EXPORT
    #endif

    static void quicksort_(uintptr_t base,const size_t num,const size_t size,
    		       void *temp,int (*compare)(const void *,const void *))
    {
      size_t pivot = 0,first2last = 0,last2first = num-1;
      while(pivot+1 != num && !compare(base+size*pivot,base+size*(pivot+1))){
        pivot++;
      }
      if(pivot+1 == num){
        return;
      }
      if(0 > compare(base+size*pivot,base+size*(pivot+1))){
        pivot++;
      }
      while(first2last < last2first){
        while(0 < compare(base+size*pivot,base+size*first2last)
    	  && first2last != num-1){
          first2last++;
        }
        while(0 >= compare(base+size*pivot,base+size*last2first)
    	  && last2first){
          last2first--;
        }
        if(first2last < last2first){
          if(pivot == first2last || pivot == last2first){
    	pivot = pivot^last2first^first2last;
          }
          memcpy(temp,base+size*first2last,size);
          memcpy(base+size*first2last,base+size*last2first,size);
          memcpy(base+size*last2first,temp,size);
        }
      }
      quicksort_(base,first2last,size,temp,compare);
      quicksort_(base+size*first2last,num-first2last,size,temp,compare);
    }

    EXPORT int quicksort(void *base, const size_t num, const size_t size,
    	      int (*compare)(const void *, const void *))
    {
      void *temp = malloc(size);
      if(!temp){
        return -1;
      }
      quicksort_((uintptr_t)base,num,size,temp,compare);
      free(temp);
      return 0;
    }

    ;; Scheme file
    ;; load shared library (on Windows the extension might be '.dll')
    ;; On Unix like environment, the shared library must be full path or
    ;; located in the same directory as the script.
    ;; On Windows it can be on PATH environment variable as well.
    (define so-library (open-shared-library "my-quick-sort.so"))
    (define quick-sort
      (c-function so-library ;; shared library
                  void       ;; return type
                  quicksort  ;; exported symbol
                  ;; argument types
                  ;; if you need pass a callback procedure, 'callback' mark needs to
                  ;; be passed to the arguments list
                  (void* size_t size_t callback)))

    (let ((array (u8-list->bytevector '(9 3 7 5 2 6 1 4 8)))
          ;; callback procedure
          (compare (c-callback int           ;; return type
                               (void* void*) ;; argument types
                               (lambda (a b)
                                 (- (pointer-ref-c-uint8 x 0)
                                    (pointer-ref-c-uint8 y 0))))))
      ;; call c function. all loaded c functions are treated the same as
      ;; usual procedures.
      (quick-sort array (bytevector-length array) 1 compare)
      ;; release callback procedure.
      ;; NOTE: callback won't be GCed so users need to release it manually
      (free-c-callback compare)
      array)

    ;; Close shared library.
    (close-shared-library so-library)

#vu8(1 2 3 4 5 6 7 8 9)

The document describes higher APIs to lower APIs.

### Shared library operations

Function open-shared-library file :optional (raise #f)

file must be a string.

Opens given file shared library and returns its pointer.

The internal process of `open-shared-library` is depending on the platform, for example if your platform is POSIX envirionment then it will use `dlopen`. So the resolving the file depends on it. If you know the absolute path of the shared library, then it's always better to use it.

If then internal process of the procedure failed and raise is #f then it returns NULL pointer, if raise is #t then it raises an error.

Function close-shared-library pointer

Closes given shared library pointer and returns unspecified value.

If the given pointer does not indicate proper shared library, the behaviour is platform dependent. It might cause SEGV.

Function shared-object-suffix

Returns platform specific shared library extension as a string value. eg. `".dll"` in Windows, `".so"` in Linux or Unix.

### Creating C functions

This section describes more details to create a corresponding C functions.

Macro c-function shared-library return-type name (argument-types ... )

Creates a c-function object and returns a Scheme procedure.

shared-library must be opened shared-library.

return-type must be one of the followings;

      void
      bool char wchar_t
      short int long long-long
      unsigned-short unsigned-int unsigned-long unsigned-long-long
      intptr_t uintptr_t
      float double
      void* char* wchar_t*
      int8_t  int16_t  int32_t  int64_t
      uint8_t uint16_t uint32_t uint64_t
      character wide-character full-character

The return value will be converted corresponding Scheme value. Following describes the conversion;

`bool`

  Scheme boolean

`char*`

  Scheme string from UTF-8

`wchar_t*`

  Scheme string from UTF-16 (Windows) or UTF-32.

`char`
`short int long long-long`
`unsigned-short unsigned-int unsigned-long unsigned-long-long`
`intptr_t uintptr_t`
`int8_t int16_t int32_t int64_t`
`uint8_t uint16_t uint32_t uint64_t`
`wchar_t`

  Scheme integer

`float double`

  Scheme flonum

`character`
`wide-character`
`full-character`

  Scheme character.
  `character` is mapped to `char` in C , if the Scheme character is out of ASCII range, then the value might get truncated.
  `wide-character` is mapped `wchar_t` in C, the size of the `wchar_t`
  might be different per platform, and the same restriction as `character` is applied. `full-character` is mapped to `int`, more precisely `int32_t` in C. This type holds the UCS32 range of the character.

`void*`

  Scheme FFI pointer type

NOTE: `char` returns a Scheme integer not Scheme character.

name must be a symbol indicating a exported C function name.

argument-types must be zero or more followings;

      bool
      char short int long long-long
      unsigned-short unsigned-int unsigned-long unsigned-long-long
      size_t
      wchar_t
      void* char* wchar_t*
      float double
      int8_t  int16_t  int32_t  int64_t
      uint8_t uint16_t uint32_t uint64_t
      callback
      ___

      character wide-character full-character

When the C function is called, given Scheme arguments will be converted to corresponding C types. Following describes the conversion;

`bool`

  Scheme boolean to C 0 (#f) or 1 (#t).

`char` `int8_t`

  Scheme integer to C char

`short` `int16_t`

  Scheme integer to C signed short

`int` `int32_t`

  Scheme integer to C int

`long`

  Scheme integer to C long

`int64_t long-long`

  Scheme integer to C int64_t

`unsigned-char` `uint8_t`

  Scheme integer to C unsigned char

`unsigned-short` `uint16_t`

  Scheme integer to C unsigned short

`unsigned-int uint32_t size_t`

  Scheme integer to C unsigned int

`unsigned-long`

  Scheme integer to C unsigned long

`uint64_t unsigned-long-long`

  Scheme integer to C uint64_t

`wchar_t`

  Scheme integer to C wchar_t

`float`

  Scheme flonum to C float

`double`

  Scheme flonum to C double

`character` `wide-character` `full-character`

  Scheme character It doesn't check the range, in case of 16 bits wide character, it's users' responsibility to pass the appropriate character. Passing out of range character doesn't raise an error but may truncate the value to be passed.

`void* char*`

  `void*` and `char*` are actually treated the same, internally. The conversion will be like this;

Scheme string

  Converts to UTF-8 C char*

Scheme bytevector

  Convert to C char*

Scheme FFI pointer

  Convert to C void*

`wchar_t*`

  Wide character string conversion only happens when the given argument was Scheme string and depends on the platform. On Windows, more specifically size of wchar_t is 2 platform, it converts to UTF-16 string without BOM. On other platform, size of wchar_t is 4 platform, it converts to UTF-32. Both case detects endianness automatically. If the given argument was bytevector, it won't convert. This case is useful when users need to pass buffer to a C-function.

`callback`

  Scheme FFI callback to C void*

Note: passing Scheme string needs to be careful when users want to use it as a buffer. It doesn't work like it. Use bytevector or FFI pointer object for that purpose.

`___` is for variable length argument and it must be the last position of the argument type list, otherwise it raises an error.

Function make-c-function shared-library return-type name argument-types

Creates C function. This procedure is underlying procedure for `c-function` macro. The arguments are the same as `c-function`, only argument-types must be a list of types.

Macro address pointer
Macro address pointer offset

Convenient macro for address passing.

When you need to pass an address of a pointer to C function, you can write like this; `(c-func (address _pointer_))`

This is equivalent of following C code; `c_func(&pointer)`

pointer can be a pointer object or a bytevector.

If the second form is used, then the passing address is offset of offset. It is user's responsibility to make sure the given pointer has enough space when offset is passed. If the pointer is a bytevector and offset is more than the bytevector size, then an error is signaled.

Macro c-callback return-type (argument-types ... ) proc

Creates a C callback.

return-type must be a symbol and the same as `c-function`'s return-type.

argument-types must be zero or following;

      bool
      char short int long long-long intptr_t
      unsigned-char unsigned-short unsigned-int unsigned-long-long uintptr_t
      int8_t int16_t int32_t int64_t
      uint8_t uint16_t uint32_t int64_t
      float double
      size_t wchar_t
      void* char* wchar_t*
      character wide-character full-character

The conversion of C to Scheme is the same as `c-function`'s return-type.

NOTE: if the content of `void*` won't be copied, thus if you modify it in the callback procedure, corresponding C function will get affected.

NOTE: `char*` and `wchar_t*` lose the original pointer address, this is due to the Scheme string to C string conversion. If the pointer address is required, then use `void*` and bytevector.

proc must be a procedure takes the same number of arguments as argument-types list.

Created callbacks are stored intarnal static storage to avoid to get GCed. This is because C functions which accept callback may hold the given callback in their storage which could be outside of Sagittarius GC root. So it is users' responsibility to release created callback to avoid memory leak. To release callbacks, you need to use `free-c-callback`.

Macro make-c-callback return-type argument-types proc

Creates C callback. This procedure is underlying procedure for `c-callback` macro. The arguments are the same as `c-callback`, only argument-types must be a list of types.

Function free-c-callback callback

Release callback.

### Pointer operations

Using C functions, users can not avoid to use raw pointers. This section describes how to create or convert a pointer.

Function pointer? obj

Returns #t if obj is FFI pointer object, otherwise #f.

Function integer->pointer integer

Converts given integer to pointer object.

To represents NULL pointer, you can write like this;

    (integer->pointer 0)

#\<pointer 0x0>
Function pointer->integer pointer :optional bits
Function pointer->uinteger pointer :optional bits

Converts given pointer to integer/uinteger, respectively.

The optional argument bits must be an exact integer range of fixnum.

If the optional argument bits is specified, then the procedure mask the pointer value. If the bits is negative or more than pointer size bits then it returns non masked value.

This is useful when C procedure sets the pointer value however it only sets a half of bits and returning value is needed only a half of bits. For example, a C procedure takes 2 arguments, one is buffer pointer the other one is buffer size pointer. When buffer size is -1 then it allocates sufficient buffer and sets buffer size pointer the allocated size. In this case. In this case, if you are using 64 bit environment and buffer size pointer is 32 bit value's pointer returning value's upper 32 bit would be 0xFFFFFFFF. If the optional argument is specified to 32 then the procedure only returns lower 32 bit value.

Function pointer->string pointer :optional (transcoder (native-transcoder))

Converts given pointer to Scheme string.

The given pointer must be terminated by 0 otherwise it won't stop until it reaches 0.

If NULL pointer is given, it raises `&assertion`.

Function pointer->bytevector pointer size :optional (offset 0) (shared #t)

Size must be an exact integer.

Converts given pointer to Scheme bytevector from given offset.

If optional argument shared is #f, then the content of pointer won't be shared between pointer and bytevector. Default value is #t, thus if the given pointer is modified, then the created bytevector gets affected.

If NULL pointer is given, it raises `&assertion`.

Function bytevector->pointer bv :optional (offset 0) (shared #t)

Converts given bytevector to pointer from given offset.

If optional argument shared is #f, then the content of bytevector won't be shared between bytevector and pointer. Default value is #t, thus if the given bv is modified, then the created pointer gets affected.

If NULL pointer is given, it raises `&assertion`.

Function object->pointer obj
Function pointer->object pointer

CAUTION: These operations are really dangerous especially `pointer->object`.

Converts Scheme object to pointer and pointer to Scheme object respectively. The operations are useful to pass Scheme object to callbacks and restore it.

Function deref pointer offset

offset must be a fixnum.

Returns a pointer offset offset of given pointer. The same as following C code;

    void* deref(void **pointer, int offset) {
      return pointer[offset];
    }

If `NULL` pointer is given, it raises `&assertion`.

Function pointer-address pointer :optional offset

Returns an address of given pointer.

If optional argument offset is given, then the returning address of pointer is the offset of given offset.

NOTE: This creates a newly allocated Scheme FFI pointer object.

NOTE: If the returned value is modified then given pointer will be affected.

Function allocate-pointer size :optional (fill 0)

size must be a fixnum.

Allocates a size of byte memory and returns an pointer object.

If optional argument fill is given, it must be a fixnum, then the procedure fill the given fill into the allocated memory using `memset(3)`.

NOTE: the fill will be converted to an unsigned char by the `memset(3)`.

The allocated memory will be GCed.

Function c-malloc size

size must be a fixnum.

Allocates a size of byte memory and returns an pointer object using C's `malloc`.

The allocated memory won't be GCed. So releasing the memory is users' responsibility.

Function c-free pointer

pointer must be a pointer created by c-malloc.

Release the pointer.

The procedure won't check if the pointer is allocated by c-malloc or not. And the behaviour when GCable pointer is passed is undefined.

Variable null-pointer

A pointer represents NULL.

This value is not a constant and if you modify this by using `address`, you might break some codes.

Function null-pointer? obj

Returns #t when obj is a pointer representing NULL otherwise #f.

Function empty-pointer

Creates a NULL pointer. This is for convenience.

Function pointer-ref-c- type pointer offset

offset must be a fixnum.

Returns an integer value of offset offset of pointer depending on the type.

Following type are supported;

    int8 int16 int32 int64
    uint8 uint16 uint32 uint64
    char wchar short int long long-long
    unsigned-char unsigned-short unsigned-int unsigned-long unsigned-long-long
    intptr uintptr
    float double
    pointer

    character wide-character full-character

NOTE: if the type is `flonum` or `double`, then it returns Scheme flonum

NOTE: if the type is `pointer`, then it returns Scheme FFI pointer.

NOTE: if the type is `character`, `wide-character` or `full-character`, then it returns Scheme character.

Function pointer-set-c- type ! pointer offset value

offset must be a fixnum.

Sets value to offset offset of pointer. Supporting _type_s are the same as `pointer-ref-c-_type_`The type conversion is the same as `c-function`'s return-type.

NOTE: if the type is `character` or `wide-character`, then the value must be Scheme character.

Function pointer-set-c- type ! pointer offset value

offset must be a fixnum.

Sets value to offset offset of pointer. Supporting _type_s are the same as `pointer-ref-c-_type_`The type conversion is the same as `c-funct

There is no direct procedures to handle C arrays. Following is an example of how to handle array of pointers;

    (import (rnrs) (sagittarius ffi))

    (define (string-vector->c-array sv)
      (let ((c-array (allocate-pointer (* (vector-length sv) size-of-void*))))
        (do ((i 0 (+ i 1)))
            ((= i (vector-length sv)) c-array)
          ;; pointer-set-c-pointer! handles Scheme string (converts to UTF-8)
          ;; If you need other encoding, then you need to write other conversion
          ;; procedure.
          (pointer-set-c-pointer! c-array (* i size-of-void*) (vector-ref sv i)))))

    ;; how to use
    (let ((p (string-vector->c-array #("abc" "def" "ghijklmn"))))
      (do ((i 0 (+ i 1)))
          ((= i 3))
        ;; deref handles pointer offset.
        ;; it can be also (pointer-ref-c-pointer p (* i size-of-void*))
        (print (pointer->string (deref p i)))))

Following is an example for Scheme string to UTF-16 bytevector;

    (import (rnrs) (sagittarius ffi))
    ;; Converts to UTF16 big endian (on little endian environment)
    (define (string->c-string s)
      (let* ((bv (string->utf16 s (endianness big)))
             ;; add extra 2 bytes for null terminated string
             (p  (allocate-pointer (+ (bytevector-length bv) 2))))
        (do ((i 0 (+ i 2)))
            ((= i (bytevector-length bv)) p)
          ;; pointer-set-c-uint16! uses native endianness to set the value
          ;; so this is platform dependent code.
          (pointer-set-c-uint16! p i
            (bytevector-u16-ref bv i (endianness little))))))

Function set-pointer-value! pointer value

value must be exact integer up to `size-of-void*` bytes.

Sets the pointer value. This is useful to reuse the existing pointer object.

CAUTION: this operation is really dangerous so be aware of it!

### C struct operations

C's struct is mere memory chunk so it is possible to access its member directly, if you know exact offset of it. However it is convenient if you can operate similar structure. This section describes how to define C structure in Scheme world.

Macro define-c-struct name clauses ...
Macro define-c-struct name (alignment n) clauses ...

Defines C structure.

clauses must be following form;

    (_type_ _name_)
    (_type_ `array` _size_ _name_)
    (`struct` _struct-name_ _name_)
    (`bit-field` _type_ (_name_ _bit_) ...)
    (`bit-field` (_type_ _endian_) (_name_ _bit_) ...)

name must be a symbol.

If the second form is used, then `alignment` is an auxiliary syntax and n must be an integer which must be either negative number or one of `1`, `2`, `4`, `8`, or `16`. This form specifies the alignemtn of the struct. If the n is negative number, then it uses platform default alignment, if it's one of the above number, then the alignment is according to the given number.

The first form is the simple C type form. type must be a symbol and the same as one of the `c-function`'s return-types or `callback`. Following describes the concrete example and the equivalent C structure:

    (define-c-struct st
      (int foo)
      (callback fn))
    #|
    struct st
    {
      int foo;
      void* fn; /* function pointer */
    };
    |#

The second form is defining C type array with size. Following describes the concrete example and the equivalent C structure:

    (define-c-struct st
      (int array 10 foo))
    #|
    struct st
    {
      int foo[10];
    };
    |#

The third form is defining internal structure. Following describes the concrete example and the equivalent C structure:

    (define-c-struct st1
      (int array 10 foo))
    (define-c-struct st2
      (struct st1 st)
      (int bar))
    #|
    struct st1
    {
      int foo[10];
    };
    struct st2
    {
      struct st1 st;
      int bar;
    };
    |#

So far, we don't support direct internal structure so users always need to extract internal structures.

The forth and fifth forms are bit fields. type must be an integer type such as `unsigned-int`. If the given type is not an integer, then `&assertion` is raised.

Following describes the concrete example and the equivalent C structure:

    (define-c-struct st1
      (bit-field unsigned-int (a 10) (b 20)))
    #|
    struct st1
    {
      unsigned int a : 10;
      unsigned int b : 20;
    };
    |#

If the fifth form is used, then endian must be an identifier which has valid name for `endianness` macro. Then the created structure packs the value according to the given endian.

If the total amount of bits is greater than given type, then `&assertion` is raised.

NOTE: Even though, this can accept signed integer the returning value would not be signed. It is safe to specify unsigned type.

The macro also defines accessors for the c-struct. Following naming rules are applied;

- For getter: name-member-name-ref

- For setter: name-member-name-set!

The macro also defines size variable for the c-struct. If the name of the c-struct if foo, then the variable name will be `size-of-foo`.

Function size-of-c-struct struct

struct must be a C structure defined by `define-c-struct`.

Returns the size of given struct.

Function allocate-c-struct struct

Allocates memory for struct and returns a pointer.

###### [!Function] make-`_struct-name_` :key members ... 0.9.13

A convenient constructor of struct-name c-struct.

Keyword arguments represents the member name, if it's provided, then the value is populdated to the returning pointer.

Function _struct-name_ - member-name -ref struct-pointer inner-member-names ...
Function _struct-name_ - member-name -set! struct-pointer value inner-member-names ...

A getter/setter of struct-name c-struct.

This is automatically defined by `define-c-struct` macro.

The optional argument inner-member-names can be passed to get inner struct values.

Following describes how it works.

    (define-c-struct in
      (int  i)
      (char c))
    (define-c-struct out
      (int  i)
      (struct in in0))

    (define out (allocate-c-struct out))
    (out-i-set! out 100 'i)   ;; -> unspecified
    (out-in0-set! out 200 'i) ;; -> unspecified
    (out-i-ref out)           ;; -> 100
    (out-in0-ref out 'i)      ;; -> 200
    (out-in0-ref out)         ;; -> pointer object (indicating the inner struct address)

#### Low level C struct accessors

Function c-struct-ref pointer struct name

struct must be a C structure defined with `define-c-struct`. name must be a symbol and struct has the same member. pointer should be a pointer allocated by `allocate-c-struct` with struct.

Returns a member name's value of struct from pointer.

Function c-struct-set! pointer struct name value

struct must be a C structure defined with `define-c-struct`. name must be a symbol and struct has the same member. pointer should be a pointer allocated by `allocate-c-struct` with struct.

Sets value to pointer offset of member name of struct.

### Typedef operations

Macro define-c-typedef original new-names ...

Convenient macro.

Defines other name of original with new-names.

new-names must be following forms;

    ()
    ((`*` _new-p_) _rest_ ...)
    ((`s*` _new-sp_) _rest_ ...)
    (_new_ _rest_ ...)

The first for defines nothing.

If the rest of form is used and rest is not null, then it will recursively define.

The second form's `*` defines new-p as `void*`.

The third form's `s*` defines new-sp as `char*`.

The forth form defines new as original.

Following example describes how to will be expanded approximately.

    (define-c-typedef char (* char_ptr) byte (s* string))

    =>

    (begin
      (define char_ptr void*)
      (define byte char)
      (define string char*)
    )

### Sizes and aligns

Constant size-of- type
Constant align-of- type

a size or align of type, respectively.

Following types are supported;

      bool char
      short int long long-long
      unsigned-short unsigned-int unsigned-long unsigned-long-long
      intptr_t uintptr_t size_t
      float double
      int8_t  int16_t  int32_t  int64_t
      uint8_t uint16_t uint32_t uint64_t
      void* wchar_t

The values are platform dependent.

### Finalizer operations

Some of C resource must be released but if you can not decide or do not want to restrict when, then you can release it at GC time.

NOTE: GC might not happen if your script is very short, so it is better not to relay these procedures too much.

Function register-ffi-finalizer pointer proc

pointer must be a pointer allocated with GCable memory.

proc must be a procedure and accepts one argument. The argument will be the pointer.

Register proc as pointer's finalizer and returns pointer.

Function unregister-ffi-finalizer pointer

pointer must be a pointer allocated with GCable memory.

Remove finalizer form pointer and returns pointer.

## (sagittarius filewatch) - Monitoring filesystem

Library (sagittarius filewatch)

Monitoring filesystem cannot be done efficiently without support of underlying operating system. This library provides unified interface of the mechanism.

The following simple `tail (1)` like script shows how it works:

    (import (rnrs) (getopt) (sagittarius filewatch) (prefix (binary io) binary:))

    (define (tail file offset)
      (define watcher (make-filesystem-watcher))
      (define in (open-file-input-port file))
      ;; dump contents to stdout
      (define (dump)
        (let loop ()
          (let ((line (binary:get-line in)))
            (unless (eof-object? line)
              (put-bytevector (standard-output-port) line)
              (put-bytevector (standard-output-port) #vu8(10))
              (loop)))))
      (define size (file-size-in-bytes file))
      ;; move port position if the size if more than offset
      (when (> size offset) (set-port-position! in (- size offset)))
      ;; dump first
      (dump)
      ;; add path to file watcher
      (filesystem-watcher-add-path! watcher file '(modify)
                                    (lambda (path event) (dump)))
      ;; monitor on foreground.
      (filesystem-watcher-start-monitoring! watcher :background #f))

    ;; this tail is not line oriented
    ;; it shows tail of the file from the given offset.
    (define (main args)
      (with-args (cdr args)
          ((offset (#\o "offset") #t "1024")
           . rest)
        (tail (car rest) (string->number offset))))

Function make-filesystem-watcher :key error-handler

Creates and returns filesystem watcher object.

The keyword argument error-handler is specified, which must be a procedure accepts one argument, then it is called with a condition when monitoring handler raised an error.

Function release-filesystem-watcher! watcher

Releasing the watcher.

Released filesystem watcher can not be reused.

Function filesystem-watcher? o

Returns #t if the given o is a filesystem watcher object, otherwise #f.

Function filesystem-watcher-add-path! watcher path flags monitoring-handler

Adds monitoring targets to the watcher.

The path must be a string and indicating existing path.

The flags must be one of the following symbols or list of the symbols:

`access`

  Checks if the path is accessed.

`modify`

  Checks if the path is modified.

`delete`

  Checks if the path is deleted.

`move`

  Checks if the path is moved.

`attribute`

  Checks if the path's attribute is changed.

NOTE: The flags might not be supported depending on the platform. See implementation limitation section for more details.

The monitoring-handler must be a procedure accepts 2 arguments. The procedure is called if the path gets an event specified flags. When the monitoring-handler is invoked, then the path and a symbol of the invoking event are passed respectively. The possible event symbols are the followings:

`accessed`

  Checks if the path is accessed.

`modified`

  Checks if the path is modified.

`deleted`

  Checks if the path is deleted.

`moved`

  Checks if the path is moved.

`attribute`

  Checks if the path's attribute is changed.

The procedure filesystem-watcher-add-path! returns the watcher.

If the watcher started monitoring, then the procedure raises `&assertion`.

Function filesystem-watcher-remove-path! watcher path

Removes given path from the watcher. And returns watcher,

If the watcher started monitoring, then the procedure raises `&assertion`.

Function filesystem-watcher-start-monitoring! watcher :key (background #t)

Starts monitoring filesystem on given watcher.

If the keyword argument background is true value, then the procedure creates a thread and let the thread monitor the filesystem. (So the procedure returns after the thread invocation.) Otherwise, the procedure blocks and wait until other thread calls `filesystem-watcher-stop-monitoring!`.

Function filesystem-watcher-stop-monitoring! watcher

Stops monitoring of given watcher.

If the watcher is started on background, then the monitoring thread may not stop immediately.

### Implementation limitation

Even the library provides unified APIs however users still should know the limitations per operating system to avoid unexpected behaviours. The following sections describes the known limitations.

#### Linux

On Linux, the library is constructed on top of `inotify (7)` and `poll (2)`. If users add too many paths, then it may reach the maximum number of watch descriptor.

The `IN_MOVED_FROM` and `IN_MOVED_TO` flags are passed as `moved`. So it is users responsibility to detect which file is moved from and which file is moved to.

#### BSD Unix

On BSD Unix, the library is constructed on top of `kqueue (2)`. This implementation contains 3 major issues. Possibility of number of file descriptor explosion, not `access` flag support, and no support of directory monitoring.

The `kqueue` requires file descriptor per monitoring path. Thus if the number of paths is large, then it reaches the maxinum number of file descriptors. (NB: `kern.maxfiles` on FreeBSD).

`kqueue` doesn't support path access monitoring (e.g. `IN_ACCESS` on `inotify`). So it is impossible to monitor file access.

Current implementation of `(sagittarius filewatch)` using `kqueue`doesn't allow users to monitor directory. This is because by default, `kqueue` doesn't provide facility to detect which file is added. To do it, we need manual management. To keep our code as simple as possible, we decided not to do it for now. This decision may be changed if there's enough demands.

#### OS X

On OS X, the library is constructed on top of `kqueue`, thus the same limitation as BSD Unix is applied.

#### Windows

Staring Windows Vista, Microsoft decided not to change timestamp just accessing the file or directory by default. So `access` flag may or may not work on Windows depending on the configuration of the platform.

Due to the lack of deletion detect, `delete` and `move` work the same. Thus the monitoring handler may get both `deleted` and `moved`even though it's only specified `delete` or `move`.

## (sagittarius io) - Extra IO library

Library (sagittarius io)

This library provided extra IO related procedures.

Function with-input-from-port port thunk
Function with-output-to-port port thunk
Function with-error-to-port port thunk

Calls thunk. During evaluation of thunk, the current input port, current output port, current error port are set to port, respectively.

Function call-with-input-string str proc
Function call-with-output-string proc
Function with-input-from-string str thunk
Function with-output-to-string thunk

These utility functions are trivially defined as follows;

    (define (call-with-input-string str proc)
      (proc (open-input-string str)))

    (define (call-with-output-string proc)
      (let ((port (open-output-string)))
        (proc port)
        (get-output-string port)))

    (define (with-input-from-string str thunk)
      (with-input-from-port (open-input-string str) thunk))

    (define (with-output-to-string thunk)
      (let ((port (open-output-string)))
        (with-output-to-port port thunk)
        (get-output-string port)))

Function buffered-port port buffer-mode :key buffer
Function transcoded-port port transcoder

Re-export of `buffered-port` and `transcoded-port`.

### Custom ports

Sagittarius provides means to create user defined ports. One of the ways is using R6RS custom port procedures. The other one is extending custom port class. The followings show how to extend it.

    ;; example for input port
    (import (rnrs) (sagittarius io) (clos user))

    ;; make a custom binary input port with 'read slot
    (get-u8 (make <custom-binary-input-port>
              :read (lambda (bv start count)
                      (bytevector-u8-set! bv start 1)
                    1)))

    ;; example for output port
    (import (rnrs) (sagittarius io) (clos user))

    ;; user defined custom binary output port
    (define-class <my-port> (<custom-binary-output-port>)
      ;; this port has own buffer
      ((buffer :init-form (make-bytevector 5 0))))

    ;; create the port
    (let ((out (make <my-port>)))
      ;; set 'write slot
      (slot-set! out 'write
        (lambda (bv start count)
           ;; just get the first element of given bytevector
           ;; and set it to own buffer
           (bytevector-copy! bv start (slot-ref out 'buffer) 0 count)
           count))
      ;;
      (put-bytevector out #vu8(1 2 3 4 5))
      (slot-ref out 'buffer))
    ;; -> #vu8(1 0 0 0 0)

Class <custom-binary-input-port>
Class <custom-binary-output-port>
Class <custom-binary-input/output-port>
Class <custom-textual-input-port>
Class <custom-textual-output-port>
Class <custom-textual-input/output-port>

Custom port classes. All of these classes have the following slots:

Slot id

Identifier of the port. Must be string is specified.

Slot position
Slot set-position
Slot read
Slot write
Slot flush
Slot close

All of them must be either procedure or #f.

`position` procedure must accept 0 argument. The procedure should return the position of the port.

`set-position` procedure must accept 2 argument, position_and_whence. Whence shall be a symbol of `begin`, `current` or `end`. The procedure should set the position of the port according to the given whence and position.

`read` procedure must accept 3 argument. bv or string, start and count. The first argument is decided by the port type. If the port is binary port, then bytevector bv is passed. If the port is textual port, then string string is passed. The procedure should fill given bv or string in _count_data elements starting start. And return number of data filled.

`write` procedure must accept 3 argument. bv or string, start and count. The first argument is decided by the port type. If the port is binary port, then bytevector bv is passed. If the port is textual port, then string string is passed. The procedure should retrieve data from given bv or _string_upto count data elements starting start. And return number of data read.

`ready` procedure must accept 0 argument. The procedure should return true value if the port is ready to read. Otherwise #f.

`flush` procedure must accept 0 argument. The procedure should flush the port.

`close` procedure must accept 0 argument. The procedure should close the port.

If the creating port is input port, then `read` must be set before any port operation. If the creating port is output port, then `write`must be set before any port operation. Other slots are optional.

## Sagittarius MOP

MOP is "meta object protocol". As far as I know, there is no standard specification even the name is really famous and most of CLOS is implemented on MOP.

Then we decided to take the APIs and its behaviour from Tiny CLOS. The following libraries are implemented with the APIs and can be examples for Sagittarius' MOP.

### (sagittarius mop allocation)

Library (sagittarius mop allocation)

Supporting `:allocation` option for `define-class`.

Class <allocation-meta>
Class <allocation-mixin>

Meta class and mixin class to support `:allocation` option for class slot definition, respectively.

The meta class must be used with `:metaclass` option of `define-class`.

The mixin class must be a parent class.

Currently, we only support `:instance` and `:class` keywords.

The following code is the whole definition of this classes.

    (define-class <allocation-meta> (<class>) ())
    (define-method compute-getter-and-setter ((class <allocation-meta>) slot)
      (cond ((slot-definition-option slot :allocation :instance)
             => (lambda (type)
                  (case type
                    ((:instance) '())
                    ((:class)
                     (let* ((init-value (slot-definition-option
                                         slot :init-value #f))
                            (init-thunk (slot-definition-option
                                         slot :init-thunk #f))
                            (def (if init-thunk (init-thunk) init-value)))
                       (list
                        (lambda (o) def)
                        (lambda (o v) (set! def v)))))
                    (else
                     (assertion-violation '<allocation-meta>
                                          "unknown :allocation type"
                                          type)))))
            (else (call-next-method))))

    (define-class <allocation-mixin> () () :metaclass <allocation-meta>)

### (sagittarius mop validator)

Library (sagittarius mop validator)

Supporting `:validator` and `observer` options for `define-class`.

Class <validator-meta>
Class <validator-mixin>

Make user be able to add own validation mechanism to slots.

`:validator` is for before set the value to the slot so that user can check the value if it's correct or not.

`:observer` is for after set the value to the slot so that user can check which value is set to the slot.

### (sagittarius mop eql)

The eql specializer is now builtin so this library is only for backward compatibility.

Library (sagittarius mop eql)

Supporting eql specializer methods.

The following code describes how to use;

    (import (clos user) (sagittarius mop eql))
    (define-generic eql-fact :class <eql-specializable-generic>)
    (define-method eql-fact ((n (eql 0))) 1)
    (define-method eql-fact ((n <integer>)) (* n (eql-fact (- n 1))))
    (eql-fact 10)

3628800

Note: The eql specializer is really slow approximately 200 time slower than usual procedure call.

Class <eql-specializable-generic>

Subclass of `<generic>`.

To use eql specializer, generic functions must have this class as a metaclass.

## (sagittarius object) - Convenient refs and coercion procedures

Library (sagittarius object)

This library provides convenient procedures.

Generic ref object key args ...
Generic (setter ref) object key value

Returns given object's values associated with key. The default implementation uses `slot-ref`.

Following classes are specialised by default.

- `<hashtable>` uses `hashtable-ref`

- `<list>` uses `list-ref`

- `<string>` uses `string-ref`

- `<vector>` uses `vector-ref`

Generic ->string object

Returns string represented object.

Generic ->integer object

Returns integer represented object.

Generic ->number object

Returns number represented object.

The default value is 0.

If the given object is number, it returns given object itself.

If the given object is string, it uses `string->number` as a conversion procedure.

If the given object is character, it uses `char->integer` as a conversion procedure.

## (sagittarius process) - Process library

In real world, there are a lot of useful programs and you want to re-use it rather than re-write it in Scheme. For that purpose, this library can be useful.

The concept of this library is similar with Java's Process class. Users can create process object and run/call whenever they want. However most of the time process can be invoked immediately, so there are high level APIs for that purpose.

This section describe from top to down.

Library (sagittarius process)

Exports high level APIs and low level APIs for operating process.

### High level APIs

Function run name arg1 ...
Function call name arg1 ...

name must be string and indicate the process name be called.

arg1 and the rest must be string which will be passed to process.

The `run` procedure invokes name process and waits until it ends. Then returns process' exit status.

The `call` procedure invokes name process and continue the Scheme process, so it does not wait the called process. Then returns process object. If you need to finish the process, make sure you call the `process-wait`procedure described below.

Both procedures' output will be redirects `current-output-port` and `current-error-port`. If you need to redirect it other place use `create-process` described below.

### Middle level APIs

Function create-process name args _

_ :key (stdout #f) (stderr #f) (call? #t) reader (transcoder #f)

name must be string and indicate a process name.

args must be list of string will be passed to the process.

The `create-process` procedure creates and invokes a process indicated name. Keyword arguments decide how to invoke and where to redirect the outputs.

If stdout is #f or non output-port and call? is #f then `create-process` raises `&assertion`.

stdout keyword argument indicates the port where to redirect the standard output of the process. This can be either binary output port or textual output port.

stderr keyword argument indicates the port where to redirect the standard error of the process. This can be either binary output port or textual output port. If this argument is #f, then stdout will be used.

call? keyword argument decides the default behaviour. If this is #t and reader is not a procedure, then the `create-process` uses `async-process-read`. If this is #f and reader is not a procedure, then it uses `sync-process-read`. If reader is provided, then it uses given reader.

reader keyword argument must be procedure which takes 4 arguments, process object, redirection of standard output and error, and transcoder respectively. This procedure decides how to handle the output.

Note: on Windows, both standard output end error has limitation. So if you replace the default behaviour, make sure you must read the output from the process, otherwise it can cause deat lock.

transcoder keyword argument must be transcoder or #f. This can be used in the procedure which specified reader keyword argument.

The procedure `create-process` creates a process and call it. The returning value is depending on the above keyword parameters. If _reader_and stdout is provided, then the result value is the value returned from reader procedure. Otherwise the created process object.

Function async-process-read process stdout stderr transcoder

Process output reader. This reader creates 2 threads to read standard ouput and standard error. The reader returns immediately after the threads are executed.

Function sync-process-read process stdout stderr transcoder

Process output reader. This reader creates 2 threads to read standard ouput and standard error. The reader waits until the given process is finished.

### Low level APIs

This section describe low level APIs however some of these might be used even if you use `call` described above.

Function process? obj

Returns #f if obj is process object, otherwise #f.

Function make-process name args

name must be string and indicates the process name which will be invoked.

args must be empty list or list of strings and will be passed to the process.

Creates a process object.

Function process-input-port process

process must be a process object.

Returns the binary output port which is redirected to the process' standard input.

Function process-output-port process

process must be a process object.

Returns the binary input port which is redirected to the process' standard output.

Function process-error-port process

process must be a process object.

Returns the binary input port which is redirected to the process' standard error.

Function process-run process

process must be a process object.

Invokes the process and wait until it ends.

On POSIX envionment this procesure returns the result status of the process.

Function process-call process

process must be a process object.

Invokes the process and continue the Scheme program.

Function process-wait process :key timeout

process must be a process object.

Wait the given process until it ends and returns the exit status of the given process.

If the keyword argument timeout is specified, then it must be an integer represents second or time object represents absolute time, then the procedure waits either the given process is finished or until the specified timeout period is passed. When the timeout period has passed and yet the process is not finished, then the procedure returns `#f`.

NOTE: The exit status are platform dependent. On Windows, the value will be 32 bit integer. On POSIX, the value will be 8 bit unsigned integer.

NOTE: On POSIX environment, timeout only works if the given process is created by `make-process` related procedures. If the process is created by `pid->process`, then it raises an error with `ECHILD`.

Function process-kill process :key children?

process must be a process object.

Kill the given process and returns the exit status of the given process. If the process is already terminated before the `process-kill`is called, then returning value is its status code. Otherwise -1.

If the keyword argument children? is given and if it's true value, then the procedure kills the child processes. The process of killing child processes is not the same between Windows and POSIX. On Windows, the process seeks all possible child processes. On POSIX, it simply calls `killpg (2)`.

Function process-active? process

process must be a process object.

Return #t if the given process is still active. Otherwise #f.

On Windows, the procedure uses `GetExitCodeProcess` which means if the process returns `STILL_ACTIVE(259)`, then this procedure return #t even if the process itself is already terminated.

On POSIX, the procedure uses `kill (2)` sending 0 to check the existance of the process.

Function getpid

Returns pid of current Sagittarius process. The returning value is an integer.

Function pid->process pid

pid must be an integer represents process id.

Creates a process form given pid.

NOTE: the created process doesn't have any ports. Those values are set to #f.

### Inter-process communication (IPC)

Users can choose how to communicate processes. One of the typical ways is using socket. `(sagittarius process)` provides shared memory for simple IPC.

Function shared-memory? obj

Returns #t if given obj is a shared memory object, otherwise #f.

Function open-shared-memory name size :optional option

Creates or opens shared memory named name.

name must be an string and must be a valid shared memory name. If there is already a shared memory with the same name, then this procedure maps to it and ignores the size argument.

size must be an integer. When a new shared memory is created, then its size is restricted to the given size.

Optional argument option must be an enumeration which created by file-options. If `no-create` is specified, and there is no shared memory with given name, then `&i/o-file-does-not-exist`is raised. If `no-truncate` is specified, then the created shared memory is intact, otherwise it is truncted.

Function close-shared-memory shared-memory

Closes given shared-memory and invalidate the allocated memory.

This procedure also removes the given shared-memory. On some platform, for example Linux, if shared memory is not explicitly unliked, then it stays until the OS is restarted. To avoid it, users need to call this procedure.

NOTE: invalidation means that the bytevector returned by `shared-memory->bytevector` will be 0 length bytevector.

Function shared-memory->bytevector shared-memory

Returns actual instance of shared memory as a bytevector.

Modifying the returning bytevector also modifies the actual shared memory.

To do synchronisation of this, use semaphore provided by `(sagittarius threads)`.

## (sagittarius reader) - reader macro library

Sagittarius provides functionalities to modify its reader like Common Lisp. It makes the reader programable. However it has some restriction to use. The following examples explain it.

Using reader macro

    #!read-macro=sagittarius/regex
    (import (sagittarius regex)) ;; usual import for procedures
    #/regex/i                    ;; (sagittarius regex) defines #/regex/ form
                                 ;; reader macro in it. it converts it
                                 ;; (comple-regex "regex" CASE-INSENSITIVE)

Writing reader macro on toplevel

    (import (rnrs) (sagittarius reader))
    (set-macro-character #\$
     (lambda (port c) (error '$-reader "invliad close paren appeared")))
    (set-macro-character #\! (lambda (port c) (read-delimited-list #\$ port)))
    !define test !lambda !$ !display "hello reader macro"$$$
    !test$ ;; prints "hello reader macro"

Writing reader macro in library and export it

    #!compatible ;; make sure Sagittarius can read keyword
    (library (reader macro test)
        ;; :export-reader-macro keyword must be in export clause
        (export :export-reader-macro)
        (import (rnrs) (sagittarius reader))

      (define-reader-macro $-reader #\$
        (lambda (port c)
          (error '$-reader "unexpected close paren appeared")))

      (define-reader-macro !-reader #\!
        (lambda (port c)
          (read-delimited-list #\$ port)))
    )

    #!read-macro=reader/macro/test  ;; imports reader macro
    !define test !lambda !$ !display "hello reader macro"$$$
    !test$    ;; prints "hello reader macro"

If you need to use reader macro in your library code, you need to define it outside of the library. The library syntax is just one huge list so Sagittarius can not execute the definition of reader macro inside during reading it.

Library (sagittarius reader)

This library provides reader macro procedures and macros.

Macro define-reader-macro char (name args ... ) body ...
Macro define-reader-macro name char proc
Macro define-reader-macro name char proc non-term?

Name must be self evaluated expression. Proc must accept 2 or 3 arguments, the first one is a port, the second one is a character which is defined as reader macro character, and the third one which is an optional argument is a read context.

`define-reader-macro` macro associates char and proc as a reader macro. Once it is associated and Sagittarius' reader reads it, then dispatches to the proc with 2 arguments.

If non-term? argument is given and not #f, the char is marked as non terminated character. So reader reads as one identifier even it it contains the given char in it.

The first form is a convenient form. Users can write a reader macro without explicitly writing `lambda`. The form is expanded to like this:

    (define-reader-macro #\$ ($-reader args ...) body ...)
    ;; -> (define-reader-macro $-reader #\$ (lambda (args ...) body ...))

Note: the name is only for error message. It does not affect anything.

Macro define-dispatch-macro name char subchar proc
Macro define-dispatch-macro name char proc subchar non-term?

Name must be self evaluated expression. Proc must accept three arguments, the first one is a port, the second one is a character which is defined as reader macro character and the third one is a macro parameter.

`define-dispatch-macro` creates macro dispatch macro character _char_if there is not dispatch macro yet, and associates subchar and _proc_as a reader macro.

If non-term? argument is given and not #f, the char is marked as non terminated character. So reader reads as one identifier even it it contains the given char in it.

Note: the name is only for error message. It does not affect anything.

Function get-macro-character char

Returns 2 values if char is macro character; one is associated procedure other one is boolean if the char is terminated character or not. Otherwise returns 2 #f.

Function set-macro-character char proc :optional non-term?

Mark given char as macro character and sets the proc as its reader. If non-term? is given and not #f, the char will be marked as non terminated macro character.

Function make-dispatch-macro-character char :optional non-term?

Creates a new dispatch macro character with given char if it is not a dispatch macro character yet. If non-term? is given and not #f, the char will be marked as non terminated macro character.

Function get-dispatch-macro-character char subchar

Returns a procedure which is associated with char and _subchar_as a reader macro. If nothing is associated, it returns #f.

Function set-dispatch-macro-character char subchar proc

Sets proc as a reader of subchar under the dispatch macro character of char.

Function read-delimited-list char :optional (port (current-input-port))

Reads a list until given char appears.

### Predefined reader macros

The following table explains predefined reader macros.

Macro character | Terminated | Explanation
--- | --- | ---
#\( | #t | Reads a list until reader reads #\).
#\[ | #t | Reads a list until reader reads #\].
#\) | #t | Raises read error.
#\] | #t | Raises read error.
#\| | #t | Reads an escaped symbol until reader reads #\|.
#\" | #t | Reads a string until reader reads #\".
#\' | #t | Reads a symbol until reader reads delimited character.
#\; | #t | Discards read characters until reader reads a linefeed.
#\` | #t | Reads a next expression and returns `(quasiquote _expr_)`
#\, | #t | Check next character if it is `@` and reads a next expression. Returns `(unquote-splicing _expr_)` if next character was `@`, otherwise `(unquote _expr_)`
#\: | #f | Only compatible mode. Reads a next expression and returns a keyword.
#\# | #t(R6RS mode) | Dispatch macro character.

Sub character | Explanation
--- | ---
#\' | Reads a next expression and returns `(syntax _expr_)`.
#\` | Reads a next expression and returns `(quasisyntax _expr_)`
#\, | Check next character if it is `@` and reads a next expression. Returns `(unsyntax-splicing _expr_)` if next character was `@`, otherwise `(unsyntax _expr_)`
#\! | Reads next expression and set flags. The details are described the below section
#\v | Checks if the next 2 characters are `u` and `8` and reads a bytevector.
#\u | Only compatible mode. Checks if the next character is `8` and reads a bytevector.
#\t and #\T | Returns #t.
#\f and #\F | Returns #f.
#\b and #\B | Reads a binary number.
#\o and #\O | Reads a octet number.
#\d and #\D | Reads a decimal number.
#\x and #\X | Reads a hex number.
#\i and #\I | Reads a inexact number.
#\e and #\E | Reads a exact number.
#\( | Reads a next list and convert it to a vector.
#\; | Reads a next expression and discards it.
#\| | Discards the following characters until reader reads `|#`
#\\ | Reads a character.
#\= | Starts reading SRFI-38 style shared object.
#\# | Refers SRFI-38 style shared object.

#### #! - Switching mode

Sagittarius has multiple reader and VM modes and users can switch these modes with `#!`. Following describes details of those modes;

`#!r6rs`: R6RS mode

  Symbols are read according to R6RS specification and VM sets the `no-overwrite` and `nounbound` flag. With this mode, keywords are read as symbols; for example, `:key` is just a symbol and users can not use extended `lambda` syntax.

`#!r7rs`: R7RS mode

  The mode for new specification of Scheme. This mode is less strict than R6RS mode described above. The reader can read keyword and VM sets the `no-overwrite` flag.

`#!compatible`: Compatible mode

  This mode is least strict mode. In other words, it does not have any restrictions such as described above.

NOTE: If you import reader macro with `#!read-macro=` form and let reader reads above hash-bang, the read table will be reset. So following code will raise a read error;

    #!read-macro=sagittarius/regex
    #!r6rs
    #/regular expression/ ;; <- &lexical

### Replacing reader

Since 0.3.7, users can replace default reader. Following example describes how to replace reader.

    #!reader=srfi/:49
    define
      fac n
      if (zero? n) 1
        * n
          fac (- n 1)

    (print (fac 10))

`#!reader=` specifies which reader will be used. For this example, it will use the one defined in `(srfi :49)` library. For compatibility of the other Scheme implementation, we chose not to use the library name itself but a bit converted name.

This is the list of `#!` flags:

`#!r6rs`

  Switches to R6RS mode

`#!r7rs`

  Switches to R7RS mode

`#!compatible`

  Switches to compatible mode

`#!no-overwrite`

  Sets no-overwrite flag that does not allow user to overwrite exported variables.

`#!nocache`

  Sets disable cache flag on the current loading file

`#!deprecated`

  Display warning message of deprecated library.

`#!reader=name`

  Replace reader with library name. The name must be converted with the naming convention described below. For more details, see Naming convention

`#!read-macro=name`

  name must be converted with the naming convention described below. For more details, see Naming convention

#### Naming convention

The naming convention is really easy. For example, replacing with `(srfi :49)`, first remove all parentheses or brackets then replace spaces to `/`. Then you get `srfi/:49`.

Macro define-reader name expr
Macro define-reader (name port) expr ...

This macro defines replaceable reader.

The forms are similar with `define`. However if you use the first form then expr must be `lambda` and it accept one argument.

The defined reader will be used on read time, so it needs to return valid expression as a return value of the reader.

NOTE: Only one reader can be defined in one library. If you define more than once the later one will be used.

NOTE: If you want to export user defined reader to other library, you need to put `:export-reader` keyword to the library export clause.

## (sagittarius record) - Extra record inspection library

Library (sagittarius record)

This library provides extra record operations.

Function record-type? obj

Returns #t if obj is record type, otherwise #f.

Function make-record-type name rtd rcd

Name must be symbol. Rtd must be record type descriptor. Rcd must be record constructor descriptor.

Associates given rcd to gien rtd.

NOTE: this procedure doesn't create fresh record type but modifies given arguments destructively.

Function record-type-rtd record-type

Record-type must be record type.

Returns associated rtd from record-type.

Function record-type-rtd record-type

Record-type must be record type.

Returns associated rcd from record-type.

Note: These procedures are not for using casually.

## (sagittarius regex) - regular expression library

As most of script language have own regular expression mechanism, Sagittarius also has own regular expression library. It is influenced by Java's regular expression, so there are a lot of differences between the most famous Perl regular expression(perlre).

This feature may be changed, if R7RS large requires Perl like regular expression.

Following examples show how to use Sagittarius's regular expression.

    ;; For Perl like
    (cond ((looking-at (regex "^hello\\s*(.+)") "hello world!")
            => (lambda (m) (m 1))))

world!

    ;; For Java like
    (cond ((matches (regex "(\\w+?)\\s*(.+)") "123hello world!")) ;; this won't match
          (else "incovenient eh?"))

The `matches` procedure is total match, so it ignores boundary matcher `'^'` and `'$'`. The `looking-at` procedure is partial match, so it works as if perlre.

Library (sagittarius regex)

This library provides Sagittarius regular expression procedures.

### User level APIs for regular expression

Function regex string :optional flags

String must be regular expression. Returns compiled regular expression. Flags' descriptions are the end of this section. The following table is the supported regular expression constructs.

Construct | Matches
--- | ---
Characters | <
`x` | The character x
`\\` | The backslash character
`\0n` | The character with octal value 0n (0 <= n <= 7)
`\0nn` | The character with octal value 0nn (0 <= n <= 7)
`\0mnn` | The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)
`\xhh` | The character with hexadecimal value 0xhh
`\uhhhh` | The character with hexadecimal value 0xhhhh
`\Uhhhhhhhh` | The character with hexadecimal value 0xhhhhhhhh. If the value exceed the maxinum fixnum value it rases an error.
`\t` | The tab character ('\u0009')
`\n` | The newline (line feed) character ('\u000A')
`\r` | The carriage-return character ('\u000D')
`\f` | The form-feed character ('\u000C')
`\a` | The alert (bell) character ('\u0007')
`\e` | The escape character ('\u001B')
`\cx` | The control character corresponding to x
Character classes | <
`[abc]` | a, b, or c (simple class)
`[^abc]` | Any character except a, b, or c (negation)
`[a-zA-Z]` | a through z or A through Z, inclusive (range)
`[a-d[m-p]]` | a through d, or m through p: [a-dm-p] (union)
`[a-z&&[def]]` | d, e, or f (intersection)
`[a-z&&[^bc]]` | a through z, except for b and c: [ad-z] (subtraction)
`[a-z&&[^m-p]]` | a through z, and not m through p: a-lq-z
Predefined character classes | <
`.` | Any character (may or may not match line terminators)
`\d` | A digit: [0-9]
`\D` | A non-digit: [^0-9]
`\s` | A whitespace character: [ \t\n\x0B\f\r]
`\S` | A non-whitespace character: [^\s]
`\w` | A word character: [a-zA-Z_0-9]
`\W` | A non-word character: [^\w]
Boundary matchers | <
`^` | The beginning of a line
`$` | The end of a line
`\b` | A word boundary
`\B` | A non-word boundary
`\A` | The beginning of the input
`\G` | The end of the previous match
`\Z` | The end of the input but for the final terminator, if any
`\z` | The end of the input
Greedy quantifiers | <
`X?` | X, once or not at all
`X*` | X, zero or more times
`X+` | X, one or more times
`X{n}` | X, exactly n times
`X{n,}` | X, at least n times
`X{n,m}` | X, at least n but not more than m times
Reluctant quantifiers | <
`X??` | X, once or not at all
`X*?` | X, zero or more times
`X+?` | X, one or more times
`X{n}?` | X, exactly n times
`X{n,}?` | X, at least n times
`X{n,m}?` | X, at least n but not more than m times
Possessive quantifiers | <
`X?+` | X, once or not at all
`X*+` | X, zero or more times
`X++` | X, one or more times
`X{n}+` | X, exactly n times
`X{n,}+` | X, at least n times
`X{n,m}+` | X, at least n but not more than m times
Logical operators | <
`XY` | X followed by Y
`X|Y` | Either X or Y
`(X)` | X, as a capturing group
Back references | <
`\n` | Whatever the nth capturing group matched
Quotation | <
`\` | Nothing, but quotes the following character
`\Q` | Nothing, but quotes all characters until \E
`\E` | Nothing, but ends quoting started by \Q
Special constructs (non-capturing) | <
`(?:X)` | X, as a non-capturing group
`(?imsux-imsux)` | Nothing, but turns match flags on - off
`(?imsux-imsux:X)` | X, as a non-capturing group with the given flags on - off
`(?=X)` | X, via zero-width positive lookahead
`(?!X)` | X, via zero-width negative lookahead
`(?<=X)` | X, via zero-width positive lookbehind
`(?<!X)` | X, via zero-width negative lookbehind
`(?>X)` | X, as an independent, non-capturing group
`(?#...)` | comment.

Since version 0.2.3, `\p` and `\P` are supported. It is cooporated with SRFI-14 charset. However it is kind of tricky. For example regex parser can reads `\p{InAscii}` or `\p{IsAscii}` and search charset named `char-set:ascii` from current library. It must have `In` or `Is`as its prefix.

Reader Macro #/-reader

This reader macro provides Perl like regular expression syntax. It allows you to write regular expression like this `#/\w+?/i` instead of like this `(regex "\\w+?" CASE-INSENSITIVE)`.

Function looking-at regex string

Regex must be regular expression object. Returns closure if regex matches input string.

The `matches` procedure attempts to match the entire input string against the pattern of regex.

The `looking-at` procedure attempts to match the input string against the pattern of regex.

Function regex-replace-first pattern text replacement
Function regex-replace-first matcher replacement
Function regex-replace-all pattern text replacement
Function regex-replace-all matcher replacement

Pattern must be pattern object.

The first form of these procedures are for convenience. It is implemented like this;

    (define (regex-replace-all pattern text replacement)
      (regex-replace-all (regex-matcher pattern text) replacement))

Text must be string.

Replacement must be either string or procedure which takes matcher object and string port as its arguments respectively.

Replaces part of text where regex matches with replacement.

If replacement is a string, the procedure replace text with given string. Replacement can refer the match result with ``$_n_``. n must be group number of given pattern or matcher.

If replacement is a procedure, then it must accept either one or two arguments. This is for backward compatibility.

The first argument is always current matcher.

If the procedure only accepts one argument, then it must return a string which will be used for replacement value.

If the procedure accepts two arguments, then the second one is string output port. User may write string to the given port and will be the replacement string.

The `regex-replace-first` procedure replaces the first match.

The `regex-replace-all` procedure replaces the all matches.

Function string-split text pattern

text must be a string.

pattern must be a string or regex-pattern object.

Split text accoding to pattern.

### Low level APIs for regular expression

The above procedures are wrapped User level API. However, you might want to use low level API directory when you re-use matcher and recursively find pattern from input. For that purpose, you need to use low level APIs directly.

NOTE: This API might be changed in future depending on R7RS large.

Function regex-pattern? obj

Returns #f if obj is regular expression object, otherwise #f.

Function regex-matcher? obj

Returns #f if obj is matcher object, otherwise #f.

Function compile-regex string :optional flags

The same as `regex` procedure.

Function regex-matcher regex string

Regex must be regular expression object. Returns matcher object.

Function regex-matches matcher

Matcher must be matcher object. Returns #t if matcher matches the entire input string against input pattern, otherwise #f.

Function regex-looking-at matcher

Matcher must be matcher object. Returns #t if matcher matches the input string against input pattern, otherwise #f.

Function regex-find matcher :optional start

Matcher must be matcher object. Resets matcher and then attempts to find the next subsequence of the input string that matches the pattern, starting at the specified index if optional argument is given otherwise from the beginning.

Function regex-group matcher index

Matcher must be matcher object. Index must be non negative exact integer.

Retrieve captured group value from matcher.

Function regex-capture-count matcher

Matcher must be matcher object.

Returns number of captured groups.

### Regular expression flags

Regular expression compiler can take following flags.

CASE-INSENSITIVE

  Enables case-insensitive matching. `i` as a flag

COMMENTS

  Permits whitespace and comments in pattern. `x` as a flag

MULTILINE

  Enables multiline mode. `m` as a flag

LITERAL

  Enables literal parsing of the pattern.

DOTAIL

  Enables dotall mode. `s` as a flag

UNICODE

  Enables Unicode-aware case folding and pre defined charset. `u` as a flag. NOTE: when this flag is set then pre defined charset, such as `\d` or `\w`, expand it's content to Unicode characters. Following properties are applied to charsets. [[:lower:]]

  The lower case charset contains `Ll` and `Other_Lowercase`. [[:upper:]]

  The upper case charset contains `Lu` and `Other_Uppercase`. [[:title:]]

  The upper case charset contains `Lt`. [[:alpha:]]

  The upper case charset contains `L`, `Nl` and `Other_Alphabetic`. [[:numeric:]]

  The upper case charset contains `Nd`. [[:punct:]]

  The upper case charset contains `P`. symbol

  The upper case charset contains `Sm`, `Sc`, `Sk` and `So`. [[:space:]]

  The upper case charset contains `Zs`, `Zl` and `Zp`. [[:cntrl:]]

  The upper case charset contains `Cc`, `Cf`, `Co`, `Cs`, and `Cn`.

### Regular expression for bytevectors

Above APIs can be used bytevectors as well. In this case, the regular expression engine treats given bytevectors as if it's ASCII strings. If users want to use this feature, users must give bytevectors instead of strings.

## (sagittarius socket) - socket library

This section describes low level socket API on Sagittarius. The following example is simple echo server, it receives input from a client and just returns it to the client.

The example program is from example/socket/echo.scm.

    (import (rnrs) (sagittarius socket))
    ;; creates echo server socket with port number 5000
    (define echo-server-socket (make-server-socket "5000"))
    ;; addr is client socket
    (let loop ((addr (socket-accept echo-server-socket)))
      (call-with-socket addr
       (lambda (sock)
         ;; socket-port creates binary input/output port
         ;; make it transcoded port for convenience.
         (let ((p (transcoded-port (socket-port sock)
    			       ;; on Sagittarius Scheme native-transcoder
    			       ;; uses utf8 codec for ASCII compatibility.
    			       ;; For socket programming it might be better
    			       ;; to specify eol-style with crlf.
    			       ;; But this sample just shows how it goes.
    			       (native-transcoder))))
           (call-with-port p
    	(lambda (p)
    	  (put-string p "please type something\n\r")
    	  (put-string p "> ")
    	  ;; gets line from client.
    	  (let lp2 ((r (get-line p)))
    	    (unless (eof-object? r)
    	      (print "received: " r)
    	      ;; just returns message from client.
    	      ;; NB: If client type nothing, it'll throw assertion-violation.
    	      (put-string p r)
    	      (put-string p "\r\n> ")
    	      ;; waits for next input.
    	      (lp2 (get-line p)))))))))
      ;; echo server waits next connection.
      (loop (socket-accept echo-server-socket)))

Library (sagittarius socket)

This library provides procedures for socket programming.

Function make-client-socket node srvice :opational ( ai_family `AF_INET` ) ( ai_socktype `SOCK_STREAM` ) ( ai_flags `(+ AI_V4MAPPED AI_ADDRCONFIG)` ) (_ai_protocol `0` )

Node and service must be string or #f. Other optional arguments must be exact integer.

Returns a client socket connected to an Internet address. The Internet address is identified by node and service. The `make-client-socket` uses `getaddrinfo(3)` to look it up. The arguments node, service, ai-family, ai-socktype, ai-flags and ai-protocol are passed to `getaddrinfo(3)` as corresponding parameters. For more detail, see reference of `getaddrinfo(3)`.

Node is a network address, ex) "www.w3.org", "localhost", "192.168.1.1".

Service is a network service, ex) "http", "ssh", "80", "22".

Ai-family is an address family specifier. Predefined specifiers are listed below.

- AF_INET

- AF_INET6

- AF_UNSPEC

Ai-sockettype is a socket type specifier. Predefined specifiers are listed below.

- SOCK_STREAM

- SOCK_DGRAM

- SOCK_RAW

Ai-flags is an additional options specifier. Predefined specifiers are listed below.

- AI_ADDRCONFIG

- AI_ALL

- AI_CANONNAME

- AI_NUMERICHOST

- AI_NUMERICSERV

- AI_PASSIVE

- AI_V4MAPPED

Ai-protocol is a protocol specifier. Predefined specifiers are listed below.

- IPPROTO_TCP

- IPPROTO_UDP

- IPPROTO_RAW

Function make-server-socket service :optional ( ai_family `AF_INET` ) ( ai_socktype `SOCK_STREAM` ) ( ai_protocol `0` )

Service must be string or #f. Other optional arguments must be exact integer. Returns a server socket waiting for connections. The argument details are the same as the `make-client-socket`.

Function socket? obj

Returns #t if obj is socket object, otherwise #f.

Function socket-port socket :optional ( close? `#t` )

Socket must be a socket object. Returns a binary input/output port associated with socket.

If optional argument close? is #f then the port won't close socket when port is closing or being GCed.

Function socket-input-port socket
Function socket-output-port socket

[SRFI-106] Socket must be a socket object. Returns a binary input and output port associated with socket, respectively.

Function call-with-socket socket proc

Socket must be a socket object. Proc must accept one argument.

The `call-with-socket` calls a procedure with socket as an argument.

This procedure is analogy with `call-with-port`.

Function shutdown-port port how

Port must be associated with a socket.

Shutdowns associated port according to how.

Function shutdown-input-port port
Function shutdown-output-port port

Port must be associated with a socket.

The `shutdown-output-port` and `shutdown-input-port` shutdown output or input connection of a socket associated with port respectively.

Function socket-accept socket

Socket must be a socket object created by `make-server-socket`.

Wait for an incoming connection request and returns a fresh connected client socket.

This procedures is a thin wrapper of POSIX's `accept(2)`.

If the calling thread is interrupted by `thread-interrupt!`, then the procedure returns #f.

Function socket-recv socket size :optional ( flags `0` )

Socket must be a socket object.

Receives a binary data block from given socket. If zero length bytevector is returned, it means the peer connection is closed.

This procedures is a thin wrapper of POSIX's `recv(2)`.

Function socket-send socket bytevector :optional ( flags `0` )

Socket must be a socket object.

Sends a binary data block to given socket and returns the sent data size.

This procedures is a thin wrapper of POSIX's `send(2)`.

Function socket-shutdown socket how

Socket must be a socket object. How must be one of the `SHUT_RD`, `SHUT_WR` or `SHUT_RDWR`.

The `socket-shutdown` shutdowns socket.

SHUT_RD

  shutdowns input.

SHUT_WR

  shutdowns output.

SHUT_RDWR

  shutdowns input and output.

Function socket-close socket

Socket must be a socket object. Closes socket.

### Socket information

Class <socket-info>

The socket information immutable class. This class has 3 slots

Slot hostname

This slot has string value represents own or peer socket host.

Slot ip-address

This slot has ip-address object of own or peer socket.

Slot port

This slot has integer value of own or peer socket port number.

Function socket-peer socket

Socket must be a socket object.

Returns socket info object or #f. The socket info object contains hostname, IP address and port number. These information is retrieved from getpeername(2).

Function socket-name socket

Socket must be a socket object.

Returns the name string of socket or #f if the socket doesn't have name.

Function socket-node socket

Socket must be a socket object.

Returns the node string of socket. Returns #f for server socket.

Function socket-service socket

Socket must be a socket object.

Returns the service string of socket.

Function socket-info socket

Socket must be a socket object.

Returns socket info object or #f. The socket info object contains hostname, IP address and port number. These information is retrieved from getsockname(2).

Function socket-info-values socket :key ( type `'peer` )

Socket must be a socket object.

Returns 3 values; hostname, IP address and port number. This procedures is for convenience to handle socket info object.

The keyword argument specifies which socket info it should retrieve. If the type is `peer` then it uses `socket-peer`. If it is `info`, then it uses `socket-info`

### IP address operations

Function ip-address->string ip

ip must be an IP address object returned from the second value of `socket-info-values`.

Converts given IP address object to human readable string.

Function ip-address->bytevector ip

ip must be an IP address object returned from the second value of `socket-info-values`.

Converts given IP address object to bytevector.

### Low level APIs

The low level socket APIs are almost compatible with BSD socket.

#### Socket

Function socket-sendto socket bvtevector sockaddr :optional ( flags `0` )

Sends a binary data block to given sockaddr and returns the sent data size.

This procedures is a thin wrapper of POSIX's `sendto (2)`.

Function socket-recvfrom socket sockaddr :optional ( flags `0` )

Receives a binary data block from given sockaddr. If zero length bytevector is returned, it means the peer connection is closed.

This procedures is a thin wrapper of POSIX's `recvfrom (2)`.

Function make-socket ai-family ai-socktype ai-protocol

Creates socket object. The procedure returns #f if it couldn't create a socket. `SO_NOSIGPIPE` socket option is set to the created socket.

This procedure is a thin wrapper of `socket (2)`.

Function socket-connect! socket addrinfo
Function socket-connect! socket addrinfo timeout

Initiate connection on the given socket with given addrinfo addrinfo.

If the second form is used, then argument timeout represents a connection timeout. The value must be a timeout value of `socket-select`.

This procedure is a thin wrapper of `connect (2)`.

Function socket-bind! socket addrinfo

Binds a name to the given socket socket with given addrinfo addrinfo.

This procedure is a thin wrapper of `bind (2)`.

Function socket-listen! socket backlog

Listen for connections on the given socket socket.

This procedure is a thin wrapper of `listen (2)`.

Function socket-setsockopt! socket level name value

Sets socket option on the given socket socket.

level must be an integer and should be one of the followings:

- SOL_SOCKET

- SOL_TCP

- SOL_IP

name must be an integer and should be one of the followings:

- SO_ACCEPTCONN

- SO_BINDTODEVICE

- SO_BROADCAST

- SO_DEBUG

- SO_DONTROUTE

- SO_ERROR

- SO_KEEPALIVE

- SO_LINGER

- SO_OOBINLINE

- SO_PASSCRED

- SO_PEERCRED

- SO_PRIORITY

- SO_RCVBUF

- SO_RCVLOWAT

- SO_RCVTIMEO

- SO_REUSEADDR

- SO_REUSEPORT

- SO_SNDBUF

- SO_SNDLOWAT

- SO_SNDTIMEO

- SO_TIMESTAMP

- SO_TYPE

- TCP_NODELAY

- TCP_MAXSEG

- TCP_CORK

- IP_OPTIONS

- IP_PKTINFO

- IP_RECVTOS

- IP_RECVTTL

- IP_RECVOPTS

- IP_TOS

- IP_TTL

- IP_HDRINCL

- IP_RECVERR

- IP_MTU_DISCOVER

- IP_MTU

- IP_ROUTER_ALERT

- IP_MULTICAST_TTL

- IP_MULTICAST_LOOP

- IP_ADD_MEMBERSHIP

- IP_DROP_MEMBERSHIP

- IP_MULTICAST_IF

The value must be either bytevector or integer.

This procedure is a thin wrapper of `setsockopt (2)`.

Function socket-getsockopt socket level name size

Gets socket option on the given socket socket.

The level and name are the same as `socket-setsockopt!`.

size must be an integer. If the value is positive number, then the returning value is a bytevector whose element count is size and contains the socket option converted to byte array. Otherwise it returns an integer value.

Function socket-nonblocking! socket
Function socket-blocking! socket

Converts given socket to nonblocking socket and blocking socket, respectively.

Function socket-set-read-timeout! socket timeout

Sets read timeout of timeout to the given socket.

The timeout must be either an exact integer represents milliseconds, or a time object.

Function socket-select rfds wfds efds timeout
Function socket-select! rfds wfds efds timeout

Monitor given fdset.

rfds, wfds and efds must be fdset object.

timeout must be #f, integer, time object or pair of integers. If this value is not #f, then the procedure waits only specified amount of time or something interesting happens. Otherwise infinite time or something interesting happens.

This procedure blocks the calling thread, and it can be interrupted by `thread-interrupt!`.

This procedure is a thin wrapper of `select (2)`.

Function socket-read-select timeout sockets ...
Function socket-write-select timeout sockets ...
Function socket-error-select timeout sockets ...

Waits until the given sockets sockets have something interesting. This is the convenient procedure for `socket-select`.

timeout is the same as `socket-select`.

`socket-read-select` can be used to detect if the given sockets have readable data.

`socket-write-select` can be used to detect if the given sockets are still active.

`socket-error-select` can be used to detect if the given sockets are readable data. This procedure might not be so interesting since it can be done by `socket-read-select`.

#### Addrinfo

Function addrinfo? obj

Returns #t if given obj is an addrinfo, otherwise #f.

Function make-addrinfo

Creates empty addrinfo object.

The object has the following slots:

- `family`

- `socktype`

- `flags`

- `protocol`

- `sockaddr`

- `next`

Function make-hint-addrinfo family socktype flags protocol

Creates an addrinfo with given flags. This can be used as hint for `get-addrinfo`.

Function get-addrinfo addrinfo

Gets addrinfo of given hint addrinfo.

When the procedure fails, then `&i/o` is raised.

This procedure is a thin wrapper of `getaddrinfo (3)`.

Function next-addrinfo addrinfo

Retrieves next addrinfo of given addrinfo if availalbe, otherwise returns #f.

Function addrinfo-sockaddr addrinfo

Retrieves `sockaddr` slot of given addrinfo.

The returning value can be used `socket-recvfrom` and `socket-sendto`.

Function sockaddr? obj

Returns #t if given obj is an sockaddr object, otherwise #f.

#### FD sets

Function fdset? obj

Returns #t if given obj is a fdset object, otherwise #f.

Function make-fdset

Creates a empty fdset object.

Function sockets->fdset sockets

Creates a fdset from given socket list sockets.

Function fdset-ref fdset socket

Returns #t if the given socket is set to fdset, otherwise #f.

Function fdset-set! fdset socket flag

Sets/unsets the given socket socket on fdset.

If the flags is #f, then the procedure unsets the socket.

If the flags is #t, then the procedure sets the socket.

Function collect-sockets fdset

Returns a list of socket which are set on fdset.

#### Socket conditions

Above APIs may raise either `&socket` or `&host-not-found`. The first condition is raised when socket related operation failed, for example `socket-send`. The latter condition is raised when `get-addrinfo` is failed.

NOTE: `make-client-socket` and `make-server-socket` may raise `&host-not-found` when the given node or service is not a valid value.

The condition hierarchy is the following:

    &i/o
     + &host-not-found (node service)
     + &socket (socket)
        + &socket-connection
        + &socket-closed
        + &socket-read-timeout
        + &socket-port (port)

Condition Type &host-not-found
Function host-not-found-error? obj
Function make-host-not-found-error node service
Function host-not-found-error-node host-not-found
Function host-not-found-error-service host-not-found

This condition describes the combination of node and _service_does not exist.

Condition Type &socket
Function socket-error? obj
Function make-socket-error socket
Function socket-error-socket socket-error

This condition describes general socket operation error.

Condition Type &socket-connection
Function socket-connection-error? obj
Function make-socket-connection-error socket

This condition describes socket connection error.

Condition Type &socket-closed
Function socket-closed-error? obj
Function make-socket-closed-error socket

This condition describes socket closed error.

Condition Type &socket-read-timeout
Function socket-closed-error? obj
Function make-socket-closed-error socket

This condition describes socket read timeout error.

Condition Type &socket-port
Function socket-port-error? obj
Function make-socket-port-error socket port
Function socket-error-port socket-port-error

This condition describes error of socket port operation. Particularly, when `port-ready` procedure is called on socket port and `select (2)` failed.

NOTE: Read or write failure of socket port raises `&i/o-read` or `&i/o-write` the same as other ports for compatibility.

NOTE2: This condition may be signalled when `get-bytevector-all` is called on socket port since it checks whether or not the given port is ready.

## (sagittarius threads) - Thread

Library (sagittarius threads)

The library provides thread related procedures. The procedures provided this library is based on SRFI-18 Multithreading support and Sagittarius specific procedures.

### Thread APIs

Function thread? obj

[SRFI-18] Returns #t if given obj is a thread, otherwise #f.

Function current-thread

[SRFI-18] Returns the current thread.

Function make-thread thunk :optional name

[SRFI-18] Returns a new thread. The created thread is not executed. To run it, users must explicitly call the `thread-start!` procedure.

The optional argument name gives the thread a name. The name can be retrieved calling `thread-name` procedure. If the argument is not given, then the `make-thread` procedures creates an unique name.

Function thread-name thread

[SRFI-18] Returns the name of thread.

Function thread-state thread

Returns the current state of thread.

Function thread-specific thread

[SRFI-18] Returns the content of the thread's specific slot.

Function thread-specific-set! thread obj

[SRFI-18] Stores obj into the thread's specific slot and returns unspecified value.

Function thread-start! thread

[SRFI-18] Executes the given thread and returns thread

Function thread-yield!

[SRFI-18] The current thread exits the running state if its quantum had expired.

Function thread-sleep! timeout

[SRFI-18] The current thread waits until the timeout is reached.

timeout must be either a time object or an exact integer. The first case, it represents absolute time of the future. The latter case represents second from current time.

Function thread-terminate! thread

[SRFI-18] Causes an abnormal termination of the thread. If the thread is not already terminated, all mutexes owned by the thread become unlocked/abandoned and a "terminated thread exception" object is stored in the thread's end-exception field. If _thread_is the current thread, `thread-terminate!` does not return. Otherwise `thread-terminate!` returns an unspecified value; the termination of the thread will occur before `thread-terminate!` returns.

Function thread-join! thread :optional timeout timeout-val

[SRFI-18] The current thread waits until the thread terminates (normal or not) or until the timeout is reached if timeout is specified. If the timeout is reached, `thread-join!` returns timeout-val if it is supplied, otherwise a "join timeout exception" is raised. If the thread terminated normally, the content of the end-result field is returned, otherwise the content of the end-exception field is raised.

Function thread-suspend! thread :optional timeout timeout-val

Suspends execution of the thread. Users can resume the _thread_by calling `thread-resume!`.

Function thread-resume! thread

Resumes execution of the thread.

If the caller thread is not the one stopped the target thread, then the procedure raises an error.

Function thread-interrupt! thread

Interrupts blocking system call.

This procedure causes `EINTR` and cancels blocking system call such as `select (2)`. Currently the only relevant procedure for this is `socket-select` related procedures. See socket library - Low level APIs.

Currently the procedure uses `SIGALRM` on POSIX environment. This might be changed in future, so do not depend on the signal to interrupt the call from outside of Sagittarius process.

On Windows, the procedure uses combination of `WSAEventSelect` and `WaitForMultipleObjects`. So there is no way to interrupt from outside of Sagittarius process.

### Mutex APIs

Function mutex? obj

[SRFI-18] Returns #t if given obj is a mutex, otherwise #f.

Function make-mutex :optional name

[SRFI-18] Returns a new mutex.

The optional argument name gives the mutex a name. If it's not specified, then the procedure makes an unique name.

Function mutex-name mutex

[SRFI-18] Returns the name of given mutex.

Function mutex-specific mutex

[SRFI-18] Returns the content of specific slot of given mutex.

Function mutex-specific-set! mutex obj

[SRFI-18] Stores the obj to given mutex's specific slot.

Function mutex-state mutex obj

[SRFI-18] Returns the state of given mutex.

Function mutex-lock! mutex :optional timeout thread

[SRFI-18] Locks the given mutex. If the mutex is currently locked, the current thread waits the mutex is unlocked or until the timeout is reached. If timeout is reached, the procedure returns #f.

Function mutex-unlock! mutex :optional cv timeout

[SRFI-18] Unlocks the given mutex. If condition variable _cv_is specified, the current thread is blocked and added to the cv before unlocking mutex, the thread can unblock at any time but no later than when an appropriate call to `condition-variable-signal!` or `condition-variable-broadcast!` is performed, and no later than the timeout, if it's given.

### Condition variable APIs

Function condition-variable? obj

[SRFI-18] Returns #t if given obj is a condition variable, otherwise #f.

Function make-condition-variable :optional name

[SRFI-18] Returns a new condition variable.

The optional argument name gives the condition variable a name. If it's not specified, then the procedure makes an unique name.

Function condition-variable-name cv

[SRFI-18] Returns the name of given cv.

Function condition-variable-specific cv

[SRFI-18] Returns the content of specific slot of given cv.

Function condition-variable-specific-set! cv obj

[SRFI-18] Stores the obj to given cv's specific slot.

Function condition-variable-signal cv

[SRFI-18] If there are thread blocked on cv, the scheduler selects a thread and unblocks it.

Function condition-variable-broadcast! cv

[SRFI-18] Unblocks all the threads blocked on the cv.

### Semaphore APIs

Function semaphore? obj

Returns #t if given obj is a semaphore, otherwise #f.

Function make-semaphore name initial

Creates a new semaphore with initial count initial__name must be either #f or string which represents semaphore name. If the value is #f, then the returning semaphore is memory based semaphore.

initial must be non negative integer.

If there is already the semaphore has the same name, then this procedure returns that semaphore instead of creating new one.

Function open-semaphore name

Opens semaphore which has name.

If there is no such semaphore, then the procedure raises `&i/o-file-does-not-exist`.

Function semaphore-name semaphore

Returns the name of given semaphore.

Function semaphore-wait! semaphore :optional timeout

Locks the semaphore. If the current count of _semaphore_is 0, then the procedure waits.

The optional argument timeout is specified, which it must be #f, integer or time object, then the procedure only waits the given timeout amount. #f means inifinite.

Function semaphore-post! semaphore

Unlock the semaphore. This procedure increase the count of semaphore.

Function semaphore-close! semaphore

Closes the semaphore.

Function semaphore-destroy! semaphore

Removes the semaphore.

NOTE: the `semaphore-close!` and `semaphore-destroy!` behaves the same on Windows.

## (sagittarius timezone) - Timezone

Library (sagittarius timezone)

This library provides timezone related procedures. The timezone database is from IANA - Time Zone Database.

Function timezone? obj

Returns #t if given obj is a timezone object, otherwise #f.

Function timezone name

Retrieves timezone object related to name. The _name_must be a string and proper name of TZID such as `Europe/Amsterdam`. If the given name is not found, then `GMT` is returned as the fallback.

Function timezone-offset tz :optional when

Returns give offset of timezone tz.

If optional argument when is specified, it must be a time object, then the offset is calculated the specified time. Otherwise `current-time`, is used.

This procedure considers daylight saving time (DST). Means, if the timezone has DST, then the return value is depending on the when. For example, `Europe/Amsterdam` has DST so if the when is in DST, then the returning offset is `7200`, otherwise `3600`.

Function timezone-dst? tz :optional (when (current-time))

Returns #t if when is in DST, otherwise #f.

Function timezone-short-name tz :optional (when (current-time))

Returns the short name of given timezone tz.

This procedure considers DST. Means if when is in DST, then short name is DST name, otherwise standard name. For example, timezone `Europe/Amsterdam` has 2 names, `CET` and `CEST`. If the given when is in DST, then `CEST` is returned, otherwise `CET`is returned.

Function timezone-raw-offset tz :optional when

Returns GMT offset of given timezone tz.

If optional argument when is given and must be a time object, then the returning offset is the historical offset. If it's not given, then the procedure reutnrs current timezone offset.

Above procedures also considers when the timezone is started. Means, given timezone has histories, such as when the daylight saving time is starting or ending, when that timezone started, etc. It may return different value according to the when. Following is the example of timezone history:

    (let ((tz (timezone "Europe/Dublin"))
          (now (date->time-utc (make-date 0 0 0 0 24 7 2015 0)))
          ;; 1:00	-	IST	1971 Oct 31  2:00u
          (no-rule-past (date->time-utc (make-date 0 0 0 0 24 7 1971 0)))
          ;; 0:00	GB-Eire	GMT/IST	1968 Oct 27
          (rule-past (date->time-utc (make-date 0 0 0 0 24 7 1968 0))))
      (timezone-short-name tz now)          ;; => "GMT/IST"
      (timezone-short-name tz no-rule-past) ;; => "IST"

      ;; no DST
      (timezone-offset tz no-rule-past)     ;; => 3600

      (timezone-raw-offset tz)              ;; => 0
      (timezone-raw-offset tz no-rule-past) ;; => 3600
      (timezone-raw-offset tz rule-past)    ;; => 0

      (timezone-short-name tz rule-past)    ;; => "GMT/IST"
      )

Function timezone-name tz

Returns TZID of given timezone tz.

Function timezone-name-list

Returns supported TZIDs.

Function zone-offset->timezones offset :optional when

Returns list of timezones whose offsets matched offset.

This procedure considers the time. For example, if the given offset is `3600` which is UTC+1 however if it's summer time, then the returning list doesn't contain some of timezones (e.g. Amsterdam).

The optional argument when specifies the time to consider. If it's not specified, then the returning value of `current-time` is used.

    (zone-offset->timezones 3600) ;; => '(#<timezone Etc/GMT-1> ...)
    ;; offset +15:00 doesn't exist
    (zone-offset->timezones (* 15 3600)) ;; => '()

Function zone-offset->timezones* offset :optional when

Similar with `zone-offset->timezones*`, the difference is this procedure creates an anonymous timezone if there's no registered timezone matching with the given offset.

    (zone-offset->timezones* 3600) ;; => '(#<timezone Etc/GMT-1> ...)
    ;; offset +15:00 doesn't exist
    (zone-offset->timezones* (* 15 3600)) ;; => '(#<timezone +15:00>)

## (sagittarius debug) - Debugging support

Library (sagittarius debug)

This library provides debugging support reader macro.

Reader Macro #?= expr

This reader macro reads the next expression as followings;

    (debug-print _expr_)

`debug-print` is an internal macro of this library which prints the read expression and its result.

Following example shows how to enable this;

    #!read-macro=sagittarius/debug
    #!debug
    (let ((a (+ 1 2)))
      #?=(expt a 2))

    #|
    #?=(expt a 2)
    #?-    9
    |#

`#!debug` enables the debug print.

Function macroexpand expr

Expands given expr. The returning value may or may not be used as proper Scheme expression.

Function macroexpand-1 expr
Function macroexpand-n expr n

Expands given expr n times. The first form's n is 1.

This procedure expands only globally defined macro and the result of expansion is other macro such as next rule of `syntax-rules`. It doesn't consider locally bound macros.

The returning value may or may not be used as proper Scheme expression.

Above 2 procedures are no more than debug aid. Depending on the result of expansion is not guaranteed to work.

#### Remote debugger (experimental feature)

CAVEAT This functionality and interface is subjected to be changed in the future.

When you want to debug a running script, you can use a remote debugger provided this library. Below example shows how to use it.

    (import (rnrs)
            (sagittarius debug))

    ;; Using random port
    (define remote-debugger (make-remote-debugger "0"))
    (print "Debugger port: " (remote-debugger-port remote-debugger))

    ;; Do heavy process or multi threading program which hangs :)

To connect the remote debugger, you can use simpley use `(sagittarius remote-repl)` towards the debugger node and port.

    (import (rnrs)
            (sagittarius remote-repl))
    (connect-remote-repl "localhost" "${port number shown on the console}")

Function remote-debugger? obj

Returns `#t` if the given obj is a remote debugger object.

Function make-remote-debugger ( port `string?` )

Creates a remote debugger. The port must be an available port number, or `"0"` for random port.

Function remote-debugger-terminate! (remote-debugger `remote-debugger?` )

Terminates the given remote-debugger.

Function remote-debugger-port (remote-debugger `remote-debugger?` )

Returns the port number of the given remote-debugger.

The bindings listed below are only available on the remote debugger's REPL.

Function all-threads

Get a list of threads created on Scheme world.

Function sleeping-threads :optional ( timeout 0.01)

Get a list of sleeping threads created on Scheme world.

Ssleeping thread is a thread which can't suspend within the given timeout.

Function thread? obj

[SRFI-18] Returns if the given obj is a thread.

Function thread-name ( thread `thread?` )

[SRFI-18] Returns the name of the given thread.

Function thread-specific ( thread `thread?` )

[SRFI-18] Returns the specific value of the given thread.

Function thread->pretty-backtrace-string ( thread `thread?` )

Returns a human readable string representation of the given thread's backtrace.

Function thread-current-procedure ( thread `thread?` )

Returns the current procedure of the thread.

Function thread-backtrace ( thread `thread?` )

Returns the backtrace of the given thread.

Currently, a backtrace is a list, however it may change in the future, to access the value of backtrace, use the procedures listed below.

NOTE: A backtrace starts with `1`, not zero base.

Function thread-backtrace-type backtrace n

Returns the type of nth backtrace. The value is

`*cproc`

  For C procedure.

`*proc`

  For Scheme procedure.

Function thread-backtrace-procedure backtrace n

Returns the procedure of the nth backtrace.

Function thread-backtrace-source backtrace n

Returns the source, list of file and line number` of the nth backtrace, if available.

Function thread-backtrace-arguments backtrace n

Returns alist of the arguments of the nth backtrace's procedure.

For local variable, the key is `local`. For free variable, the key is `free`.

NOTE: `local` variable may contain more than the argument of the current procedure. This is bacause it also retrieves the available local variable of the current call frame.

Function thread-backtrace-local-variables backtrace n

Returns `local` part of the nth backtrace arguments.

Function thread-backtrace-free-variables backtrace n

Returns `free` part of the nth backtrace arguments.

Function thread-backtrace->pretty-string backtrace

Returns a human readable string representation of the given backtrace.

Function slot-ref obj slot

Returns the slot value of given obj.

Function inspect-object obj

Returns the available slots of the given obj.

Function print arg ...
Function print/ss arg ...

Prints the given args and newline at the end. The first form uses `display` to print, the latter form uses `write/ss`.

Function string-prefix? s1 s2

[SRFI-13] Returns `#t` if the given s1 is the prefix of s2.

Function string-suffix? s1 s2

[SRFI-13] Returns `#t` if the given s1 is the suffix of s2.

## (sagittarius generators) - Generators

Library (sagittarius generators)

This library provides procedures for generator.

A generator is simply a procedure with no arguments that works as a source of a series of values. Every time it is called, it yields a value. Generators may be finite or infinite; a finite generator returns an EOF object to indicate that it is exhausted. For example, read-char is a generator that generates characters from the current input port. Generators provide lightweight laziness.

### Generator constructors

The following procedures creates a generator. Except `null-generator`, all procedures have prefix `'g'`. Arguments named _generator_indicates a generator.

Function null-generator

Returns a generator which always returns EOF object.

Function circular-generator obj obj* ...

Returns a generator which repeats the given _obj_s.

Function giota :optional (count +inf.0) (start 0) (step 1)

Returns a generator which returns count number of numbers. The returning numbers start with start and increased by step.

    (generator->list (giota 5))

(0 1 2 3 4)

    (generator->list (giota 5 10))

(10 11 12 13 14)

    (generator->list (giota 5 10 2))

(10 12 14 16 18)

If count is not given, then the generator is inifinte.

Function grange :optional (start 0) (end +inf.0) (step 1)

Returns a generator which returns numbers in range of start and end. The returning numbers are increased by step.

Function gunfold stop? mapper successor seed :optional (tail-gen #f)

A generator constructor similar to `unfold`.

    (generator->list (gunfold
                          (lambda (s) (> s 5))
                          (lambda (s) (* s 2))
                          (lambda (s) (+ s 1))
                          0))

(0 2 4 6 8 10)

Function list->generator list
Function vector->generator vector
Function reverse-vector->generator vector
Function string->generator string
Function bytevector->generator bytevector

Generator constructors. The returning generator returns the items taken from given argument from the beginning of the given sequence to the end. Except `reverse-vector->generator` which return end to beginning.

Function port->char-generator port
Function port->byte-generator port

Generator constructors. The returning generator returns the items read from the given port. The `port->char-generator` uses `get-char`to read the port. The `port->byte-generator` uses `get-u8`.

Generic ->generator

Generic constructor of generators. By default, the following methods are defined and dispatched above generator constrocturs.

`<list>`, `<vector>`, `<string>`, `<bytevector>` and `<port>`.

If the given argument is type of `<vector>`, then `vector->generator`is used. If the given argument is type of `<port>`, then it checks if it's binary or textual and dispatches apropriate procedure.

### Generator operations

Function gcons* object ... generator

Returns a generator which adds _object_s in front of generator.

Function gappend generator ...

Returns a generator which yields values from the first _generator_and when it's exhausted continues to next.

Function gcombine proc seed generator generators ...

Returns a generator for mapping with state. It yields a sequence of sub-folds over proc.

The proc argument is a procedure which takes as many arguments as the input generators plus one. It is called as `(_proc_ _v1_ _v2_ ... _seed_)`, where v1, v2,`...` are the values yielded from the input generators, and seed is the current seed value. It must return two values, the yielding value and the next seed.

Function gfilter pred generator
Function gremove pred generator

Return generators which yield the items from the source generator, except those on which pred returns false or true respectively.

Function gtake generator k :optional padding
Function gdrop generator k

Return generators which take or drop k items from generator, respectively. Returning generators won't raise errors when it's exhausted before reaching k.

Optional argument padding for `gtake` is passed, then the value is filled until the procedure reaches k.

These procedures are analogues of SRFI-1 `take` and `drop`.

Function gtake-while generator pred
Function gdrop-while generator pred

Return generators which take or drop until procedure pred returns false value respectively.

These procedures are analogues of SRFI-1 `take-while` and `drop-while`.

Function gdelete item generator :optional (= equal?)

Returns a generator which returns items generator returns, except items which are the same as item in sense of =.

Function gdelete-neighbor-dups generator :optional (= equal?)

Returns a generator which returns items generator returns, except items which are the same as the proceeding item in sense of =.

Function gselect value-generator index-generator

Returns a generator which returns the items generated by value-generator of specified by the indice generated by index-generator. The indice must be non negative integer and increased strictly. Otherwise an error is raised.

    (generator->list (gindex (list->generator '(a b c d e f))
                     (list->generator '(0 2 4))))

(a c e)

Function gselect value-generator truth-generator

Returns a generator which returns the items generated by value-generator that correspond to the items generated by truth-generator. If truth-generator returns true value, then the current value of value-generator is returned. Otherwise not.

    (generator->list (gselect (list->generator '(a b c d e f))
                              (list->generator '(#t #f #f #t #t #f))))

(a d e)

Function gconcatenate generator

generator must be an generator generates generators.

Returns a generator which returns the items generated by the generators generated by given generator. It is similar to the following:

    (apply gappend (generator->list generator))

The difference is that this procedure can handle infinite generator.

Function gflatten generator

generator must be a generator which returns lists as its items.

Returns a generator which flatten the items generated by given generator.

    (generator->list (gflatten (list->generator (list '(1 2 3 4)
                                                      '(a b c d)
                                                      '(A B C D)))))

(1 2 3 4 a b c d A B C D)

If the generator returns non list item, then it is ignored.

    (generator->list (gflatten (list->generator (list 'ignored
                                                      '(a b c d)
                                                      'ignored
                                                      '(A B C D)))))

(a b c d A B C D)

This behaviour is an error behaviour so it might be changed in future. So users should not depend on this.

Function gmerge compare generator1 generator2 ...

compare must be a procedure which accepts 2 arguments and returns boolean value. The procedure should compare the given 2 arguments and return true value if the first argument is smaller than the second argument.

Returns a generator which returns the ordered items determined by _compare_procedure. If the `gmerge` procedure is called only one argument, then it simply returns a generator (if generator1 isn't a generator then it is coerced).

    (generator->list (gmerge < (list->generator '(1 4 5)) (list->generator '(0 2 3))))

(0 1 2 3 4 5)

Function gmap proc generator1 generator2 ...

Returns a generator which returns the items returned by `proc`.

The `proc` is called with the items returned by generator1 and generator2 if it's given.

The gmap procedure accepts uneven length of generators however one of the generator must be finite length, otherwise it won't be exhausted.

It is an analogy of `map`.

Function gfilter-map proc generator1 generator2 ...

Returns a generator which returns the items returnd by `proc`.

This procedure is similar with `gmap`. The difference is that the returning item is filtered if the returning value of proc is #f.

It is an analogy of `filter-map`.

Function generate proc

Returns a coroutine generator which return the item returned by proc.

The given argument proc must accept one argument, yield which is a procedure accepts variable arguments. The proc procedure can return values via yield procedure.

    (define g
      (make-coroutine-generator
        (lambda (yield)
          (let loop ((i 0))
            (when (< i 3)
              (yield i)
              (loop (+ i 1)))))))

    (generator->list g)

(0 1 2)

Macro glet* (bindings ... ) body1 body2 ...

`glet*` is a macro which is similar to `let*`. The difference is that `glet*` check if the bindings are EOF object or not and if it detects EOF object, then it returns EOF object immediately.

bindings must be one of the following forms:

- `(_var_ _gen-expr_)`

- `( _gen-expr_ )`

If the first form is used, then the gen-expr is bound to var. Otherwise the `glet*` just check if the value is EOF or not.

    (define g (list->generator '(1 2 3)))

    (list
      (glet* ((a (g))) a)
      (glet* ((a (g))) (define b 2) (+ a b))
      (glet* ((a (g)) (b (g))) (+ a b)))

(1 2 #\<eof>)

Macro glet1 var expr body1 body2 ...

Convenient macro for only one binding of `glet*`. This is defined like the following:

    (define-syntax glet1
      (syntax-rules ()
        ((_ var expr body body1 ...)
         (glet* ((var expr)) body body1 ...))))

Macro do-generator (var gen-expr) body ...

Iterates generator of then given gen-expr.

## Cryptographic libraries

Sagittarius provides a comprehensive set of cryptographic libraries. Currently the libraries support below:

- Block cipher

- Asymmetric cipher

- Cryptographic hash functions

- Cryptographically secure pseudo random number generators (CSPRNG)

- Signature generation / verification

- Key generate, agreement and import/export

- MAC

- X.509 CSR, CRL and certificate

- PKCS#5 via PBKDF

- PKCS#8

- PKCS#12 keystore

- PEM

- Various KDFs

Not like legacy `(crypto)` and `(math)` libraries, these libraries are split per components. Users need to combine some libraries to achieve their goals.

### Examples

This section shows some basic examples how to use the crypto graphic libraries.

#### Block cipher

This example encrypts and decrypts a plain text with a radomly generated secret key. The encryption scheme is AES-256 and encryption mode is CTR.

    (import (rnrs)
            (sagittarius crypto ciphers)
            (sagittarius crypto keys))

    ;; Randomly generates AES-256 secret key.
    (define key (generate-symmetric-key *scheme:aes-256*))

    ;; Initial Vector (use randomly generated one in production code)
    (define iv
     (make-bytevector (block-cipher-descriptor-block-length *scheme:aes-256*) 1))

    ;; AES-256 cipher with CTR mode, without padding
    (define aes-cipher
     (make-block-cipher *scheme:aes-256* *mode:ctr* no-padding))

    ;; Cipher parameter.
    ;; NOTE, IV will be copied so modifying original IV doesn't affect the result
    (define parameter
      (make-cipher-parameter
       (make-iv-parameter iv)
       (make-counter-mode-parameter *ctr-mode:big-endian*)))

    (define (encrypt cipher key parameter plain-text)
      (block-cipher-init! cipher (cipher-direction encrypt) key parameter)
      (let ((cipher-text (block-cipher-encrypt-last-block cipher plain-text)))
        (block-cipher-done! cipher)
        cipher-text))

    (define (decrypt cipher key parameter cipher-text)
      (block-cipher-init! cipher (cipher-direction decrypt) key parameter)
      (let ((plain-text (block-cipher-decrypt-last-block cipher cipher-text)))
        (block-cipher-done! cipher)
        plain-text))

    (define plain-text (string->utf8 "Hello Sagittarius Scheme!"))
    (decrypt aes-cipher key parameter (encrypt aes-cipher key parameter plain-text))
    ;; -> A bytevector of UTF-8 representation of `plain-text`

This example shows how to use a string password as a key (Password-Based Encryption Scheme, a.k.a. PBES). PBES is just a block cipher using a derived key. To do so, you need to use KDF, Key Derivation Function.

    (import (rnrs)
            (sagittarius crypto ciphers)
            (sagittarius crypto keys)
            (sagittarius crypto kdfs)    ;; for PBKDF2
            (sagittarius crypto digests) ;; for digests, e.g. SHA-256
            (sagittarius crypto mac))    ;; for MAC, NOTE: PRF = MAC

    ;; If everyone uses this kind of password, then it'd be almost impossibe
    ;; to crack :)
    (define password "You can't guess this password! It's so strong!! :D")

    ;; PRF
    (define prf (mac->prf-provider *mac:hmac* :digest *digest:sha-256*))

    (define (derive-key scheme password)
      ;; I'm not sure if this is a bad practice or not, but for simplicity
      ;; we use hashed password as a salt
      (define md (make-message-digest *digest:sha-256*))
      (define bv (string->utf8 password))
      (define salt (digest-message md bv))
      ;; 310,000 iteration, required by FIPS-140
      (pbkdf-2 bv salt 310000
        (block-cipher-descriptor-suggested-key-length scheme)
    	:prf prf))

    (define key
     (generate-symmetric-key *scheme:aes-256*
      (derive-key *scheme:aes-256* password)))

    ;; The rest can be the same as above CTR mode example.

This example shows how to handle `offline` encryption mode.

    (import (rnrs)
            (sagittarius crypto ciphers)
            (sagittarius crypto keys))

    (define key (generate-symmetric-key *scheme:aes-256*))
    ;; GCM-SIV nonce size = 12
    (define iv (make-bytevector 12))

    ;; AES-256-GCM-SIV
    (define aes-cipher
      (make-block-cipher *scheme:aes-256* *mode:gcm-siv* no-padding))

    (define parameter
      (make-cipher-parameter
       (make-iv-parameter iv)
       ;; empyt AAD :)
       (make-aad-parameter #vu8())))

    (define (encrypt-messages . messages)
      (for-each (lambda (message)
                  ;; output space is not needed, and this procedure returns 0
                  (block-cipher-encrypt! aes-cipher message 0 #vu8() 0)) messages)
      (let* ((out-size (block-cipher-last-block-size aes-cipher 0))
             (out (make-bytevector out-size)))
        ;; passing dummy block
        (block-cipher-encrypt-last-block! aes-cipher #vu8() 0 out 0)
        (values out (block-cipher-done/tag aes-cipher))))

    (block-cipher-init! aes-cipher (cipher-direction encrypt) key parameter)
    (let-values (((enc tag) (encrypt-messages (string->utf8 "Hello, GCM-SIV") (string->utf8 "\nI'm done"))))
      (block-cipher-init! aes-cipher (cipher-direction decrypt) key (make-cipher-parameter parameter (make-tag-parameter tag)))
      (let* ((size (block-cipher-last-block-size aes-cipher enc))
             (msg (make-bytevector size)))
        (block-cipher-decrypt-last-block! aes-cipher enc 0 msg 0)
        (block-cipher-done/tag! aes-cipher tag)
        (utf8->string msg)))
    ;; "Hello, GCM-SIV\nI'm done"

#### Stream cipher

This example encrypts and decrypts a plain text with a randomly generated secret key. The encryption scheme is ChaCha20 Poly1305.

    (import (rnrs)
            (sagittarius crypto ciphers)
            (sagittarius crypto keys))

    ;; Randomly generates AES-256 secret key.
    (define key (generate-symmetric-key *scheme:aes-256*))

#### Asymmetric cipher

This example encrypts and decrypts a plain text with a randomly generated RSA key pair.

    (import (rnrs)
            (sagittarius crypto ciphers)
            (sagittarius crypto keys)
            (sagittarius crypto digests))

    ;; Randomly genrates RSA key pair. Default 2048 bits
    (define key-pair (generate-key-pair *key:rsa*))

    ;; Making RSA cipher with OAEP encoding (default) with SHA-256
    (define rsa-cipher
     (make-asymmetric-cipher *scheme:rsa* :digest *digest:sha-256*))

    ;; Encryption can only be done by a public key
    (define (encrypt cipher key plain-text)
      (asymmetric-cipher-init! cipher key)
      (let ((cipher-text (asymmetric-cipher-encrypt-bytevector cipher plain-text)))
        (asymmetric-cipher-done! cipher)
        cipher-text))

    ;; Decryption can only be done by a private key
    (define (decrypt cipher key cipher-text)
      (asymmetric-cipher-init! cipher key)
      (let ((plain-text (asymmetric-cipher-decrypt-bytevector cipher cipher-text)))
        (asymmetric-cipher-done! cipher)
        plain-text))

    (define message (string->utf8 "Hello Sagittarius Scheme"))
    (decrypt rsa-cipher (key-pair-private key-pair)
      (encrypt rsa-cipher (key-pair-public key-pair) message))
    ;; -> A bytevector of UTF-8 representation of `plain-text`

#### Cryptographic hash function

In the libraries, hash is called digest. So, from now on we use digest instead of hash.

Below example shows how to generate a digest of SHA-256.

    (import (rnrs)
            (sagittarius crypto digests))

    (define md (make-message-digest *digest:sha-256*))

    (digest-message md (string->utf8 "Hello Sagittarius Scheme"))
    ;; -> #vu8(65 109 154 253 119 192 195 187 255 90 75 208 135 51 25 43 106 121 236 172 96 233 38 189 154 240 32 8 116 58 169 237)

Also below example shows how to generate a digest of SHAKE-256, which generates a variable length digest.

    (import (rnrs)
            (sagittarius crypto digests))

    (define md (make-message-digest *digest:shake-256*))

    ;; Generates 32 bytes digests
    (digest-message md (string->utf8 "Hello Sagittarius Scheme") 32)
    ;; -> #vu8(127 141 98 85 40 216 103 129 10 71 136 179 158 103 163 218 109 65 244 77 119 4 109 54 135 126 225 162 188 58 16 64)

#### Cryptographically secure pseudo random number generators (CSPRNG)

Below example shows how to generate a random integer.

    (import (rnrs)
            (sagittarius crypto random))

    ;; Pseudo random generator, it returns the same value each execution
    (define prng (pseudo-random-generator *prng:chacha20*))
    ;; Secure random generator, it returns random value each execution
    ;; (define prng (secure-random-generator *prng:chacha20*))

    ;; range of 0 <= r < 100
    (random-generator-random-integer prng 100)
    ;; -> each time the same result as it's pseudo random, not secure random

## Key library - (sagittarius crypto keys)

The key library provides key operations for both symmetric and asymmetric keys.

Library (sagittarius crypto keys)

The key library, this library exports the procedures listed below sections.

### Key type

Sagittarius crypto library uses hierachial key structure. The hierarchy of the key type is below.

                     +--------------+
                     | <crypto-key> |
                     +------+-------+
                            |
             +--------------+-------------+
             |                            |
    +--------+--------+          +--------+---------+
    | <symmetric-key> |          | <asymmetric-key> |
    +-----------------+          +--------+---------+
                                          |
                                 +--------+--------+
                                 |                 |
                         +-------+------+  +-------+------+
                         | <public-key> |  | <private-key |
                         +--------------+  +--------------+

Function crypto-key? obj

Returns `#t` if the given obj is an instance of `<crypto-key>`, otherwise `#f`.

Function symmetric-key? obj

Returns `#t` if the given obj is an instance of `<symmetric-key>`, otherwise `#f`.

Function asymmetric-key? obj

Returns `#t` if the given obj is an instance of `<asymmetric-key>`, otherwise `#f`.

Function public-key? obj

Returns `#t` if the given obj is an instance of `<public-key>`, otherwise `#f`.

Function private-key? obj

Returns `#t` if the given obj is an instance of `<private-key>`, otherwise `#f`.

### Symmetric key operations

Function make-symmetric-key ( bv `bytevector?` )

Creates a symmetric key of the value of bv.
The key can be used for any of the symmetric ciphers supported by Sagittarius, however it is users' responsibility to align the key size. If you want to make sure the bv has the right key size, consier using `generate-symmetric-key` method.

Function symmetric-key-value ( key `symmetric-key?` )

Retrieves the raw key value of the given key.

Method generate-symmetric-key `<block-cipher-descriptor>`
Method generate-symmetric-key `<block-cipher-descriptor>` `<random-generator>`

Generates a symmetric key suitable for the given block cipher scheme, randomly.

Method generate-symmetric-key `<block-cipher-descriptor>` `<bytevector>`

Creates a symmetric from the bytevector, this method checks the key size if it's appropriate for the given cipher or not.

Function make-rfc3394-key-wrap ( scheme `block-cipher-descriptor?` ) ( key `symmetric-key?` ) :key iv

Creates a key wrap procedure using given scheme and key. The optional keyword parameter iv is used as an initial vector if provided.

Function make-aes-key-wrap ( key `symmetric-key?` ) opts ...

Creates an AES key wrap procedure.

Function make-camellia-key-wrap ( key `symmetric-key?` ) opts ...

Creates an Camellia key wrap procedure.

Function make-rfc3394-key-unwrap ( scheme `block-cipher-descriptor?` ) ( key `symmetric-key?` ) :key iv

Creates a key unwrap procedure using given scheme and key. The optional keyword parameter iv is used as an initial vector if provided.

Function make-aes-key-unwrap ( key `symmetric-key?` ) opts ...

Creates an AES key unwrap procedure.

Function make-camellia-key-unwrap ( key `symmetric-key?` ) opts ...

Creates an Camellia key unwrap procedure.

### Asymmetric key operations

Function key-pair? obj

Returns `#t` if the given obj is a key pair, otherwise `#f`.

Function key-pair-private ( kp `key-pair?` )

Returns the private key of the given kp.

Function key-pair-public

Returns the public key of the given kp.

Method generate-key-pair scheme opts ...

Generates a key pair of the given scheme. Followings are the supported schemes:

Key scheme *key:rsa
Key scheme *key:dsa
Key scheme *key:ecdsa
Key scheme *key:ed25519
Key scheme *key:ed448
Key scheme *key:x25519
Key scheme *key:x448

Those are RSA, DSA, ECDSA, Ed5519, Ed448, X25519 and X448 respectively.
For convenience `*scheme:rsa` has the same effect as `*key:rsa`.

Function generate-public-key scheme opts ...
Function generate-private-key scheme opts ...
Macro public-key-format format

A macro returns a symbol representation of format. The format must be either `raw` or `subject-public-key-info`.

`raw`: Imports/exports raw public key. `subject-public-key-info`: Imports/exports subject public key info.

Enum set *public-key-formats*

Enum set of the `public-key-format`.

Function public-key-format? obj

Returns `#t` if the given obj is a member of `public-key-format` enum.

Method import-public-key `<bytevector>` `'subject-public-key-info`
Method import-public-key `<port>` `'subject-public-key-info`

Imports a public from the given `<bytevector>` or `<port>` which must be a valid subject public key info.
The returning public key type is detected via the OID inside of the subject public key info.

Method import-public-key `*key:rsa*` `<bytevector>` :optional format
Method import-public-key `*key:rsa*` `<port>` :optional format

Imports RSA key from given `<bytevector>` or `<port>`. The optional format specifies the format of the given key. Default value is `raw`.

Method export-public-key `<rsa-public-key>` :optional format
Method export-public-key `*key:rsa*` `<rsa-public-key>` :optional format

Exports RSA key from the given `<rsa-public-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

Method import-public-key `*key:dsa*` `<bytevector>` :optional format parameter
Method import-public-key `*key:dsa*` `<port>` :optional format parameter

Imports DSA key from given `<bytevector>` or `<port>`. The optional format specifies the format of the given key. Default value is `subject-public-key-info`.

If `raw` is specified, then optional argument parameter must be specified and it must be `<dsa-key-parameter>`

Method export-public-key `<dsa-public-key>` :optional format
Method export-public-key `*key:dsa*` `<dsa-public-key>` :optional format

Exports DSA key from the given `<dsa-public-key>`. The optional format controls the format of the exporting key. Default value is `subject-public-key-info`.

Method import-public-key `*key:ecdsa*` `<bytevector>` :optional format ec-parameter
Method import-public-key `*key:ecdsa*` `<port>` :optional format ec-parameter

Imports ECDSA key from given `<bytevector>` or `<port>`. The optional format specifies the format of the given key. Default value is `subject-public-key-info`.
If `raw` format is specified, then optional parameter `ec-parameter` must be specified. Below are the supported EC parameters.

EC parameter *ec-parameter:p192*
EC parameter *ec-parameter:p224*
EC parameter *ec-parameter:p256*
EC parameter *ec-parameter:p384*
EC parameter *ec-parameter:p521*
EC parameter *ec-parameter:k163*
EC parameter *ec-parameter:k233*
EC parameter *ec-parameter:k283*
EC parameter *ec-parameter:k409*
EC parameter *ec-parameter:k571*
EC parameter *ec-parameter:b163*
EC parameter *ec-parameter:b233*
EC parameter *ec-parameter:b283*
EC parameter *ec-parameter:b409*
EC parameter *ec-parameter:b571*
EC parameter *ec-parameter:secp160r1* 0.9.12
EC parameter *ec-parameter:secp160k1* 0.9.12
EC parameter *ec-parameter:secp160r2* 0.9.12
EC parameter *ec-parameter:secp192r1*
EC parameter *ec-parameter:secp224r1*
EC parameter *ec-parameter:secp256r1*
EC parameter *ec-parameter:secp384r1*
EC parameter *ec-parameter:secp521r1*
EC parameter *ec-parameter:sect163k1*
EC parameter *ec-parameter:sect233k1*
EC parameter *ec-parameter:sect283k1*
EC parameter *ec-parameter:sect409k1*
EC parameter *ec-parameter:sect571k1*
EC parameter *ec-parameter:sect163r2*
EC parameter *ec-parameter:sect233r1*
EC parameter *ec-parameter:sect283r1*
EC parameter *ec-parameter:sect409r1*
EC parameter *ec-parameter:sect571r1*
EC parameter *ec-parameter:secp192k1*
EC parameter *ec-parameter:secp224k1*
EC parameter *ec-parameter:secp256k1*
EC parameter *ec-parameter:sect163r1*
EC parameter *ec-parameter:sect239k1*
EC parameter *ec-parameter:sect113r1*
EC parameter *ec-parameter:brainpool-p160r1*
EC parameter *ec-parameter:brainpool-p160t1*
EC parameter *ec-parameter:brainpool-p192r1*
EC parameter *ec-parameter:brainpool-p192t1*
EC parameter *ec-parameter:brainpool-p224r1*
EC parameter *ec-parameter:brainpool-p224t1*
EC parameter *ec-parameter:brainpool-p256r1*
EC parameter *ec-parameter:brainpool-p256t1*
EC parameter *ec-parameter:brainpool-p320r1*
EC parameter *ec-parameter:brainpool-p320t1*
EC parameter *ec-parameter:brainpool-p384r1*
EC parameter *ec-parameter:brainpool-p384t1*
EC parameter *ec-parameter:brainpool-p512r1*
EC parameter *ec-parameter:brainpool-p512t1*

After `ec-parameter:` represents the parameter name.

Method export-public-key `<ecdsa-public-key>` :optional format
Method export-public-key `*key:ecdsa*` `<ecdsa-public-key>` :optional format

Exports ECDSA key from the given `<ecdsa-public-key>`. The optional format controls the format of the exporting key. Default value is `subject-public-key-info`.

Method import-public-key `*key:ed25519*` `<bytevector>` :optional format
Method import-public-key `*key:ed25519*` `<port>` :optional format
Method import-public-key `*key:ed448*` `<bytevector>` :optional format
Method import-public-key `*key:ed448*` `<port>` :optional format

Imports Ed25519 or Ed448 public key from the given `<bytevector>` or `<port>`. The optional format controls the key format, default is `raw`.

Method export-public-key `<eddsa-public-key>` :optional format
Method export-public-key `*key:ed25519*` `<eddsa-public-key>` :optional format
Method export-public-key `<eddsa-public-key>` :optional format
Method export-public-key `*key:ed448*` `<eddsa-public-key>` :optional format

Exports Ed25519 or Ed448 key from the given `<eddsa-public-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

If the first form is used, then the method automatically detects the key type.

Method import-public-key `*key:x25519*` `<bytevector>` :optional format
Method import-public-key `*key:x25519*` `<port>` :optional format
Method import-public-key `*key:x448*` `<bytevector>` :optional format
Method import-public-key `*key:x448*` `<port>` :optional format

Imports X25519 or X448 public key from the given `<bytevector>` or `<port>`. The optional format controls the key format, default is `raw`.

Method export-public-key `<rfc7748-public-key>` :optional format
Method export-public-key `*key:x25519*` `<rfc7748-public-key>` :optional format
Method export-public-key `<rfc7748-public-key>` :optional format
Method export-public-key `*key:x448*` `<rfc7748-public-key>` :optional format

Exports X25519 or X448 key from the given `<rfc7748-public-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

If the first form is used, then the method automatically detects the key type.

Macro private-key-format format

A macro returns a symbol representation of format. The format must be either `raw` or `private-key-info`.

`raw`: Imports/exports raw public key. `private-key-info`: Imports/exports private key info or one asymmetric key.

Enum set *private-key-formats*

Enum set of the `private-key-format`.

Function private-key-format? obj

Returns `#t` if the given obj is a member of `private-key-format` enum.

Method import-private-key `<bytevector>` `'private-key-info`
Method import-private-key `<port>` `'private-key-info`

Imports a private key from the `<bytevector>` or `<port>` which must be a valid private key info or one asymmetric key.
The returning private key type is detected by the OID inside of the private key info.

Method import-private-key `*key:rsa` `<bytevector>`
Method import-private-key `*key:rsa` `<port>`

Imports a RSA private key from the `<bytevector>` or `<port>`. The format of the input must be a raw RSAPrivateKey.

Method export-private-key `<rsa-crt-private-key>` :optional format
Method export-private-key `*key:rsa*` `<rsa-crt-private-key>` :optional format

Exporting RSA private key is only supported with CRT key.
Exports the given `<rsa-crt-private-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

Method import-private-key `*key:dsa` `<bytevector>`
Method import-private-key `*key:dsa` `<port>`

Imports a DSA private key from the `<bytevector>` or `<port>`. The format of the input must be a raw DSAPrivateKey.

Method export-private-key `<dsa-private-key>` :optional format
Method export-private-key `*key:dsa*` `<dsa-private-key>` :optional format

Exports the given `<dsa-private-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

Method import-private-key `*key:ecdsa` `<bytevector>` :optional ec-parameter
Method import-private-key `*key:ecdsa` `<port>` :optional ec-parameter

Imports a ECDSA private key from the `<bytevector>` or `<port>`. The format of the input must be a raw ECPrivateKey.
If the given raw key doesn't contain EC parameter, then the optional ec-parameter must be provided.

Method export-private-key `<ecdsa-private-key>` :optional format
Method export-private-key `*key:ecdsa*` `<ecdsa-private-key>` :optional format

Exports the given `<ecdsa-private-key>`. The optional format controls the format of the exporting key. Default value is `raw`.

Method import-private-key `*key:ed25519` `<bytevector>`
Method import-private-key `*key:ed25519` `<port>`
Method import-private-key `*key:ed448` `<bytevector>`
Method import-private-key `*key:ed448` `<port>`

Imports a Ed25519 or Ed448 private key from the `<bytevector>` or `<port>`.

Method export-private-key `<eddsa-private-key>` :optional format
Method export-private-key `*key:ed25519*` `<eddsa-private-key>` :optional format
Method export-private-key `*key:ed448*` `<eddsa-private-key>` :optional format

Exports the given `<eddsa-private-key>`. The optional format controls the format of the exporting key. Default value is `raw`.
If the first form is used, then the exporting key type is detected from the given key.

Method calculate-key-agreement `*key:ecdh*` `<ecdsa-private-key>` `<ecdsa-public-key>`
Method calculate-key-agreement `*key:x25519*` `<rfc7748-private-key>` `<rfc7748-public-key>`
Method calculate-key-agreement `*key:x449*` `<rfc7748-private-key>` `<rfc7748-public-key>`

Calculate a secret key from the given private key and public key.

Function oid->key-operation
Function key->oid

## Cipher library - (sagittarius crypto ciphers)

The cipher library provides both symmetric and asymmetric cipher operations.

Library (sagittarius crypto ciphers)

The cipher library, this library exports the procedures listed below sections.

### Ciphers parameters

Cipher parameters are parameters to pass to the cipher, such as Initial Vector (IV).

All the parameter value retriever accept optional argument. If it's provided and the parameter is not or does not contain the target parameter, then the default value is returned, otherwise `&assertion` is signalled.

NOTE: The cipher parameters are only used on symmetric ciphers. Asymmetric ciphers use keywords.

Function cipher-parameter? obj

Returns `#t` if the given obj is a cipher parameter, otherwise `#f`.

A cipher parameter can be a simple parameter or composite parameter like the condition system.

Function make-cipher-parameter parameter ...

Creates a composite cipher parameter whose contents are given parameters.

Function round-parameter? obj

Returns `#t` if the given obj is a round cipher parameter, otherwise `#f`.

This parameter is used all the modes.

Function make-round-parameter ( round `integer?` )

Creates a round cipher parameter with the given round.

Function cipher-parameter-rounds ( parameter `cipher-parameter?` ) :optional default

Retrieves the `round` field of the given parameter.

Function iv-parameter? obj

Returns `#t` if the given obj is a iv cipher parameter, otherwise `#f`.

This parameter is used by CBC, CFB, OFB, CTR, LRW F8 and GCM, and all of the modes require it.

Function make-iv-parameter ( iv `bytevector?` )

Creates a IV cipher parameter with the given iv. The iv is copied during the creation so modifying the original value does not affect the parameter.

Function cipher-parameter-iv ( parameter `cipher-parameter?` ) :optional default

Retrieves the `iv` field of the given parameter.

Function counter-mode-parameter? obj

Returns `#t` if the given obj is a counter mode cipher parameter, otherwise `#f`.

This parameter is used by CTR mode and if it's not provided, then `*ctr-mode:big-endian*` is used.

Function make-counter-mode-parameter mode

Creates a counter mode parameter with the given mode. The mode must be one of the following:

Function *ctr-mode:little-endian*
Function *ctr-mode:big-endian*
Function *ctr-mode:rfc3686

These modes are little-endian, big-endian, and IPSec ESP described RFC 3686, respectively.

Function cipher-parameter-counter-mode ( parameter `cipher-parameter?` ) :optional default

Retrieves the `counter-mode` field of the given parameter.

Function tweak-parameter? obj

Returns `#t` if the given obj is a tweak cipher parameter, otherwise `#f`.

This parameter is used by LRW mode, and it's a required parameter.

Function make-tweak-parameter ( tweak `bytevector?` )

Creates a tweak cipher parameter with the given tweak. The tweak is copied during the creation so modifying the original value does not affect the parameter.

Function cipher-parameter-tweak ( parameter `cipher-parameter?` ) :optional default

Retrieves the `tweak` field of the given parameter.

Function salt-parameter? obj

Returns `#t` if the given obj is a salt cipher parameter, otherwise `#f`.

This parameter is used by F8 mode, and it's a required parameter.

Function make-salt-parameter ( salt `bytevector?` )

Creates a salt cipher parameter with the given salt. The salt is copied during the creation so modifying the original value does not affect the parameter.

Function cipher-parameter-salt ( parameter `cipher-parameter?` ) :optional default

Retrieves the `salt` field of the given parameter.

Function nonce-parameter? obj

Returns `#t` if the given obj is a nonce cipher parameter, otherwise `#f`.

This parameter is used by EAX, OCB and OCB3. EAX doesn't require it, others require it.

Function make-nonce-parameter ( nonce `bytevector?` )

Creates a nonce cipher parameter with the given nonce. The nonce is copied during the creation so modifying the original value does not affect the parameter.

Function cipher-parameter-nonce ( parameter `cipher-parameter?` ) :optional default

Retrieves the `nonce` field of the given parameter.

Function aad-parameter? obj

Returns `#t` if the given obj is a aad cipher parameter, otherwise `#f`.

This parameter is used by EAX and GCM. It's an optional parameter.

Function make-aad-parameter ( aad `bytevector?` )

Creates a aad cipher parameter with the given aad. The aad is copied during the creation so modifying the original value does not affect the parameter.

Function cipher-parameter-aad ( parameter `cipher-parameter?` ) :optional default

Retrieves the `aad` field of the given parameter.

Function tag-length-parameter? obj

Returns `#t` if the given obj is a tag length cipher parameter, otherwise `#f`.

This parameter is used by OCB3 and it's a required parameter.

Function make-tag-length-parameter ( tag-length `integer?` )

Creates a tag length cipher parameter with the given tag-length.

Function cipher-parameter-tag-length ( parameter `cipher-parameter?` ) :optional default

Retrieves the `tag-length` field of the given parameter.

Function tag-parameter? obj

Returns `#t` if the given obj is a tag length cipher parameter, otherwise `#f`.

This parameter is used by CCM and GCM-SIV (on decryption), and it's a required parameter.

Function make-tag-parameter ( tag `integer?` )

Creates a tag length cipher parameter with the given tag.

Function cipher-parameter-tag ( parameter `cipher-parameter?` ) :optional default

Retrieves the `tag` field of the given parameter.

### Ciphers

Function cipher-descriptor? obj

Returns `#t` if the given obj is a cipher descriptor, otherwise `#f`.

A cipher descriptor is an object which holds encryption scheme information, such as algorithm, key length, etc.
This object itself doesn't provide any cipher operations, to execute them, users need to create a cipher object.

Function cipher-descriptor-name ( descriptor `cipher-descriptor?` )

Returns the name of the given descriptor.

Function cipher? obj

Returns `#t` if the given obj is a cipher object, otherwise `#f`.

A cipher object is an actual working object to operate cipher operation.
A cipher may holds operation state, and it is users' responsibility to make sure not to mix up the state.

Macro cipher-direction direction

A macro returns a symbol representation of direction. The direction must be either `encrypt` or `decrypt`.

### Symmetric ciphers

Symmetric cipher can be either block cipher or stream cipher.

Function symmetric-cipher-descriptor? obj

Returns `#t` if the given obj is a symmetric cipher descriptor, otherwise `#f`.

Function symmetric-cipher-descriptor-min-key-length ( descriptor `symmetric-cipher-descriptor?` )

Returns minimum key length of the given descriptor's algorithm.

Function symmetric-cipher-descriptor-max-key-length ( descriptor `symmetric-cipher-descriptor?` )

Returns maximum key length of the given descriptor's algorithm.

Function symmetric-cipher? obj

Returns `#t` if the given obj is a symmetric cipher object, otherwise `#f`.

#### [§5] Block ciphers

Function block-cipher-descriptor? obj

Returns `#t` if the given obj is a block cipher descriptor, otherwise `#f`.

Currently, below encryption algorithms are supported:

Block cipher descriptor *scheme:aes*
Block cipher descriptor *scheme:aes-128*
Block cipher descriptor *scheme:aes-192*
Block cipher descriptor *scheme:aes-256*
Block cipher descriptor *scheme:blowfish*
Block cipher descriptor *scheme:camellia*
Block cipher descriptor *scheme:cast-128*
Block cipher descriptor *scheme:cast5*
Block cipher descriptor *scheme:des*
Block cipher descriptor *scheme:des3*
Block cipher descriptor *scheme:desede*
Block cipher descriptor *scheme:kasumi*
Block cipher descriptor *scheme:khazad*
Block cipher descriptor *scheme:noekeon*
Block cipher descriptor *scheme:rc2*
Block cipher descriptor *scheme:rc5*
Block cipher descriptor *scheme:rc6*
Block cipher descriptor *scheme:safer+*
Block cipher descriptor *scheme:safer-k128*
Block cipher descriptor *scheme:safer-k64*
Block cipher descriptor *scheme:safer-sk128*
Block cipher descriptor *scheme:safer-sk64*
Block cipher descriptor *scheme:seed*
Block cipher descriptor *scheme:skipjack*
Block cipher descriptor *scheme:twofish*
Block cipher descriptor *scheme:x-tea*

Some of the algorithms are considered as broken cipher, such as DES.
It is users' responsibility to use those ciphers.

NOTE: NIST recommends to use AES.

Function block-cipher-descriptor-block-length ( descriptor `block-cipher-descriptor?` )

Returns block size of the given descriptor's algorithm.

Function block-cipher-descriptor-suggested-key-length ( descriptor `block-cipher-descriptor?` ) :optional size

Returns suggested key length of the given descriptor's algorithm.

Most of the time, this returns the result of the `symmetric-cipher-descriptor-max-key-length` procedure.

If the optional argument size is provided, then it check the size is valid length of the key length.

Function mode-descriptor? obj

Returns `#t` if the given obj is a mode descriptor, otherwise `#f`.

Currently, below encryption modes are supported.

Mode descriptor *mode:ecb*
Mode descriptor *mode:cbc*
Mode descriptor *mode:cfb*
Mode descriptor *mode:ofb*
Mode descriptor *mode:ctr*
Mode descriptor *mode:lrw*
Mode descriptor *mode:f8*

Mode descriptors for ECB, CBC, CFB, OFB, CTR, LRW and F8 respectively.

Mode descriptor *mode:eax*
Mode descriptor *mode:ocb*
Mode descriptor *mode:ocb3*
Mode descriptor *mode:gcm*
Mode descriptor *mode:gcm-siv* 0.9.12
Mode descriptor *mode:ccm* 0.9.12

Mode descriptor for EAX, OCB, OCB3, GCM, GCM-SIV and CCM respectively. These are authenticated encryption with assiciated data (AEAD) modes.

GCM-SIV and CCM are `offline` mode, which means it requires to know all the input ahead. So, cipher encryption or decryption procedures don't return encrypted or decrypted values. Only the last block handling will do. This also implies that the last block handling may require output space more than input block size. To know the required space, use `block-cipher-last-block-size` procedure. See the example for the detail usage.

Function mode-descriptor-name ( descriptor `mode-descriptor?` )

Returns the name of the given descriptor.

Function block-cipher? obj

Returns `#t` if the given obj is a block cipher object, otherwise `#f`.

Function make-block-cipher ( scheme `block-cipher-descriptor?` ) ( mode `mode-descriptor` ) :optional ( padding `pkcs7-padding` )

Creates a block cipher object of scheme encryption scheme and mode encryption mode.
padding is used to encrypt or decrypt the last block of the plain text.

Function block-cipher-block-length ( cipher `block-cipher?` )

Returns the block length of the given cipher.

Function block-cipher-init! ( cipher `block-cipher?` ) ( direction `symbol?` ) ( key `symmetric-key?` ) :optional ( parameter `cipher-parameter?` )

Initialise the given cipher for the given direction purpose with the given key and parameter.
The direction must be a symbol returned by the `cipher-direction` macro.

Function block-cipher-init ( cipher `block-cipher?` ) ( direction `symbol?` ) ( key `symmetric-key?` ) :optional ( parameter `cipher-parameter?` )

Initialise the give cipher. This procedure is an analogy to the `block-cipher-init!`, the difference is this procedure returns a copy of the given cipher.

Function block-cipher-encrypt! ( cipher `block-cipher?` ) ( pt `bytevector?` ) ( ps `integer?` ) ( ct `bytevector?` ) ( cs `integer?` )

Encrypts the given plain text pt from the position of ps, and store the cipher text into ct from the position of cs. Then returns the byte size of the encrypted plain text.
The encryption is executed by the given cipher.

Function block-cipher-encrypt ( cipher `block-cipher?` ) ( pt `bytevector?` ) :optional ( ps 0)

Encrypts the given plain text pt from the position of ps, and returns the cipher text.
The encryption is executed by the given cipher.

NOTE: the given pt length and result cipher text length may differ if the pt length is not multiple of the cipher block size.

Function block-cipher-last-block-size ( cipher `block-cipher?` ) ( block (or `bytevector?` `integer?` ))

Returns the required output space in bytes.

This procedure is useful when the encryption mode is GCM-SIV or CCM.

Function block-cipher-encrypt-last-block! ( cipher `block-cipher?` ) ( pt `bytevector?` ) ( ps `integer?` ) ( ct `bytevector?` ) ( cs `integer?` )

Encrypts the given plain text pt from the position of ps, and store the cipher text into ct from the position of cs. Then returns the byte size of the encrypted plain text.
The encryption is executed by the given cipher.

This procedure consumes all the plain text, and applies padding if needed.

Function block-cipher-encrypt-last-block ( cipher `block-cipher?` ) ( pt `bytevector?` ) :optional ( ps 0)

Encrypts the given plain text pt from the position of ps, and returns the cipher text.
The encryption is executed by the given cipher.

This procedure consumes all the plain text, and applies padding if needed.

Function block-cipher-decrypt! ( cipher `block-cipher?` ) ( ct `bytevector?` ) ( cs `integer?` ) ( pt `bytevector?` ) ( ps `integer?` )

Decrypts the given cipher text ct from the position of cs, store the plain text info pt from the position of cs. Then returns the byte size of the decrypted cipher text. The decryption is executed by the given cipher.

Function block-cipher-decrypt ( cipher `block-cipher?` ) ( ct `bytevector?` ) :optional ( cs 0)

Decrypts the given cipher text ct from the position of cs, and returns the plain text.
The decryption is executed by the given cipher.

NOTE: the given ct length and result plain text length may differ if the ct length is not multiple of the cipher block size.

Function block-cipher-decrypt-last-block! ( cipher `block-cipher?` ) ( ct `bytevector?` ) ( cs `integer?` ) ( pt `bytevector?` ) ( ps `integer?` )

Decrypts the given cipher text ct from the position of cs, store the plain text info pt from the position of cs. Then returns the byte size of the decrypted cipher text.

This procedure applies unpadding if the cipher is created with padding.

Function block-cipher-decrypt-last-block ( cipher `block-cipher?` ) ( ct `bytevector?` ) :optional ( cs 0)

Decrypts the given cipher text ct from the position of cs, and returns the plain text.
The decryption is executed by the given cipher.

This procedure applies unpadding if the cipher is created with padding.

Function block-cipher-done! ( cipher `block-cipher?` )

Cleanup the given cipher and make it neutral state.

Function block-cipher-update-aad! ( cipher `block-cipher?` ) ( aad `bytevector?` ) :optional ( start 0) ( length `(- (bytevector-length aad) start)` )

Updating Additional Authentication Data aad of the given cipher.
Optional arguments restricts the range of the aad.

This procedure is effective on authenticated encryption modes.

Function block-cipher-update-iv! ( cipher `block-cipher?` ) ( iv `bytevector?` ) :optional ( start 0) ( length `(- (bytevector-length aad) start)` )

Updating Initial Vector iv of the given cipher.
Optional arguments restricts the range of the iv.

This procedure is effective only GCM mode.

Function block-cipher-max-tag-length ( cipher `block-cipher?` )

Returns the max tag length of the given cipher. If the cipher doesn't support authentication tag, then it returns `0`.

Function block-cipher-done/tag! ( cipher `block-cipher?` ) ( tag `bytevector?` ) :optional ( start 0)

If the cipher is encryption mode, then the procedure stores the authentication tag into the give tag of the position starting start.

If the cipher is decryption mode, then the procedure validates the given tag against the cipher's authentication tag starting from the position of start.

Function block-cipher-done/tag ( cipher `block-cipher?` ) ( tag-len `integer?` )

This procedure is only for encryption mode.
Stores the cipher's authentication tag into the given tag, starting position of start.

#### [§5] Stream ciphers

Function stream-cipher-descriptor? obj

Returns `#t` if the given obj is a stream cipher descriptor, otherwise `#f`.

Currently, below encryption algorithms are supported:

Stream cipher descriptor *scheme:chacha20*
Stream cipher descriptor *scheme:xchacha20* 0.9.12
Stream cipher descriptor *scheme:chacha20-poly1305*
Stream cipher descriptor *scheme:xchacha20-poly1305* 0.9.12
Function stream-cipher-descriptor-aead? ( descriptor `stream-cipher-descriptor?` )

Returns `#t` if given the descriptor is a AEAD stream cipher, otherwise `#f`.

Function stream-cipher? obj

Returns `#t` if the given obj is a stream cipher object, otherwise `#f`.

Function make-stream-cipher ( scheme `stream-cipher-descriptor?` )

Creates a stream cipher object of scheme encryption scheme.

### Asymmetric ciphers

Function asymmetric-cipher-descriptor? obj

Returns `#t` if the given obj is an asymmetric cipher descriptor, otherwise `#f`.

Currently, below asymmetric encryption algorithms are supported:

Asymmetric cipher descriptor *scheme:rsa*
Function asymmetric-cipher? obj

Returns `#t` if the given obj is an asymmetric cipher, otherwise `#f`.

Function make-asymmetric-cipher ( scheme `asymmetric-cipher-descriptor?` :key encoding :allow-other-keys

Creates an asymmetric cipher of scheme.
The encoding specifies its encoding algorithm, default is `oaep-encoding`.

Function asymmetric-cipher-init! ( cipher `asymmetric-cipher?` ) ( key `asymmetric-key?` )

Initialise the given cipher with the given key.

Function asymmetric-cipher-init ( cipher `asymmetric-cipher?` ) ( key `asymmetric-key?` )

Initialise the given cipher with the given key. This procedure is an analogy to the `asymmetric-cipher-init!`, the differ is this procedure returns a copy of the given cipher.

Function asymmetric-cipher-encrypt-bytevector ( cipher `asymmetric-cipher?` ) ( bv `bytevector?` ) :optional (start 0)

Encrypts the given bytevector bv with the given cipher from the position of start and returns a bytevector.

Function asymmetric-cipher-decrypt-bytevector ( cipher `asymmetric-cipher?` ) ( bv `bytevector?` ) :optional (start 0)

Decrypts the given bytevector bv with the given cipher from the position of start and returns a bytevector.

Function asymmetric-cipher-done! ( cipher `asymmetric-cipher?` )

Cleanup the given cipher.

Function oaep-encoding

Provides OAEP encoding scheme. This can be used for `:encoding` keyword's argument of the `make-asymmetric-cipher` procedure.

This encoding scheme accepts the following keyword arguments:

`:digest`

  A digest descriptor to be generate a digest for label provided by `:label` keyword. Default value is `*digest:sha-1*`

`:label`

  A label. Default value is `#vu8()`.

`:mgf`

  MGF function. Default value is `mgf-1`.

`:mgf-digest`

  A digest descriptor to be used by the `:mgf`'s argument. Default value is `*digest:sha-1*`.

`:prng`

  A pseudo random generator to generate padding. Default value is `(secure-random-generator *prng:chacha20*)`.

Function pkcs1-v1.5-encoding

Provides PKCS#1.5 encoding scheme. This can be used for `:encoding` keyword's arguments of the `make-asymmetric-cipher` procedure.

This encoding scheme accepts the following keyword arguments:

`:prng`

  A pseudo random generator to generate padding. Default value is `(secure-random-generator *prng:chacha20*)`.

Function mgf-1

MGF-1 procedure. This can be used to `:mgf` keyword's argument of the `oaep-encoding`.

## Digest library - (sagittarius crypto digests)

The digest library provides cryptographic hash functions.

Library (sagittarius crypto digests)

The digest library, this library exports the procedures listed below sections.

### Digest descriptor

A digest descriptor describes the characteristic of the digest, such as name, digest size (if applicable), block size and OID (if exists).

Function digest-descriptor? obj

Returns `#t` if the given obj is a digest descriptor, otherwise `#f`.

Function digest-descriptor-name ( descriptor `digest-descriptor?` )

Returns the human readable name of the descriptor.

Function digest-descriptor-digest-size ( descriptor `digest-descriptor?` )

Returns the digest size of the descriptor. Some of the digests, e.g. SHAKE, don't have fixed digest size.

Function digest-descriptor-block-size ( descriptor `digest-descriptor?` )

Returns the block size of the descriptor.

Function digest-descriptor-oid ( descriptor `digest-descriptor?` )

Returns the OID of the descriptor. If the digest doesn't have OID, then it returns `#f`.

Blow are the digest descriptors supported by this library:

Digest descriptor *digest:whirlpool*
Digest descriptor *digest:ripemd-128*
Digest descriptor *digest:ripemd-160*
Digest descriptor *digest:ripemd-256*
Digest descriptor *digest:ripemd-320*
Digest descriptor *digest:sha-1*
Digest descriptor *digest:sha-224*
Digest descriptor *digest:sha-256*
Digest descriptor *digest:sha-384*
Digest descriptor *digest:sha-512*
Digest descriptor *digest:sha-512/224*
Digest descriptor *digest:sha-512/256*
Digest descriptor *digest:sha3-224*
Digest descriptor *digest:sha3-256*
Digest descriptor *digest:sha3-384*
Digest descriptor *digest:sha3-512*
Digest descriptor *digest:keccak-224*
Digest descriptor *digest:keccak-256*
Digest descriptor *digest:keccak-384*
Digest descriptor *digest:keccak-512*
Digest descriptor *digest:tiger-192*
Digest descriptor *digest:md5*
Digest descriptor *digest:md4*
Digest descriptor *digest:md2*
Digest descriptor *digest:blake2s-128*
Digest descriptor *digest:blake2s-160*
Digest descriptor *digest:blake2s-224*
Digest descriptor *digest:blake2s-256*
Digest descriptor *digest:blake2b-160*
Digest descriptor *digest:blake2b-256*
Digest descriptor *digest:blake2b-384*
Digest descriptor *digest:blake2b-512*
Digest descriptor *digest:shake-128*
Digest descriptor *digest:shake-256*
Digest descriptor *digest:cshake-128*
Digest descriptor *digest:cshake-256*

We supports weak / broken digest algorithms, such as MD5. It is users' responsibility to choose appropriate algorithm.

### Message Digest

Message Digest is a stateful object which ingests input and provides digests.

Function message-digest? obj

Returns `#t` if the given obj is a message digest, otherwise `#f`.

Function make-message-digest ( descriptor `digest-descriptor?` )

Creates a message digest of the algorithm descriptor.

Function message-digest-descriptor ( md `message-digest?` )

Returns the digest descriptor of given md.

Function message-digest-digest-size ( md `message-digest?` )

Returns the digest size of given md.

Function digest-message ( md `message-digest?` ) ( msg `bytevector?` ) :optional length

Returns the digest of the given msg.
The optional argument length is only required for the variable length digest algorithms, such as SHAKE. Otherwise, the value will be ignored.

Function digest-message! ( md `message-digest?` ) ( msg `bytevector?` ) ( out `bytevector?` ) :optional start length

Digests the given msg, then fill the result into the out.
Optional argument start and length specify the start position of the out and the length of the filling.

Below procedures are low level APIs which can be used not to allocate entire input buffer, say using `get-bytevector-n!` instead of `get-bytevector-all`.

Function message-digest-init! ( md `message-digest?` )

Initialises the given md. This procedure rests the previous input as well.

Function message-digest-process! ( md `message-digest?` ) ( msg `bytevector?` ) :optional start length

Ingests the given msg into md.
Optional argument start and length controls the range of the msg.

Function message-digest-done! ( md `message-digest?` ) ( out `bytevector?` ) :optional start length

Fill the result digest of md into the out.
Optional argument start and length controls the range of the out.

Function message-digest-done ( md `message-digest?` ) :optional length

Returns a freshly allocated bytevector whose content is the result of md, digest.
Optional argument length is only used for the variable length digest algorithm, such as SHAKE. Otherwise it will be ignored.

## Random library - (sagittarius crypto random)

The random library provides cryptographically secure random number generator (CSPRNG) operations.

Library (sagittarius crypto random)

The random library, this library exports the procedures listed below sections.

### PRNG descriptor

PRNG descriptor is a representation of pseudo random generator (PRNG).

Library prng-descriptor? obj

Returns `#t` if the given obj is a PRNG descriptor, otherwise `#f`.

Library prng-descriptor-name ( descriptor `prng-descriptor?` )

Returns a human readable name of the given descriptor.

Below are the supported PRNGs.

PRNG descriptor *prng:yarrow*
PRNG descriptor *prng:fortuna*
PRNG descriptor *prng:rc4*
PRNG descriptor *prng:sober-128*
PRNG descriptor *prng:chacha20*

These are the PRNG algorithms, Yarrow, Fortuna RC4, Sober-128 and ChaCha20, respectively.

PRNG descriptor *prng:system*

This is a system, platform dependent, PRNG. For example, this PRNG reads from file descriptor of `/dev/urandom` on Linux or other POSIX environment if the device exists.

Ths PRNG is slow as it requires I/O. Also can't be pseudo random generator described below.

### Random generator

Random generator has a hierachical class structure. If you only use the provided PRNGs, you don't have to care about it. However, if you want to make a custom algorithm which is not supported by the library, then you may need to know how to enhance it. Creating a custom random generator is described the below section.

                                   <random-generator>
                                           |
               +---------------------------+------------------------+
               |                           |                        |
    <builtin-random-generator> <secure-random-generator> <custom-random-generator>
               |                           |
               +-------------+-------------+
                             |
             <builtin-secure-random-generator>

Function random-generator? obj

Returns `#t` if the given obj is a random generator, otherwise `#f`.

Function builtin-random-generator? obj

Returns `#t` if the given obj is a builtin random generator, otherwise `#f`.

Function secure-random-generator? obj

Returns `#t` if the given obj is a secure random generator, otherwise `#f`.

Function custom-random-generator? obj

Returns `#t` if the given obj is a custom random generator, otherwise `#f`.

Function random-generator-read-random-bytes ( random-generator `random-generator?` ) size

Returns a bytevector of length size filled with random data read from the given random-generator.

Function random-generator-read-random-bytes! ( random-generator `random-generator?` ) ( out `bytevector?` ) :optional start length

Reads random data from random-generator, and fill them into out.
If optional arguments starts and length are specified, then it specifies the range of the output bytevector.

Function random-generator-randomize! ( random-generator `random-generator?` ) ( seed `bytevector?` ) :optional start length

Add entropy seed to the given random-generator.
If optional arguments starts and length are specified, then it specifies the range of the seed bytevector.

Function random-generator-random-integer ( random-generator `random-generator?` ) bound

Returns a random integer of range 0 <= n <= bound.

Function pseudo-random-generator descriptor opts ...
Function secure-random-generator descriptor opts ...

Creates a pseudo or secure random generator, respectively.
If the given descriptor is PRNG descrptor, then these procedure creates builtin random generator ignoreing the given opts.
If the given descriptor is not PRNG descrptor, then these procedure call `make-custom-random-generator` method passing descriptor and opts.

If `secure-random-generator` is used, then `make-custom-random-generator` receives `:secure-random` keyword argument with value of `#t`, so that the receiver can handle it properly.

Method random-generator-state `<random-generator>`

Gets the state of given `<random-generator>` if it's supported.
By default this method returns `#f`, means not supported.

Method random-generator-state `<random-generator>` `<any>`

Sets the given state represented by `<any>` to `<random-generator>` if it's supported.
By default this method does nothing and returns `#f`, means not supported.

### Custom random generator

Class <custom-random-generator>
Generic make-custom-random-generator

## Signature library - (sagittarius crypto signatures)

The signature library provides signature generation / verification operations.

Library (sagittarius crypto signatures)

The signature library, this library exports the procedures listed below sections.

### Algorithms

Below are the algorithms supported by the library.

Signature algorithm *signature:rsa*
Signature algorithm *signature:dsa*
Signature algorithm *signature:ecdsa*
Signature algorithm *signature:eddsa*
Signature algorithm *signature:ed25519*
Signature algorithm *signature:ed25519ctx*
Signature algorithm *signature:ed25519ph*
Signature algorithm *signature:ed448*
Signature algorithm *signature:ed448ph*

These algorithms can be used both signer and verifier.

### Signer

Function signer? obj

Returns `#t` if the given obj is a signer, otherwise `#f`.

Function make-signer scheme key opts ...

Creates a signer of the scheme. The scheme must be one of the signature algorithms listed above. The key must be an appropriate private key for the specified scheme.

opts must be a keyword arguments, the procedure ignores unsupported keywords. The supporting keyword arguments and its scheme are below

`:digest`

  For all signature algorithms. Specifying digest algorithm. Most of the algorithm uses `*digest:sha-256*` as its default digest algorithm.

`:encoder`

  For `*signature:rsa*`. Specifying signature encoding, default value is `pkcs1-emsa-pss-encode`.

`:k-generator`

  For `*signature:dsa*` and `*signature:ecdsa*`. Specifying k generator. It uses random generator as default value.

`:der-encode`

  For `*signature:dsa*` and `*signature:ecdsa*`. Specifying if the result signature is DER encoded or not. Default value is `#t`.

`:scheme`

  For `*signature:eddsa*`. Specifying EdDSA scheme.

`:context`

  For `*signature:eddsa*` `*signature:ed25519ctx*`, `*signature:ed25519ph*`, `*signature:ed448*`, and `*signature:ed448ph*`. Specifying context, default value is `#vu8()`.

For the scheme specific procedures such as `k-generator`, see the below sections.

Function signer-sign-message ( signer `signer?` ) ( message `bytevector?` )

Signs the given message with signer and returns the signature.

Function signer-init! ( signer `signer?` )

Initialises the given signer

Function signer-process! ( signer `signer?` ) ( message `bytevector?` ) :optional start length

Feeds the given message to the signer. The optional arguments specifies the range of the message to feed.

Function signer-sign! ( signer `signer?` )

Signs the accumulated message of signer and returns a bytevector.

### Verifier

Function verifier? obj

Returns `#t` if the given obj is a verifier, otherwise `#f`.

Function make-verifier scheme key opts ...

Creates a verifier of the scheme. The scheme must be one of the signature algorithms listed above. The key must be an appropriate public key for the specified scheme.

opts must be a keyword arguments, the procedure ignores unsupported keywords. The supporting keyword arguments and its scheme are below

`:digest`

  For all signature algorithms. Specifying digest algorithm. Most of the algorithm uses `*digest:sha-256*` as its default digest algorithm.

`:verifier`

  For `*signature:rsa*`. Specifying signature encoding, default value is `pkcs1-emsa-pss-verify`.

`:der-encode`

  For `*signature:dsa*` and `*signature:ecdsa*`. Specifying if the result signature is DER encoded or not. Default value is `#t`.

`:scheme`

  For `*signature:eddsa*`. Specifying EdDSA scheme.

`:context`

  For `*signature:eddsa*` `*signature:ed25519ctx*`, `*signature:ed25519ph*`, `*signature:ed448*`, and `*signature:ed448ph*`. Specifying context, default value is `#vu8()`.

Function verifier-verify-signature ( verifier `verifier?` ) ( message `bytevector?` ) ( signature `bytevector?` )

Verifies if the given signature is valid signature of the given message with verifier.

It returns `#t` if the given signature is a valid signature.
If the signature verification is failed, then returns `#f`.
If the signature format is not valid, then raise an error.

Function verifier-init! ( verifier `verifier?` )

Initialises the given verifier.

Function verifier-process! ( verifier `verifier?` ) ( message `bytevector?` ) :optional start length

Feeds the given message to the verifier. The optional arguments specifies the range of the message to feed.

Function verifier-verify! ( verifier `verifier?` ) ( signature `bytevector?` )

Verifies the given signature against the accumulated messgage.

It returns `#t` if the given signature is a valid signature.
If the signature verification is failed, then returns `#f`.
If the signature format is not valid, then raise an error.

### RSA signature specific

These procedures are RSA signature specific, i.e. `:encoder` and `:verifier` keyword arguments, the keyword arguments specified in these procedures are passed via either `make-signer` or `make-verifier`.

Function pkcs1-emsa-pss-encode :key salt (mgf `mgf-1` ) mgf-digest

PKCS#1 EMSA PSS encode. The keyword arguments specifies its salt, MGF and digest algorithm of the MGF.

Function pkcs1-emsa-pss-verify :key salt-length (mgf `mgf-1` ) mgf-digest

PKCS#1 EMSA PSS verify. The keyword arguments specifies its salt, MGF and digest algorithm of the MGF.

Function pkcs1-emsa-v1.5-encode

PKCS#1 EMSA PKCS1-v1_5 encode.

Function pkcs1-emsa-v1.5-verify

PKCS#1 EMSA PKCS1-v1_5 verify.

Function mgf-1

MGF1 function, the same as the one exported from `(sagittarius crypto ciphers)`.

### DSA and ECDSA signature specific

Function make-random-k-generator ( prng `random-generator?` )

Creates a random k-generator.

Function make-hmac-k-generator ( digest `digest-descriptor?` )

Creates a RFC 6979 determistic k-generator.

### Supporting algorithms' OIDs

The below bindings are string representaion of OIDs which can be used to create X.509 algorithm identifier, i.e. `make-x509-algorithm-identifier`, described in X.509 library.

Constant *signature-algorithm:rsa-pkcs-v1.5-sha1*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha256*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha384*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha512*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha224*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha512/224*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha512/256*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha3-224*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha3-256*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha3-384*
Constant *signature-algorithm:rsa-pkcs-v1.5-sha3-512*
Constant *signature-algorithm:rsa-ssa-pss*
Constant *signature-algorithm:dsa-sha224*
Constant *signature-algorithm:dsa-sha256*
Constant *signature-algorithm:dsa-sha384*
Constant *signature-algorithm:dsa-sha512*
Constant *signature-algorithm:ecdsa-sha1*
Constant *signature-algorithm:ecdsa-sha224*
Constant *signature-algorithm:ecdsa-sha256*
Constant *signature-algorithm:ecdsa-sha384*
Constant *signature-algorithm:ecdsa-sha512*
Constant *signature-algorithm:ecdsa-sha3-224*
Constant *signature-algorithm:ecdsa-sha3-256*
Constant *signature-algorithm:ecdsa-sha3-384*
Constant *signature-algorithm:ecdsa-sha3-512*
Constant *signature-algorithm:ed25519*
Constant *signature-algorithm:ed448*

The name must be descriptive enough to see which algorithm of OID it represents.

## MAC library - (sagittarius crypto mac)

The Message Authentication Code, MAC, library provides MAC generation / verification operations.

Library (sagittarius crypto mac)

The MAC library, this library exports the procedures listed below sections.

### Algorithms

Below are the MAC algorithms supported by the library.

MAC algorithm *mac:hmac*
MAC algorithm *mac:cmac*
MAC algorithm *mac:gmac*
MAC algorithm *mac:kmac*
MAC algorithm *mac:kmac-128*
MAC algorithm *mac:kmac-256*
Function mac? obj

Returns `#t` if the given obj is MAC object, otherwise `#f`.

Function make-mac type key opts ...

Creates a MAC object of algorithm type.
key must be an appropriate shared secret per type. At this moment, all the algorithms require bytevector.

Function mac-type ( mac `mac?` )

Returns the type of given mac.

Function mac-mac-size ( mac `mac?` )

Returns MAC size of the given mac, if the MAC size is fixed, otherwise `#f`.
Only KMAC is variable length.

Function mac-oid ( mac `mac?` )

Returns OID of the mac, if it has, otherwise `#f`.

Function generate-mac ( mac `mac?` ) ( message `bytevector?` ) :optional length

Generates MAC of given message by mac.
Optional argument length specifies the length of returning bytevector.

NOTE: length doesn't guarantee the bytevector is filled with MAC. If the MAC size is shorter than length, then excess values are filled with 0.

Function generate-mac! ( mac `mac?` ) ( message `bytevector?` ) ( out `bytevector?` ) :optional start length

Generates MAC of given message by mac and fills it in the out from position start to length count.

Function verify-mac ( mac `mac?` ) ( message `bytevector?` ) ( auth-mac `bytevector?` )

Verifies if the given auth-mac is MAC of message by mac and returns `#t` if the MAC is verified, otherwise signals an error.

Function mac-init! ( mac `mac?` )

Initialises the given mac. If this procedure is called during the message processing, then the previous state will be reset.

Function mac-process! ( mac `mac?` ) ( message `bytevector?` ) :optional start length

Processes the given message with mac.
Optional arguments specifies the range of message to be processed.

Function mac-done! ( mac `mac?` ) ( out `bytevector?` ) :optional start length

Generates MAC by mac and fills it into the out from position _start to length count.

## X.509 library - (sagittarius crypto x509)

The X.509 library provides X.509 certificate, CRL, CSR and some other related operations.

Library (sagittarius crypto x509)

The X.509 library, this library exports the procedures listed below sections.

### X.509 certificate

Function x509-certificate? obj

Returns `#t` if the given obj is X.509 certificate, otherwise `#f`.

Function bytevector->x509-certificate ( bv `bygevector?` )

Converts the given bytevector bv to X.509 certificate. The bytevector must be a valid X.509 certificate structure otherwise an error is signalled.

Function read-x509-certificate ( bin (and `input-port?` `binary-port?` ))

Reads X.509 certificate from the given binary input port bin. The data must be a valid X.509 certificate structure otherwise an error is signalled.

Function x509-certificate->bytevector ( certificate `x509-certificate?` )

Converts the given X.509 certificate certificate to a bytevector.

Function write-x509-certificate ( certificate `x509-certificate?` ) :optional out

Writes the given X.509 certificate into out if specified, otherwise `(current-output-port)`.

Function x509-certificate-expired? ( certificate `x509-certificate?` ) :optional when

Checks if the given X.509 certificate is expired on the given when if specified, otherwise `(current-date)`.

Function x509-certificate-issuer-dn ( certificate `x509-certificate?` )

Retrieves IssuerDn of the given certificate as X.509 name.

Function x509-certificate-subject-dn ( certificate `x509-certificate?` )

Retrieves SubjectDn of the given certificate as X.509 name.

Function x509-certificate-public-key ( certificate `x509-certificate?` )

Retrieves public key of the given certificate.

Function x509-certificate-validity ( certificate `x509-certificate?` )

Retrieves validity of the given certificate as X.509 validity.

Function x509-certificate-serial-number ( certificate `x509-certificate?` )

Retrieves serial number of the given certificate.

Function x509-certificate-version ( certificate `x509-certificate?` )

Retrieves version of the given certificate.
The returning value indicates the version number, for example, v1 certificate then the procedure returns `1`.

Function x509-certificate-signature ( certificate `x509-certificate?` )

Retrieves signature of the given certificate.

Function x509-certificate-signature-algorithm ( certificate `x509-certificate?` )

Retrieves signature algorithm of the given certificate as X.509 algorithm identifier.

Function x509-certificate-extensions ( certificate `x509-certificate?` )

Retrieves extensions of the given certificate as a list of X.509 extension.

Function validate-x509-certificate ( certificate `x509-certificate?` ) validator ...

Validates the given certificate against the given validator.
validator must be a procedure accepts one argument, certificate.

Function x509-certificate-signature-validator ( public-key `public-key?` )

Creates a signature validator.

Function x509-certificate-validity-validator :optional when

Creates a validity validator.
Optional argument when specifies in which period of time the certificate validity. Default value is `(current-date)`.

Function x509-certificate-signed-by? ( certificate `x509-certificate?` ) ( ca-certificate `x509-certificate?` )

Returns `t` if the given certificate is signed by the ca-certificate, otherwise `#t`.

Function x509-certificate-revoked? ( certificate `x509-certificate?` ) ( ca-certificate `x509-certificate?` ) ( crl `x509-certificate-revocation-list?` ) :optional date

Checks if the given certificate is revoked on the given crl.
If the optional argument date is provided, then the procedure checks on the given date. Default value is `(current-date)`.

Function x509-certificate-template? obj

Returns `#t` if the given obj is X.509 certificate template, otherwise `#f`.

Macro x509-certificate-template-builder ( field value ) ...

Builds an X.509 certificate template. field and its value must be one or more of the followings:

`issuer-dn`

  X.509 name, represents IssuerDn. Required.

`subject-dn`

  X.509 name, represents SubjectDn. Required.

`serial-number`

  Integer, represents serial number. Required.

`not-before`

  Date, represents not before. Required.

`not-after`

  Date, represents not after. Required.

`public-key`

  Public key of the certificate. Required.

`issuer-unique-id`

  Bytevector, represents issuer unique Id. Optional.

`subject-unique-id`

  Bytevector, represents subject unique Id. Optional.

`extentions`

  List of X.509 extensions. Optional.

Function sign-x509-certificate-template ( template `x509-certificate-template?` ) ( aid (or `string?` `x509-algorithm-identifier?` )) ( private-key `private-key?` )

Signs the given template with aid algorithm and private-key, then returns X.509 certificate.

### X.509 CSR

Function x509-certification-request? obj

Returns `#t` if the given obj is X.509 certificate, otherwise `#f`.

Function bytevector->x509-certification-request ( bv `bygevector?` )

Converts the given bytevector bv to X.509 CSR. The bytevector must be a valid X.509 CSR otherwise an error is signalled.

Function read-x509-certification-request ( bin (and `input-port?` `binary-port?` ))

Reads X.509 CSR from the given binary input port bin. The data must be a valid X.509 CSR structure otherwise an error is signalled.

Function x509-certification-request->bytevector ( csr `x509-certification-request?` )

Converts the given X.509 CSR csr to a bytevector.

Function write-x509-certification-request ( csr `x509-certification-request?` ) :optional out

Writes the given X.509 CSR into out if specified, otherwise `(current-output-port)`.

Function x509-certification-request-version ( csr `x509-certification-request?` )

Retrieves version of the given csr.
The returning value indicates the version number, for example, v1 certificate then the procedure returns `1`.

Function x509-certification-request-subject ( csr `x509-certification-request?` )

Retrieves SubjectDn of the given csr as X.509 name.

Function x509-certification-request-public-key ( csr `x509-certification-request?` )

Retrieves public key of the given csr.

Function x509-certification-request-attributes ( csr `x509-certification-request?` )

Retrieves list of attributes of the given csr as list of X.509 attributes.

Function x509-certification-request-signature ( csr `x509-certification-request?` )

Retrieves signature of the given csr.

Function x509-certification-request-signature-algorithm ( csr `x509-certification-request?` )

Retrieves signature algorithm of the given csr as X.509 algorithm identifier.

Function validate-x509-certification-request ( csr `x509-certification-request?` ) validator ...

Validates the given csr against the given validator.
validator must be a procedure accepts one argument, csr.

Function x509-certification-request-signature-validator

X.509 CSR signature validator. It validates the signature of the target X.509 CSR.

Function x509-certification-request-template? obj

Returns `#t` if the given obj is X.509 CSR template, otherwise `#f`.

Macro x509-certification-request-template-builder ( field _value) ...

Builds an X.509 CSR template. field and its value must be one or more of the followings:

`subject-dn`

  X.509 name, represents SubjectDn. Required.

`attributes`

  List of X.509 attributes. Optional.

Function sign-x509-certification-request-template ( template `x509-certification-request-template?` ) ( aid (or `string?` `x509-algorithm-identifier?` )) ( signing-key-pair `key-pair?` )

Signs the given template with aid algorithm and the private key of the signing-key-pair, then returns X.509 CSR.
The returning X.509 CSR contains the public key of the signing-key-pair.

### X.509 CRL

Function x509-certificate-revocation-list? obj

Returns `#t` if the given obj is X.509 CRL, otherwise `#f`.

Function bytevector->x509-certificate-revocation-list ( bv `bygevector?` )

Converts the given bytevector bv to X.509 CRL. The bytevector must be a valid X.509 CRL structure otherwise an error is signalled.

Function read-x509-certificate-revocation-list ( bin (and `input-port?` `binary-port?` ))

Reads X.509 CRL from the given binary input port bin. The data must be a valid X.509 CRL structure otherwise an error is signalled.

Function x509-certificate-revocation-list->bytevector ( crl `x509-certificate-revocation-list?` )

Converts the given X.509 CRL crl to a bytevector.

Function write-x509-certificate-revocation-list ( crl `x509-certificate-revocation-list?` ) :optional out

Writes the given X.509 CRL into out if specified, otherwise `(current-output-port)`.

Function x509-certificate-revocation-list-issuer ( crl `x509-certificate-revocation-list?` )

Retrieves IssuerDn of the given crl as X.509 name.

Function x509-certificate-revocation-list-this-update ( crl `x509-certificate-revocation-list?` )

Retrieves this update of the given crl as date.

Function x509-certificate-revocation-list-next-update ( crl `x509-certificate-revocation-list?` )

Retrieves next update of the given crl as date.

Function x509-certificate-revocation-list-revoked-certificates ( crl `x509-certificate-revocation-list?` )

Retrieves X.509 revoked certificate of the given crl as list.

Function x509-certificate-revocation-list-crl-extensions ( crl `x509-certificate-revocation-list?` )

Retrieves X.509 extensions of the given crl as X.509 extension list.

Function x509-certificate-revocation-list-signature-algorithm ( crl `x509-certificate-revocation-list?` )

Retrieves signature algorithm the given crl as X.509 algorithm identifier.

Function x509-certificate-revocation-list-signature ( crl `x509-certificate-revocation-list?` )

Retrieves signature of the given crl.

Function validate-x509-certificate-revocation-list ( crl `x509-certificate-revocation-list?` ) validator ...

Validates the given crl with the given validator, if the validation failed, then the procedure signals an error.

Function x509-certificate-revocation-list-signature-validator ( public-key `public-key?` )

Creates a X.509 CRL validator which verifies the signature with the given public-key.

Function x509-certificate-revocation-list-issuer-validator ( issuer `x509-name?` )

Creates a X.509 CRL validator which checks if the issuer DN is issuer or not.

Function x509-revoked-certificate? obj

Returns `#t` if the given obj is X.509 revoked certificate, otherwise `#f`.

Function make-x509-revoked-certificate ( serial-number `integer?` ) ( revocation-date `date?` ) :optional extensions

Creates a X.509 revoked certificate.

Function x509-revoked-certificate-serial-number ( rc `x509-revoked-certificate?` )

Retrieves serial number of the given rc.

Function x509-revoked-certificate-revocation-date ( rc `x509-revoked-certificate?` )

Retrieves revocation date of the given rc as date.

Function x509-revoked-certificate-crl-entry-extensions ( rc `x509-revoked-certificate?` )

Retrieves CRL entry extensions of the given rc as X.509 extension list.

Function x509-certificate-revocation-list-template? obj

Returns `#t` if the given obj is X.509 CRL template, otherwise `#f`.

Function x509-certificate-revocation-list-template-builder ( field value ) ...

Builds an X.509 CRL template. field and its value must be one or more of the followings:

`issuer-dn`

  X.509 name, represents IssuerDn. Required.

`this-update`

  Date, represents this update. Required.

`next-update`

  Date, represents next update. Optional.

`revoked-certificate`

  A list of X.509 revoked certificate, represents revoked certificates. Required.

`crl-extensions`

  A list of X.509 extensions, represents CRL extensions. Optional.

Function sign-x509-certificate-revocation-list-template ( template `x509-certificate-revocation-list-template?` ) ( aid (or `string?` `x509-algorithm-identifier` )) ( private-key `private-key?` )

Signs the given template with aid algorithm and private-key, then returns X.509 CRL.

### Distinguished name (DN)

Function x509-name? obj

Returns `#t` if the given obj is X.509 name, otherwise `#f`.

Function x509-name component ...
Function list->x509-name list of component

Creates X.509 name from the given components.

A component must be a list of either:

- Symbol representation of well-known name, such as `CN`, and string value

- Or string representation of OID and string value.

Below are the supported symbols:

`CN`

  Common name

`L`

  Locality name

`ST`

  State or province name

`O`

  Origanisation name

`OU`

  Origanisation unit name

`STREET`

  Street address

`DC`

  Domain component

`UID`

  User ID

`Name`

  Name

`SURNAME`

  Surname

`GIVENNAME`

  Given name

`T`

  Title

`DN`

  DN qualifier

`SERIALNUMBER`

  Serial number

`Pseudonym`

  Pseudonym

`E`

  Email address

Function x509-name->string ( name `x509-name?` )

Converts given name to string representation.

Function string->x509-name ( dn `string?` ) 0.9.12

Converts given dn to X509 names.

### X.509 validity

Function x509-validity? obj

Returns `#t` if the given obj is X.509 validity, otherwise `#f`.

Function make-x509-validity ( not-before `date?` ) ( not-after `date?` )

Creates a X.509 validity of the range of not-after and not-after.

Function x509-validity-not-before ( validity `x509-validity?` )

Retrieves not before of validity as date.

Function x509-validity-not-after ( validity `x509-validity?` )

Retrieves not after of validity as date.

### X.509 algorithm identifier

Function x509-algorithm-identifier? obj

returns `#t` if the given obj is x.509 algorithm identifier, otherwise `#f`.

Function make-x509-algorithm-identifier ( oid `string?` ) :optional parameters

oid must be a valid string representaion of oid.
creates a x.509 algorithm identifier of _oid.
if optional parameter is passed, then it has to be a valid x.509 algorithm identifier parameter.

Function x509-algorithm-identifier-oid ( aid `x509-algorithm-identifier?` )

Retrieves OID of aid.

Function x509-algorithm-identifier-parameters ( aid `x509-algorithm-identifier?` )

Retrieves parameters of aid.

### X.509 subject public key info

Function subject-public-key-info? obj

returns `#t` if the given obj is subject public key info, otherwise `#f`.

Function subject-public-key-info->public-key ( spki `subject-public-key-info?` )

Converts given spki to a public key.

Function public-key->subject-public-key-info ( public-key `public-key?` )

Converts given public-key to a subject public key info.

Function bytevector->subject-public-key-info ( bv `bytevector?` )

Converts given bv to a subject public key info.
The bytevector must be a valid SubjectPublicKeyInfo structure. Otherwise, an error is signalled.

Function subject-public-key-info->bytevector ( spki `subject-public-key-info?` )

Converts given spki to a bytevector.

### X.509 attribute

Function x509-attribute? obj

Returns `#t` if the given obj is X.509 attribute, otherwise `#f`.

Function x509-attribute-type ( attr `x509-attribute?` )

Retrieves type of the attr.

Function x509-attribute-values ( attr `x509-attribute?` )

Retrieves values of the attr. The retrieved value may not be usable as it is.

Function x509-attribute-of oid

oid must be a string representaion of OID or object identifier.
Returns a predicate for a X.509 attribute list. The predicate checks if the given X.509 attribute has oid or not.

Function make-x509-challenge-password-attribute ( password `string?` )

Creates PKCS#9 challenge password attribute of the value password.

Function make-x509-extension-request-attribute x509-extension ...

x509-extension must be X.509 extension.
Creates PKCS#9 extension request attribute of the value x509-extensions.

Function x509-attribute->x509-extension-list ( attr `x509-attribute` )

Converts PKCS#9 extension request attribute to list of X.509 extensions.
If the attr does not have appropriate attribute type, the procedure signals an error.

Object identifier *pkcs-9:channelge-password*
Object identifier *pkcs-9:extenion-request*

The above object identifiers can be use for `x509-attribute-of` procedure.

### X.509 extension

Function x509-extension? obj

Returns `#t` if the given obj is X.509 extension, otherwise `#f`.

Function x509-extension-id ( ext `x509-extension?` )

Retrieves id of the ext.

Function x509-extension-critical? ( ext `x509-extension?` )

Retrieves critical of the ext.

Function x509-extension-value ( ext `x509-extension?` )

Retrieves value of the ext.

Object identifier *extension:authority-key-identifier*
Object identifier *extension:subject-key-identifier*
Object identifier *extension:key-usage*
Object identifier *extension:private-key-usage-period*
Object identifier *extension:certificate-policies*
Object identifier *extension:policy-mappings*
Object identifier *extension:subject-alt-name*
Object identifier *extension:issuer-alt-name*
Object identifier *extension:subject-directory-attributes*
Object identifier *extension:basic-constraints*
Object identifier *extension:name-constraints*
Object identifier *extension:policy-constraints*
Object identifier *extension:ext-key-usage*
Object identifier *extension:crl-distribution-points*
Object identifier *extension:inhibit-any-policy*
Object identifier *extension:freshest-crl*
Object identifier *extension:authority-info-access*
Object identifier *extension:subject-info-access*
Object identifier *extension:crl-number*
Object identifier *extension:delta-crl-indicator*
Object identifier *extension:issuing-distribution-point*
Object identifier *extension:crl-reason*
Object identifier *extension:certificate-issuer*
Object identifier *extension:hold-instruction-code*
Object identifier *extension:invalidity-date*

Object identifiers of X.509 extension. The name must be descritive enough to see which extension's OID it is.

Function x509-extension-of oid

oid must be a string representaion of OID or object identifier.
Creates a predicate for a list of X.509 extensions.

## Keystore library - (sagittarius crypto keystores)

The keystore library provides keystore operation. More precisely, PKCS#12.

PKCS#12 keystore is very flexible format, and there's no standard convension, but just de-fact. For example, PKCS#12 itself doesn't require the entry to be key/value, however most of the existing library uses the format as key/value map.

This library provides the de-fact convension layer. If you want to use raw PKCS#12 format, see `(sagittarius crypto pkcs keystore)`.

Library (sagittarius crypto keystores)

The keystore library, this library exports the procedures listed blow sections.

Function pkcs12-keystore? obj

Returns `#t` if the given obj is PKCS#12 keystore, otherwise `#f`.

Function make-pkcs12-keystore

Creates an empty PKCS#12 keystore.

Function read-pkcs12-keystore ( password `string?` ) :optiona in

Reads PKCS#12 keystore from in, if provided, otherwise `(current-input-port)`.

The password must be a valid password for the reading PKCS#12, otherwise an error is signalled.

Function bytevector->pkcs12-keystore ( bv `bytevector?` ) ( password `string?` )

Converts given bv to PKCS#12 keystore.

The password must be a valid password for the reading PKCS#12, otherwise an error is signalled.

Function pkcs12-keystore->bytevector ( ks `pkcs12-keystore?` ) ( password `string?` )

Converts the given ks to a bytevector using the given password as both integrity and privacy exchange key.

Function write-pkcs12-keystore ( ks `pkcs12-keystore?` ) ( password `string?` ) :optiona out

Writes the given ks to out if provided, otherwise `(current-output-port)`, using the given password as both integrity and privacy exchange key.

Function pkcs12-keystore-private-key-ref ( ks `pkcs12-keystore?` ) ( alias `string?` ) ( password `string?` )

Retrieves a private key associated to alias from ks decrypting with the given password.

If the alias doesn't exist in the ks, then returns `#f`.

Function pkcs12-keystore-private-key-set! ( ks `pkcs12-keystore?` ) ( alias `string?` ) ( key `private-key?` ) ( password `string?` ) certs

certs must be a list of X.509 certificates.

Stores the given key into the ks associating with alias. The key is encrypted with the password.

The certs must be a valid (chain) certificate(s) for the given key.

Function pkcs12-keystore-certificate-ref ( ks `pkcs12-keystore?` ) ( alias `string?` )

Retrieves a certificate associated to alias from ks.

If the alias doesn't exist in the ks, then returns `#f`.

Function pkcs12-keystore-certificate-set! ( ks `pkcs12-keystore?` ) ( alias `string?` ) ( cert `x509-certificate?` )

Stores the given cert into the given ks associating with alias.

Function pkcs12-keystore-certificate-chain-ref ( ks `pkcs12-keystore?` ) ( alias `string?` )

Retrieves certificate chain associated to alias from the ks.

If there's no certificate associated to alias, then it returns `()`.

Function pkcs12-keystore-delete-entry! ( ks `pkcs12-keystore?` ) ( alias `string?` )

Removes the entry associated to alias from the ks.

Function pkcs12-keystore-delete-all-entries! ( ks `pkcs12-keystore?` )

Removes all entries from the ks.

## KDF library - (sagittarius crypto kdfs)

The KDF, Key Derivation Function, library provides various KDF algorithms.

Library (sagittarius crypto kdfs)

The KDF library, this library exports the procedures listed below sections.

Function pbkdf-1 P S c dk-len :key ( digest `*digest:sha-1*` )

_P_and S must be bytevectors.
c and dk-len must be non-negative integers.

PBKDF1

Function pbkdf-2 P S c dk-len :key ( prf `*hmac-sha1-prf*` )

_P_and S must be bytevectors.
c and dk-len must be non-negative integers.

PBKDF2

Function mac->prf-provider scheme . opts

scheme must be a MAC scheme, e.g. `*mac:hmac*`.

Provides a PRF generator which accepts S, secret, based on the given scheme.
The opts will be passed to the MAC generation.

Function hkdf digest ikm salt info dk-len

HKDF

Function pkcf12-kdf digest pw salt iteration dk-len

PKCS12 KDF

Function scrypt P S N r p dk-len 0.9.13

scrypt, defined in RFC 7914.

P and S must be bytevectors, represents password and salt.
N must be an integer, represents cost parameter.
r must be an integer, represents block size.
p must be an integer, represents parallelization parameter.

## (sagittarius atomic) - Atomic operation

Library (sagittarius atomic) 0.9.13

This library provides atomic operation. The underlying implementation of this library can be either `stdatomic` from C11 or `<atomic>` from C++11. If the platform supports the first one, then that'd be chosen, otherwise the latter one.

NOTE: if the platform doesn't support none of them, then compilation error.

Function atomic? obj

Returns `#t` if the given obj is an atomic object, otherwise `#f`.

Function make-atomic obj

Creates a fresh atomic object whoes initial value is obj.

Function atomic-flag? obj

Returns `#t` if the given obj is an atomic flag object, otherwise `#f`.

Function make-atomic-flag

Creates a fresh atomic flag. The flag is unset.

Function atomic-fixnum? obj

Returns `#t` if the given obj is an atomic fixnum object, otherwise `#f`.

Function make-atomic-fixnum ( n `fixnum?` )

Creates a fresh atomic fixnum object whoes initial value is n.

Function atomic-pair? obj

Returns `#t` if the given obj is an atomic pair object, otherwise `#f`.

Function make-atomic-pair head tail

Creates a fresh atomic pair object whoes initial values are first and tail.

This is double word atomic object.

Function memory-order? obj

Returns `#t` if the given obj is a fixnum and value of memory order.

Constant *memory-order:relaxed*
Constant *memory-order:consume*
Constant *memory-order:acquire*
Constant *memory-order:release*
Constant *memory-order:acq-rel*
Constant *memory-order:seq-cst*

The memory order values. The meanings are the same as C11.

If the `libatomic_ops` is used as underlying implementation, then it translate them with the best effort.

Function atomic-load ( a `atomic?` ) :optional ( order `memory-order?` )

Loads the current value of the given atomic of a.

Function atomic-store! ( a `atomic?` ) v :optional ( order `memory-order?` )

Stores the given value v into the atomic a.

Function atomic-fixnum-load ( a `atomic-fixnum?` ) :optional ( order `memory-order?` )

Loads the current value of the given atomic of a.

Function atomic-fixnum-store! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )

Stores the given value n into the atomic a. The return value is unspecified.

Function atomic-fixnum-add! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )
Function atomic-fixnum-sub! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )
Function atomic-fixnum-ior! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )
Function atomic-fixnum-xor! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )
Function atomic-fixnum-and! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )

Operates the addition, subtraction, bitwise or, bitwise xor and bitwise and against the value of atomic a with given n and updates the value of a and returns the previous value of a.

Function atomic-exchange! ( a `atomic?` ) v :optional ( order `memory-order?` )
Function atomic-fixnum-exchange! ( a `atomic-fixnum?` ) ( n `fixnum?` ) :optional ( order `memory-order?` )

Exchange the value of a with given v or n and returns the old value of a.

Function atomic-compare-and-swap! ( a `atomic?` ) e v :optional ( order `memory-order?` )

CAS operation. Returns `#t` if the operation succeed, otherwise `#f`.

Function atomic-fetch-compare-and-swap! ( a `atomic?` ) e v :optional ( order `memory-order?` )

CAS operation. Returns previously set value if the operation failed, otherwise the e.

Function atomic-fixnum-inc! ( a `atomic-fixnum?` ) :optional ( order `memory-order?` )
Function atomic-fixnum-dec! ( a `atomic-fixnum?` ) :optional ( order `memory-order?` )

Increment or decrement the value of given a and updates the value.

Function atomic-thread-fence ( order `memory-order?` )

Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses.

# Utility libraries

## (archive) - Generic archive interface

Library archive

This library provides generic interface to access archive libraries. Sagittarius supports `tar` and `zip`.

Following code describes a typical use of the library;

    (import (rnrs) (archive))

    ;; extract file "bar.txt" from "foo.zip"
    (call-with-input-archive-file 'zip "foo.zip"
      (lambda (zip-in)
        (do-entry (e zip-in)
          (when (string=? (archive-entry-name e) "bar.txt")
            (call-with-output-file "bar.txt"
              (lambda (out) (extract-entry e out))
               :transcoder #f)))))

    ;; archive "bar.txt" into foo.tar
    (call-with-output-archive-file 'tar "foo.tar"
      (lambda (tar-out)
        (append-entry! tar-out (create-entry tar-out "bar.txt"))))

Following sections use type as a supported archive type. More precisely, if it's a supported archive type then there must be a library named `(archive _type_)`.

### Archive input

Function make-input-archive type input-port

type must be a symbol and supported archive type. input-port must be a binary input port.

Creates an archive input which represents the specified type of archive.

Method next-entry! archive-input

Retrieves next entry of the given archive input. If there is no entry, then it returns #f.

Macro do-entry (entry archive-input) body ...
Macro do-entry (entry archive-input result) body ...

Convenient macro. Iterates the given archive-input's entries.

The macro is expanded like this;

    (do ((_entry_ (next-entry! _archive-input_) (next-entry! _archive-input_)))
        ((not _entry_) _result_)
      _body_ ...)

If the first form is used, then result is #t.

Method extract-entry entry output-port

Extract the given archive entry entry to binary output port output-port.

Function extract-all-entries archive-input :key (destinator archive-entry-name) (overwrite #f)

Convenient function. Extracts all entries in the given archive-input to the file specified by destinator.

The keyword argument destinator must be a procedure which accepts one argument, archive entry, and return a string represents the file/directory path.

The keyword argument overwrite is #t, then it overwrites the file. If it is #f and there is a file, then it raises an error.

Method finish! archive-input

Finalize the given archive input.

Function call-with-input-archive archive-input proc

archive-input must be an archive input. proc must be a procedure which accepts one argument.

Call the proc with archive input and returns the result of the proc.

The archive-input is finalized by `finish!`.

Function call-with-input-archive-port type input-port proc

Creates an archive input with type and input-port, then call `call-with-input-archive`.

Function call-with-input-archive-file type file proc

Open file binary input port with given file and call `call-with-input-archive-port`.

### Archive output

Function make-output-archive type output-port

type must be a symbol. output-port must be a output port.

Creates an archive output which represents the specified type of archive.

Method create-entry archive-output file

Creates an archive entry from the given file.

For implementing user defined archive;

This method is defined like following on the interface library:

    (define-method create-entry ((out <archive-output>) file)
      (create-entry out file file))

So as long as it doesn't have to be distinguished, users don't have to implement this method.

Method create-entry archive-output entry-name file

Creates an archive entry from the given file. The entry's name is entry-name. This is useful when users want to append entry with different name from file name.

Method append-entry! archive-output entry

Appends the given entry to archive-output.

Method finish! archive-output

Finalize the given archive output.

Function call-with-output-archive archive-output proc

archive-output must be an archive output. proc must be a procedure which accepts one argument.

Call the proc with archive input and returns the result of the proc.

The archive-output is finalized by `finish!`.

Function call-with-output-archive-port type output-port proc

Creates an archive output with type and output-port, then call `call-with-output-archive`.

Function call-with-output-archive-file type file proc

Open file binary output port with given file and call `call-with-output-archive-port`.

### Entry accessor

Function archive-entry-name entry

Returns the name of entry.

Function archive-entry-type entry

Returns the type of entry. It is either `file` or `directory`.

### Implementing archive implementation library

To support other archive such as RAR, then you need to create a implementation library.

Library (archive interface)

The library defines all abstract class and method for the generic archive access.

To support foo archive, then the library name must be code{(archive foo)} and it must import `(archive interface)`. So the library code should look like this;

    (library (archive foo)
      (export) ;; no export procedure is needed
      (import (rnrs)
              (close user)
              (archive interface)
              ;; so on
              ...)
      ;; class and method definitions
      ...)

For archiving, the implementation needs to implement following methods and extends following classes;

    make-archive-input, next-entry, extract-entry

    <archive-input> <archive-entry>

For extracting, the implementation needs to implement following methods and extends following classes;

    make-archive-output, create-entry, append-entry!, finish!

    <archive-output> <archive-entry>

NOTE: `<archive-entry>` may be shared between archiving and extracting.

Class <archive-input>

Abstract class of the archive input. This class has the following slot;

source

  Source of the archive. For compatibility of other archive, this should be a binary input port.

Class <archive-output>

Abstract class of the archive output. This class has the following slot;

sink

  Destination of the archive. For compatibility of other archive, this should be a binary output port.

Class <archive-entry>

Abstract class of the archive entry. This class has the following slots;

name

  Entry name.

type

  Entry type. For compatibility of other archive, this must be `file` or `directory`.

Method make-archive-input type (source )
Method make-archive-output type (sink )

Creates an archive input or output. type specifies the archive type. It is recommended to use `eql` specializer to specify.

Method finish! (in )

The `finish!` method for archive input has a default implementation and it does nothing.

Users can specialize the method for own archive input.

The other methods must be implemented as it's described in above section.

## (asn.1) - Abstract Syntas Notation One library

This section describes `(asn.1)` library. The library supports DER and BER formats. We do not describe DER or BER format here.

Library (asn.1)

Top most library of asn.1 procedure collection libraries. There are multiple of related libraries, however we do not mention those because it might be changed in future. So do not use the child libraries directly, use this.

### High level user APIs

Function encode obj :key (encoder der-encode)

obj must be asn.1-object which described below sections.

If you specify keyword argument encoder, it must be generic function which accepts an object and a binary output port respectively.

Encodes given obj to bytevector. If obj contains BER object, the procedure encodes it to BER. This might be changed in future to configure which format this should encode.

If you want to encode to other format such as CER or XER, then you need to implement an encoder. This procedure does not check given arguments type, just pass obj to encoder with binary output port.

Function read-asn.1-object in

in must be binary input port.

Reads asn.1-object from given port. The port must be DER or BER encoded stream otherwise it raises `&assertion`

### Middle level user APIs

This section is incompleted.

Generic make-der-application-specific <boolean> <integer> <bytevector>
Generic make-der-application-specific <integer> <bytevector>
Generic make-der-application-specific <boolean> <integer> <der-encodable>
Generic make-der-application-specific <integer> <der-encodable>

Creates a DER application specific object.

Generic make-der-bit-string <bytevector> <integer>
Generic make-der-bit-string <bytevector>

Creates a DER bit string object.

Generic make-der-bmp-string <bytevector>
Generic make-der-bmp-string <string>

Creates a DER bmp string object.

Generic make-der-octet-string <bytevector>
Generic make-der-octet-string <der-encodable>

Creates a DER octet string object.

Generic make-der-general-string <string>
Generic make-der-general-string <bytevector>

Creates a DER general string object.

Generic make-der-ia5-string <string>
Generic make-der-ia5-string <string> <boolean>
Generic make-der-ia5-string <bytevector>

Creates a DER IA5 string object.

Generic make-der-numeric-string <string>
Generic make-der-numeric-string <string> <boolean>
Generic make-der-numeric-string <bytevector>

Creates a DER numeric string object.

Generic make-der-printable-string <string>
Generic make-der-printable-string <string> <boolean>
Generic make-der-printable-string <bytevector>

Creates a DER printable string object.

Generic make-der-t61-string <string>
Generic make-der-t61-string <bytevector>

Creates a DER T61 string object.

Generic make-der-universal-string <bytevector>

Creates a DER universal string object.

Generic make-der-utf8-string <string>
Generic make-der-utf8-string <bytevector>

Creates a DER UTF8 string object.

Generic make-der-visible-string <string>
Generic make-der-visible-string <bytevector>

Creates a DER visible string object.

Generic make-der-boolean <boolean>
Generic make-der-boolean <bytevector>

Creates a DER boolean object.

Generic make-der-enumerated <bytevector>
Generic make-der-enumerated <integer>

Creates a DER enumerated object.

Generic make-der-integer <integer>
Generic make-der-integer <bytevector>

Creates a DER integer object.

Generic make-der-object-identifier <string>
Generic make-der-object-identifier <bytevector>

Creates a DER OID object.

Generic make-der-sequence
Generic make-der-sequence <der-encodable>
Generic make-der-sequence o ...

Creates a DER sequence object.

If the third form is used, _o_s must be list of `<der-encodable>`.

Generic make-der-set
Generic make-der-set <der-encodable>
Generic make-der-set o ...

Creates a DER set object.

If the third form is used, _o_s must be list of `<der-encodable>`.

Generic make-der-null

Creates a DER null object.

Generic make-der-generalized-time <string>
Generic make-der-generalized-time <bytevector>
Generic make-der-generalized-time <date>

Creates a DER generalized time object.

Generic make-der-utc-time <string>
Generic make-der-utc-time <bytevector>
Generic make-der-utc-time <date>

Creates a DER UTC time object.

Generic make-der-tagged-object <boolean> <integer> <der-encodable>
Generic make-der-tagged-object <integer> <der-encodable>
Generic make-der-tagged-object <integer>

Creates a DER tagged object.

Generic make-der-external <der-object-identifier> <der-integer> <asn.1-object> <der-tagged-object>
Generic make-der-external <der-object-identifier> <der-integer> <asn.1-object> <integer> <der-object>

Creates a DER external object.

Generic make-ber-constructed-octet-string <bytevector>
Generic make-ber-constructed-octet-string l ...

Creates a BER constructed object.

Generic make-ber-application-specific <integer> l ...

Creates a BER application specific object.

Generic make-ber-tagged-object <boolean> <integer> <der-encodable>

Creates a BER tagged object.

Generic make-ber-sequence l ...

Creates a BER sequence object.

_l_s must be list of `<der-encodable>`.

Generic make-ber-set l ...

Creates a BER set object.

_l_s must be list of `<der-encodable>`.

Generic make-ber-null

Creates a BER null object.

### Low level User APIs

This section is incompleted. Here must desribe classes defined in `(asn.1)`library.

## (binary data) - Binary data read/write

Library (binary data)

This library provides yet another binary data structure read/write. The difference between (binary pack) and this is the level of abstraction. This library provides higher abstraction layer of the way how to handle binary data.

Macro define-simple-datum-define name reader writer
Macro define-composite-data-define name reader writer

Defines a macro named name to read binary data by generic method reader and write binary data by writer.

To use defining macros effectively, both forms' reader and _writer_should be the same name.

The first form defines a macro which takes 5 required arguments and optional keyword arguments. Let's say the name is `define-simple`, the reader is `simple-read` and the write is `simple-write`, Then the definition of defined macro would be like this;

Macro define-simple name parents slots read-proc write-proc :key (parent-metaclass )

Defines name class whose parent classes are parents and slots are slots.

read-proc must be a procedure which takes one argument, a input port and return number of slots values.

write-proc must be a procedure which takes number of slots plus 1 arguments. The first one is an output port and the rest are the value of the slots of the defined class' instance.

The keyword argument parent-metaclass is a parent class of the metaclass of this class.

The slots form must be a list of slot definitions which must be followings;

- name

- (name)

- (name default)

The first and second form define a slot which name is name and its initial value is #f. The third form defines a slot which name is _name_and its initial is default.

Note that current implemenation does not handle parent classes slots. This is only for seamless operations with other CLOS class.

The second form defines a macro which takes 3 required arguments and optional keyword arguments. Let's say the name is `define-composite`, the reader is `simple-read` and the write is `simple-write`, Then the definition of defined macro would be like this;

Macro define-simple name parents slots :key (parent-metaclass )

Defines a composite data class named name whose parent classes are parents and slots are slots.

It is similar form with `define-class` however slots must be a list of one of the followings.

- (name type)

- (name type default)

- (name (type count))

- (name (type count) default)

name must be a symbol which represents the slot name.

type can be class name or `eqv?` comparable datum. e.g. keyword.

default can be any object.

count must be a non negative exact integer.

The first form is equivalent with the following form; `(name type #f)`. And the third form is equivalent with the following form; `(name (type count) #f)`.

The first 2 forms defines a datum slot which the datum is read by _reader_passing type and written by writer.

The rest forms defines an array data represented by a vector.

If the type is not defined by neither of the definition forms, then it is users responsibility to define a method which handles the type.

Following is the simple example to show how to use the macros above.

    (import (clos user) (binary data))

    ;; use the same name of reader and writer
    (define-simple-datum-define   define-simple    sample-read sample-write)
    (define-composite-data-define define-composite sample-read sample-write)

    (define-simple <simple> ()
      (a b (c 0))
      (lambda (in) (values (get-u8 in) (get-u8 in) (get-u8 in)))
      (lambda (out a b c) (put-u8 out a) (put-u8 out b) (put-u8 out c)))

    (define-composite <composite> ()
      ((d :byte 1)
       (e (:byte 4) #vu8(1 2 3 4))
       (f <simple>)))

    ;; :byte reader and writer
    (define-method sample-read ((o (eql :byte)) in array-size?)
      (if array-size?
          (get-bytevector-n in array-size?)
          (get-u8 in)))

    (define-method sample-write ((type (eql :byte)) o out array-size?)
      (if array-size?
         (put-bytevector out o)
         (put-u8 out o)))

How to use the defined data structure.

    ;; read as a <composite> object
    ;; "deeeeabc" in ascii
    (define bv #vu8(#x64 #x65 #x65 #x65 #x65 #x61 #x62 #x63))
    (call-with-port (open-bytevector-input-port bv)
      (lambda (in)
        (let ((s (sample-read <composite> in)))
          (slot-ref s 'd) ;; => #\d
          (slot-ref s 'f) ;; => <simple>
          )))

    ;; write <composite> object
    (call-with-bytevector-output-port
      (lambda (out)
        (let* ((s (make <simple> :a 10 :b 20))
               (c (make <composite> :f s)))
          ;; this can be written like this as well (sample-write o out)
          (sample-write <composite> c out))))
    ;; => #vu8(1 1 2 3 4 10 20 0)

## (binary io) - Binary I/O utilities

Library (binary data)

Binary I/O utility. In real world you sometimes want to treat binary port like textual port (e.g. `get-line` for binary port). This library exports those convenient procedures

### Binary I/O

Function get-line in :key eol (transcoder #f)

in must be binary input port.

Reads a bytevector from in until it hits the eol data. _eol_can be multiple length such as `#vu8(#x0d #x0a)`. Default value is `#vu8(#x0a)`If keyword argument transcoder is given, then returning value will be converted to string.

Function put-u16 out v endian
Function put-s16 out v endian
Function put-u32 out v endian
Function put-s32 out v endian

Re-exported procedure from `(sagittarius)` for convenience. See Sagittarius extensions.

Function put-u64 out v endian
Function put-s64 out v endian
Function put-f32 out v endian
Function put-f64 out v endian

out must be binary output port. endian must be a value returned from `endianness` macro.

Write v to out as unsigned/signed 16/32/64 bit integer or 32/64 bit floating number.

Function get-u16 in endian
Function get-s16 in endian
Function get-u32 in endian
Function get-s32 in endian

Re-exported procedure from `(sagittarius)` for convenience. See Sagittarius extensions.

Function get-u64 in endian
Function get-s64 in endian
Function get-f32 in endian
Function get-f64 in endian

in must be binary input port. endian must be a value returned from `endianness` macro.

Read a number from in as unsigned/signed 16/32/64 bit integer or 32/64 bit floating number.

### Chunk buffered port

Default binary input port requires bytevector however if users want to handle bigger data then it would not be suitable. Chunk buffered port is a buffered port which buffer is chunks of bytevector so that it doesn't allocate huge memory.

Function ->chunked-binary-input-port ->chunks :key chunk-size

Creates chunk buffered port.

->chunks must be a procedure which takes one argument, chunk-size. And must return a list of bytevectors which size is chunk-size except the last element.

The keyword argument chunk-size is specified then it must be a positive integer. By default `+default-chunk-size+` is used.

Constant +default-chunk-size+

Default chunk size of chunk buffered port.

Function input-port->chunked-binary-input-port iport :key chunk-size threshold

Creates chunk buffered port from given iport.

iport must be a binary input port.

The keyword argument threshold is specified, it must be a positive integer, then the procedure only reads the number of threshold bytes from iport.

## (binary pack) - Packing binary data

Library (binary pack)

This library provides an interface for packing and unpacking (writing and reading) binary data with template. The functionality is inspired by Industria's `(weinholt struct pack)` library.

Macro pack template args ...

template must be a string.

Construct a bytevector with given args according to the given template. Template characters are described below.

Macro pack! template bv offset args ...

template must be a string.

bv must be a bytevector.

offset must a non-negative exact integer.

Converts given args and put it into bv starting from offset. The conversion is done according to the template string.

The template characters are extensible so following description can only cover predefined characters.

x: padding; c: s8; C: u8; s: s16; S: u16; l: s32; L: u32; q: s64; Q: u64; f: ieee-single; d: ieee-double; ! or >: big-endian; <: little-endian; =: native-endian; u: disable natural alignment; a: enable natural alignment. Whitespace is ignored.

    (pack "!c" 128)

#vu8(128)

    (pack "s" 100)

#vu8(100 0)

    (pack "!s" 100)

#vu8(0 100)

    (pack "!d" 3.14)

#vu8(64 9 30 184 81 235 133 31)

Fields are by default aligned to their natural alignment and NUL bytes are inserted as necessary to have a field's index to be aligned to its size.

    (pack "!xd" 3.14)

#vu8(0 0 0 0 0 0 0 0 64 9 30 184 81 235 133 31)

    (pack "!uxd" 3.14)

#vu8(0 64 9 30 184 81 235 133 31)

Digits in front of the syntax characters means repetition. And `#\*` means indefinite length repetition.

    (pack "3c" 1 2 3)

#vu8(1 2 3)

    (pack "*c" 1 2 3 4)

#vu8(1 2 3 4)

When the macro detects the given template is string, then it tries to expand as much as possible. So it might raises the different condition even if the template strings are the same.

    (pack "3c" 1 2 3 4)

&syntax

    (pack (car '("3c")) 1 2 3 4)

&error
Macro unpack template bv
Macro unpack template bv offset

template must be a string.

Unpack the given bytevector according to the given template and returns the values. The template syntax are the same as `pack!`.

If the second form is used, then unpacking is done from the given offset.

    (unpack "!SS" #vu8(0 1 0 2))

1 2

    (unpack "!SS" #vu8(0 1 0 2 0 3) 1)

2 3

    (unpack "!uSS" #vu8(0 1 0 2 0 3) 1)

256 512
Macro get-unpack port template

template must be a string.

Utility unpacking macro for binary port.

Macro format-size template
Macro format-size template args ...

template must be a string.

Calculate the size of the result bytevector. If the second form is used, then macro can calculate even if the template contains indefinite length syntax `#\*`, otherwise #f is returned.

    (format-size "!xd")

16

    (format-size "!uxd")

9

    (format-size "*c")

    (format-size "*c" 1 2 3 4)

4
Macro define- ** -packer (char arg) ( `pack` expr1 ... ) ( `unpack` expr2 ... )

char must character.

`pack` and `unpack` are syntactic keywords.

Defines packing extension to given char. This macro can not overwrite the predefined characters. ** can be followings;

`s8`, `u8`, `s16`, `u16`, `s32`, `u32`, `s64`, `u64`, `f32`, and `f64`.

    ;; defining char to u8 converter
    (define-u8-packer (#\A v)
      (pack (char->integer v))
      (unpack (integer->char v)))
    (pack "AA" #\a #\b)       ;; => #vu8(97 98)
    (unpack "AA" #vu8(97 98)) ;; => #\a #\b

## (util buffer) - Buffer utilities

Library (util buffer)

This library provides buffer utitlities. Currently, it only provides pre-allocated buffer and its procedures.

### Pre-allocated buffer

Record Type <pre-allocated-buffer>

Parent type of pre-allocated buffer. This library doesn't expose the record constructor for this type.

This type contains `buffer` and `size` fields.

Function pre-allocated-buffer? obj

Returns #t if given obj is a pre-allocated buffer. Otherwise #f.

Function pre-allocated-buffer-buffer buffer

Returns value of `buffer` field of given buffer.

The type of `buffer` field is implementation specific.

Function pre-allocated-buffer-size buffer

Returns value of `size` field of given buffer.

The returning value shall represents how much buffer of the given _buffer_is consumed.

Function pre-allocated-buffer-reset! buffer

Sets 0 to the `size` field of given `buffer`.

### Conditions

Condition &pre-allocated-buffer-overflow

Buffer overflow condition. This is raised when an operation tries to put data exceed the buffer size.

This condition have `data` field which contains overflowing data.

Function pre-allocated-buffer-overflow? obj

Returns #t if given obj is `&pre-allocated-buffer-overflow`condition, otherwise #f.

Function pre-allocated-buffer-overflow-data condition

Retrieves `data` field value of condition.

The condition must be a `&pre-allocated-buffer-overflow` condition.

### Binary pre-allocated buffer

Binary pre-allocated buffer can be used when users don't want to allocate bytevector number of times. This buffer can be used like a bytevector.

Function make-binary-pre-allocated-buffer bv

Creates pre-allocated buffer with given bytevector bv.

The returning value is a subtype of `<pre-allocated-buffer>`.

Function binary-pre-allocated-buffer? obj

Returns #t if given obj is binary pre-allocated buffer, otherwise #f.

#### Operations

Function binary-pre-allocated-buffer-put-u8! binary-buffer u8
Function binary-pre-allocated-buffer-put-u16! binary-buffer u16 endianness
Function binary-pre-allocated-buffer-put-u32! binary-buffer u32 endianness
Function binary-pre-allocated-buffer-put-u64! binary-buffer u64 endianness
Function binary-pre-allocated-buffer-put-s8! binary-buffer s8
Function binary-pre-allocated-buffer-put-s16! binary-buffer s16 endianness
Function binary-pre-allocated-buffer-put-s32! binary-buffer s32 endianness
Function binary-pre-allocated-buffer-put-s64! binary-buffer s64 endianness
Function binary-pre-allocated-buffer-put-f32! binary-buffer f32 endianness
Function binary-pre-allocated-buffer-put-f64! binary-buffer f64 endianness

Appending given integer or flonum to binary-buffer. Setting given values uses the following procedures, respectively:

`bytevector-u8-set!``bytevector-u16-set!``bytevector-u32-set!``bytevector-u64-set!``bytevector-s8-set!``bytevector-s16-set!``bytevector-s32-set!``bytevector-s64-set!``bytevector-ieee-single-set!``bytevector-ieee-double-set!`The endianness is passed to the above procedures if required.

This procedure also updates the `size` field of binary-buffer.

Function binary-pre-allocated-buffer-put-bytevector! binary-buffer bv :optional start count

Appending given bytevector bv to binary-buffer.

Optional arguments start and count specifies from where of bv and how much bytes need to be put. By default, start is 0 and count is `(- (bytevector-length _bv_) _start_)`.

This procedure also updates the `size` field of binary-buffer.

Function binary-pre-allocated-buffer-set-u8! binary-buffer index u8
Function binary-pre-allocated-buffer-set-u16! binary-buffer index u16 endianness
Function binary-pre-allocated-buffer-set-u32! binary-buffer index u32 endianness
Function binary-pre-allocated-buffer-set-u64! binary-buffer index u64 endianness
Function binary-pre-allocated-buffer-set-s8! binary-buffer index s8
Function binary-pre-allocated-buffer-set-s16! binary-buffer index s16 endianness
Function binary-pre-allocated-buffer-set-s32! binary-buffer index s32 endianness
Function binary-pre-allocated-buffer-set-s64! binary-buffer index s64 endianness
Function binary-pre-allocated-buffer-set-f32! binary-buffer index f32 endianness
Function binary-pre-allocated-buffer-set-f64! binary-buffer index f64 endianness

Setting given integer/flonum to binary-buffer. These procedures are anology of the following procedures, respectively:

`bytevector-u8-set!``bytevector-s8-set!``bytevector-u16-set!``bytevector-u32-set!``bytevector-u64-set!``bytevector-s16-set!``bytevector-s32-set!``bytevector-s64-set!``bytevector-ieee-single-set!``bytevector-ieee-double-set!`The endianness is passed to the above procedures if required.

This procedure updates the `size` field of binary-buffer if sum of given index and number of bytes set in the buffer exceeds the size of the buffer.

Function binary-pre-allocated-buffer-set-bytevector! binary-buffer index bv :optional start count

Sets the given bv to binary-buffer at position of index.

Optional arguments start and count specifies from where of bv and how much bytes need to be put. By default, start is 0 and count is `(- (bytevector-length _bv_) _start_)`.

This procedure updates the `size` field of binary-buffer if sum of given index and number of bytes set in the buffer exceeds the size of the buffer.

All above operations may raises an `&pre-allocated-buffer-overflow`, when it tries to exceed the pre-allocated buffer.

Function binary-pre-allocated-buffer-can-store? binary-buffer count :optional position

Returns #t if binary-buffer can store count bytes.

If optional argument position is given, then the procedure check from the position.

Function binary-pre-allocated-buffer-swap! binary-buffer new-buf new-size

Swaps the buffer of binary-buffer with _new-buf_and new-size.

Function binary-pre-allocated-buffer-get-bytevector-n! binary-buffer input-port n :optional position

Reads n bytes from given input-port and store it to binary-buffer.

If optional argument position is given, then the procedure stores from the position.

Function crop-binary-buffer binary-buffer

Returns newly allocated bytevector which contains range of 0 to `size` field value of `buffer` field.

Function ->binary-pre-allocated-buffer-output-port binary-buffer

Converts the given binary-buffer to binary output port.

If port operations try to exceed the pre-allocated buffer, then it raises `&pre-allocated-buffer-overflow`.

## (util bytevector) - Bytevector utility library

Library (util bytevector)

This library provides bytevector utilities which are not provided as builtin procedures such as `bytevector->integer`.

All procedures take bytevector as its arguments.

Function bytevector-xor bv1 bv2 ...
Function bytevector-xor! out bv1 bv2 ...
Function bytevector-ior bv1 bv2 ...
Function bytevector-ior! out bv1 bv2 ...
Function bytevector-and bv1 bv2 ...
Function bytevector-and! out bv1 bv2 ...

Compute exclusive or, logical or and logical and for each given bytevectors, respectively.

The procedures without `!` freshly allocate a new bytevector as it's return value. If the given bytevectors are not the same sized, then the smallest size will be allocated.

The procedures with `!` takes first argument as the storage of the result and return it.

Function bytevector-slices bv k :key (padding #f)

Slices the given bytevector bv into k size and returns a list of bytevectors.

The keyword argument padding is given and it must be a procedure accept one argument, then it will be called when the last chunk of bytevector is not size of k. The procedure should return padded bytevector and it doesn't check the returned value nor it's size so it is caller's responsibility to make sure the returned value is a bytevector and the size is k.

    (bytevector-slices #vu8(1 2 3 4 5 6) 3)

(#vu8(1 2 3) #vu8(4 5 6))

    (bytevector-slices #vu8(1 2 3 4) 3)

(#vu8(1 2 3) #vu8(4))

    ;; the given bytevector bv is #vu8(4)
    (bytevector-slices #vu8(1 2 3 4) 3 :padding (lambda (bv) #vu8(4 5 6)))

(#vu8(1 2 3) #vu8(4 5 6))

    ;; this is valid as well so that bytevector-slices doesn't check the
    ;; return value
    (bytevector-slices #vu8(1 2 3 4) 3 :padding (lambda (bv) #f))

(#vu8(1 2 3) #f)

Function bytevector-split-at* bv k :key (padding #f)

Splits bytevector into 2 bytevectors and returns 2 values of bytevectors.

The first returned bytevector size will be k and its content is given bytevector's value starting from 0 to k - 1. The second returned value is the rest of values of bv.

If size of the given bytevector bv is less than k then the second value of returned bytevector will be empty bytevector.

The keyword argument padding is given and it must be a procedure accept one argument, then it will be called when given bytevector's size is less than k and first returned value will the result of padding.

    (bytevector-split-at* #vu8(1 2 3 4 5) 3)

#vu8(1 2 3) and #vu8(4 5)

    (bytevector-split-at* #vu8(1 2) 3 :padding (lambda (bv) #vu8(1 2 3)))

#vu8(1 2 3) and #vu8()

    (bytevector-split-at* #vu8(1 2) 3 :padding (lambda (bv) #f))

#f and #vu8()

Function ->odd-parity bv :optional (start 0) (end (bytevector-length bv))
Function ->odd-parity! bv :optional (start 0) (end (bytevector-length bv))

Compute odd parity of the given bytevector bv and return the result of bytevector.

If the second procedure is used, then bv will be modified.

Function bytevector<? bv1 bv2 rest ...
Function bytevector>? bv1 bv2 rest ...
Function bytevector<=? bv1 bv2 rest ...
Function bytevector>=? bv1 bv2 rest ...

Comparing given bytevectors.

The comparison is done by comparing the elements of bytevectors from index `0`. The comparison procedures are `<`, `>`, `<=`and `>=`, respectively.

Function bytevector->hex-string bv :key (upper? #t)

Converts given bytevector bv to hex string.

The keyword argument upper? is specified with true value, then the procedures converts to upper case hex values, otherwise lower case.

Function hex-string->bytevector string

Converts given hex string string to bytevector.

Function bytevector->escaped-string bv

Converts given bytevector to string without transcoder.

The conversion is the same as the following code:

    (list->string (map integer->char (bytevector->u8-list bv)))

This procedure is implemented in a memory efficient way.

Function bytevector-reverse! bv :optional (start 0) (end (bytevector-length bv))
Function bytevector-reverse bv :optional (start 0) (end (bytevector-length bv))

Reverse the given bytevector bv.

Optional arguments start and end controls from and until where the procedure reverses the bytevector. end is exclusive.

The `bytevector-reverse!` reverses destructively.

### SRFI-13 convension APIs

#### U8 sets

U8 set is a list of integers which range is in between `0 <= n <= 255`. This is useful to handle bytevectors as if they are ASCII strings.

Function u8? o

Returns #t if given o is an integer in range of `0 <= _o_ <= 255`, otherwise #f.

Function u8-set? o

Returns #t if given o is a list and its all elements satisfy `u8?`. Otherwise #f.

Function u8-set-contains? u8-set u8

u8-set must satisfy `u8-set?`. u8 should satisfy `u8`. The procedure doesn't check if arguments satify this.

Returns #t if given u8-set contains u8.

Function string->u8-set string

Converts given string to list of integers. Given string should only contains in range of ASCII characters but the procedure doesn't check. Thus the procedure may return a list doesn't satify `u8-set?`. It is users' responsibility to pass ASCII string.

Function char-set->u8-set cset

Converts given char-set cset to u8 set. This procedure returns a list that satify `u8-set?` by dropping outside of ASCII characters.

#### Bytevectors as ASCII strings

Function bytevector-fold kons knil bv :optional start end
Function bytevector-fold-right kons knil bv :optional start end

Iterate given bv from start until end. kons is called by each element with result of the kons. The inital value is knil.

This is analogy of fold-left and fold-right.

Function bytevector-take bv n
Function bytevector-take-right bv n

Subtract bytevector bv until index n (exclusive).

The `bytevector-take` takes from left and the `bytevector-take-right`takes from right.

Function bytevector-drop bv n
Function bytevector-drop-right bv n

Drops given bv until index n (exclusive).

The `bytevector-drop` drops from left and the `bytevector-drop-right`drops from right.

Function bytevector-trim bv :optional criterion start end
Function bytevector-trim-right bv :optional criterion start end
Function bytevector-trim-both bv :optional criterion start end

Trims given bytevector bv from left, right and both, respectively.

The optional argument criterion specifies how to trim. By default, it uses whitespaces. `" \r\f\v\n\t"`.

The optional arguments start and end specify from and until where the procedure trims. The default value is 0 for start and the length of given bytevector for end.

Function bytevector-pad bv n :optional (u8 0) start end
Function bytevector-pad-right bv n :optional (u8 0) start end

Pads given bytevector bv with n elements of u8. The `bytevector-pad` pads left side of given bv. The `bytevector-pad-right` pads right side of given bv.

The optional arguments start and end specify from and until where the procedure pads. The default value is 0 for start and the length of given bytevector for end.

Function bytevector-prefix-length bv1 bv2 :optional start1 end1 start2 end2
Function bytevector-suffix-length bv1 bv2 :optional start1 end1 start2 end2

Return the length of the longest common prefix/suffix of the two bytevectors.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-prefix? bv1 bv2 :optional start1 end1 start2 end2
Function bytevector-suffix? bv1 bv2 :optional start1 end1 start2 end2

Returns #t if bv1 is a prefix/suffix of bv2. Otherwise #f.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-index bv criterion :optional start end
Function bytevector-index-right bv criterion :optional start end

Searches through the given bytevector bv from the left (right), returning the index of the first occurrence of an element which satisfies the criterion.

criterion can be a u8 value, a u8 set or a procedure.

If the procedure doesn't find any element satisfies criterion, then returns #f.

Function bytevector-skip bv criterion :optional start end
Function bytevector-skip-right bv criterion :optional start end

Search through the given bytevector bv from the left (right), returning the index of the first occurrence of an element which does not satisfy the criterion.

criterion can be a u8 value, a u8 set or a procedure.

If the procedure doesn't find any element which does not satisfy criterion, then returns #f.

Function bytevector-contains bv1 bv2 :optional start1 end1 start2 end2

Returns index of bv1 where bv2 is found. If bv1 doesn't contain bv2 then returns #f.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv1 and bv2.

Function bytevector-replace bv1 bv2 start1 end2 :optional start2 end2

Returns

    (bytevector-append (bytevector-copy s1 0 start1)
                       (bytevector-copy s2 start2 end2)
                       (bytevector-copy s1 end1 (string-length s1)))

Function bytevector-tokenize bv :optional token-set start end

Split the given bytevector bv into a list of sub bytevectors, where each sub bytevector is a maximal non-empty contigunous sequence of elements from the u8 set token-set.

Optional argument token-set must be a u8 set. By default, it's a list of bytes of ASCII graphical characters.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv.

Function bytevector-filter criterion bv :optional start end
Function bytevector-delete criterion bv :optional start end

Filter the bytevector bv, retaining only those elements that satisfy / do not satisfy the criterion argument.

criterion can be a u8 value, a u8 set or a procedure.

The optional start/end indices restrict the comparison to the indicated sub bytevectors of bv.

## (util concurrent) - Concurrency utilities

Library (util concurrent)

This library provides high level concurrency APIs.

Using low level thread and mutex sometimes causes dead lock or incomprehensible code. This library provides frameworks of common use cases. This library is built on top of SRFI-18.

### Future

Library (util concurrent future)

A sub library of `(util concurrent)`. This library provides future related APIs.

A future is an object that has a task which is a thunk and will be executed in future. In this implementation, future is an interface and its execution is depending on the sub class. The default implementation this library provides uses a thread per future. If users don't have to manage number of threads, then using this is sufficient.

    (import (rnrs) (util concurrent))

    ;; creates 5 futures
    (define futures
      (map (lambda (i) (future (* i i))) '(1 2 3 4 5)))

    ;; wait and retrieve the results
    (map future-get futures)

(1 4 9 16 25)

Record <future>

The interface of all futures.

Function future? obj

Returns #t if given obj is a future object, otherwise #f.

Macro future expr ...
Macro future (class record)expr ...

Creates a future which executes expr. The type of the returning future is record.

The first form is equivalent with the following: `(future (class <simple-future>) _expr ..._)`

Function future-get future

Retrieves the result of the given future.

This procedure waits if the execution of the future isn't finished yet.

Function future-cancel future

Cancels the execution of future.

This procedure may or may not cancel the execution depending on the implementation of future. The `<simple-future>` provides by this library won't disturb the execution. Thus calling this procedure doesn't do anything but changing the future's state.

NOTE: once this procedure is called, then calling `future-get`with future raises a `&future-terminated`.

    (import (rnrs) (util concurrent))

    (define f (future (display "cancelled") (newline)))
    (future-cancel f)
    (future-get f)

&future-terminated

The above example may or may not print `"cancelled"`.

Function future-done? future

Returns #t if given execution of future is finished, otherwise #f.

Function future-cancelled? future

Returns #t if given execution of future is terminated by `future-cancel`, otherwise #f.

Function future-state future

Returns current state of the given future.

The returning state is depending on the implementation of future. Only 2 states are defined in this library, `done` and `terminated`.

`done` is set when `future-get` is called.

`terminated` is set when `future-cancel` is called.

Condition Type &future-terminated

This type describes when a future is terminated but users try to retrieve its result.

Function future-terminated? obj

Returns #t if given obj is object of `&future-terminated`.

Function terminated-future condition

condition must be a `&future-terminated` condition.

Retrieve terminated future from condition.

#### Simple future

Simple future is a future implementation which executes the task on a thread immediately.

Record <simple-future>

Default `<future>` implementation of this library.

Function simple-future? obj

Returns #t if given obj is a simple future, otherwise #f.

Function make-simple-future thunk

Creates a simple future which executes thunk.

### Executor

Library (util concurrent executor)

A sub library of `(util concurrent)`. This library provides executor related APIs.

A executor is an object that executes submitted futures. The idea is taken from `java.util.concurrent` package. The library provides 2 types of executors, thread pool executor and fork join executor. The first one uses thread pool, described below section, and the latter one just creates a thread per task. The following is an example how to use the executors:

    (import (rnrs) (util concurrent))

    ;; creates executor which uses 5 threads and push all tasks
    (define executor
      (make-thread-pool-executor 5 push-future-handler))

    ;; creates 10 futures
    (define futures
      (map (lambda (i)
             (future (class <executor-future>)
               (* i i)))
           '(1 2 3 4 5 6 7 8 9 10)))

    ;; execute futures
    (for-each (lambda (future) (execute-future! executor future)) futures)

    ;; wait/retrieve the results
    (map future-get futures)

(1 4 9 16 25 36 49 64 81 100)

The thread pool executor with `push-future-handler` waits until the previous taskes are finished.

#### Generic Executor APIs

Executor provided by this library is an extensible. So the most commonly used procedures are generic.

Record <executor>

The interface of executor.

This record only has one field, `state`.

Function executor? obj

Returns #t if given obj is an executor, otherwise #f.

Function executor-state executor

Returns `state` field of the executor.

The behaviour of the folowing procedures depend on its implementation.

Function executor-available? executor

Returns #t if the given executor is available, otherwise #f.

Function execute-future! executor future

Executes given future on executor.

Function shutdown-executor! executor

Shutdowns the given executor.

This procedure may or may not affect the managed futures on the executor.

Function executor-submit! executor thunk

Converts thunk to a future and execute it on given executor, then returns the future. This procedure is defined as follows:

    (define (executor-submit! e thunk)
      (let ((f (make-executor-future thunk)))
        (execute-future! e f)
        f))

#### Thread pool executor

Thread pool executor uses `(util concurrent thread-pool)` as its underlying thread managing. So once the threads are created then the thread holds its environment until the executor is shutdown. In other words, if a task changes the dynamic environment, then the next task uses the changed dynamic environment. The following example describes how dynamic environments works on this executor:

    (import (rnrs) (util concurrent) (srfi :39))

    (define *one* (make-parameter 1))

    (define executor (make-thread-pool-executor 1))

    (let ((f1 (make-executor-future (lambda () (*one* 2) 1)))
          (f2 (make-executor-future (lambda () (*one*)))))
      (execute-future! executor f1)
      (future-get f1)
      (execute-future! executor f2)
      (future-get f2))

2

NOTE: parameter objects are thread safe in general, thus if a thread is created per future, then the parameter `*one*` is initialised with the initial value `1` during thread creation.

Record <thread-pool-executor>

Record type of thread pool executor. This record type inherits `<executor>`.

Function thread-pool-executor? obj

Returns #t if given obj is a thread pool executor, otherwise #f.

Function make-thread-pool-executor max-thread :optional reject-handler

Creates a thread pool executor with thread count max-thread.

If optional argument reject-handler is specified, then the specified handler is used. Otherwise, `abort-rejected-handler` is used.

Function thread-pool-executor-pool-size thread-pool-executor

Returns number of futures currently executing on the given thread pool executor.

This number would be greater than the thread count if `push-future-handler`is specified during the executor creation.

Function thread-pool-executor-max-pool-size thread-pool-executor

Returns number of thread count of the given thread pool executor.

Function thread-pool-executor-available? thread-pool-executor

Return #t if the number of executing future is less than the number of thread count.

NOTE: this procedure may return #f even tasks can be pushed to the executor if `push-future-handler` is specified.

Function thread-pool-executor-execute-future! thread-pool-executor future

Executes the given future on thread-pool-executor.

Function thread-pool-executor-shutdown! thread-pool-executor

Shutdown the given thread-pool-executor.

Builtin reject handlers.

Reject handler is a procedure called when thread pool executor is not available to decide how the executor should treat the given future.

Function abort-rejected-handler

Reject the future and raises `&rejected-execution-error`.

This is the default handler.

Function terminate-oldest-handler

Terminates the oldest future.

When this handler is called, the thread which target future is running is also terminated. Thus the dynamic environment is also reset.

Function wait-finishing-handler wait-retry

Creats a reject handler which waits until one of the thread is available.

The wait-retry is a number of retry count. If none of future task is finished by this counter, then `abort-rejected-handler` is called.

Function push-future-handler

Pushes the task to the least used thread.

Condition Type &rejected-execution-error

A condition describes when a future is rejected by an executor.

Function rejected-execution-error? obj

Returns #t if given obj is `&rejected-execution-error` object. Otherwise #f.

Function rejected-future condition
Function rejected-executor condition

condition must be a `&rejected-execution-error` object.

Retrieves the rejected future and executor, respectively.

#### Fork join executor

Fork join executor is an executor which uses fork join pool as its underlying thread pool.

Record <fork-join-executor>

Record type of fork join executor. This record type inherits `<executor>`.

Function fork-join-executor? obj

Returns #t if given obj is a fork join executor, otherwise #f.

Function make-fork-join-executor
Function make-fork-join-executor parallelism
Function make-fork-join-executor parallelism parameter

Creates a fork join executor.

If the second form is used, then it uses the given parallelism as its parallelism.

If the third form is used, then the parameter must be `fork-join-pool-parameter` described in below section and the procedure passes the given parameter to fork join thread pool creation.

Function fork-join-executor-max-thread-count fork-join-executor

Returns max thread count of the given fork-join-executor.

Function fork-join-executor-thread-count fork-join-executor

Returns current active thread count of the given fork-join-executor.

Function fork-join-executor-available? fork-join-executor

Returns `#t`, if the underlying thread pool is not shutdown, otherwise `#f`.

Function fork-join-executor-execute-future! fork-join-executor future

Executes the given future on fork-join-executor.

Function fork-join-executor-shutdown! fork-join-executor

Shutdowns the given fork-join-executor. The procedure also shutdowns the underlying fork join pool.

#### Executor future

An executor future is an future object which can be used on executor.

Record <executor-future>

Record type of `<executor-future>`. This type inherits `<future>`.

Function executor-future? obj

Returns #t if the given obj is an executor future, otherwise #f.

Function make-executor-future thunk

Creates an executor future object.

### Thread pool

Library (util concurrent thread-pool)

A sub library of `(util concurrent)`. This library provides thread pool APIs.

Creating a thread is not cheap on Sagittarius. If users want to reuse threads, then this library can be used.

    (import (rnrs) (util concurrent))

    ;; pooling 5 thread
    (define thread-pool (make-thread-pool 5))

    (for-each (lambda (i) (thread-pool-push-task! thread-pool (lambda () (* i i))))
              '(1 2 3 4 5 6 7 8 9 10))

    ;; waits until all tasks are done
    (thread-pool-wait-all! thread-pool)

    ;; release thread-pool
    (thread-pool-release! thread-pool)

Record type <thread-pool>

Record type of thread pool.

Function thread-pool? obj

Returns `#t` if given obj is a thread-pool, otherwise `#f`.

Function make-thread-pool thread-count :optional error-handler

Creates a thread pool with thread-count of threads.

If the optional argument error-handler is given, it must be a procedure which accept one argument, then the procedure is called when the pushed task raised an error.

Function thread-pool-size thread-pool

Returns number of threads on the given thread-pool.

Function thread-pool-push-task! thread-pool thunk

Push the given thunk to least used thread-pool's thread. And returns the id of the pushed thread. This id can be used to retrive the actual thread calling `thread-pool-thread` procedure.

Function thread-pool-wait-all! thread-pool

Waits all the tasks pushed into the given thread-pool.

The return value of the tasks are discarded.

Function thread-pool-release! thread-pool :optional how

Joins all the thread on the given thread-pool.

If optional argument how is specified `terminate`, then the procedure terminates the thread instead of joining.

NOTE: terminating a thread is very dangerous operation, so don't use casually.

Function thread-pool-thread thread-pool id

Retrieves the pooled thread associated with given id from given thread-pool.

It signals an error if the given id is not a thread id.

Function thread-pool-thread-id thread-pool thread

Retrieves the pooled thread id associated with given thread from given thread-pool. The procedure takes O(n) where n is number of threads managed by the thread-pool. It might be better to use `(thread-pool-current-thread-id)` procedure to retrieve thread id from managed threads.

It signals an error if the given thread is not a managed thread.

NOTE: if the thread is terminated, then the procedure also signals an error.

Function (thread-pool-current-thread-id)

Retrieves thread id of current thread. If the current thread is not a managed thread, then #f is returned.

Function thread-pool-thread-terminate! thread-pool id

Terminates the pooled thread associated with given id and recreate a new thread into thread-pool.

NTOE: this is a dangerous operation. Don't use it casually.

Function thread-pool-thread-task-running? thread-pool id

Returns #t if the given id of thread in the thread-pool is running. Otherwise #f.

Library (util concurrent fork-join-pool)

A sub library of `(util concurrent)`. This library provides fork join pool APIs.

On Sagittarius, fork join pool means work stealing pool. The pool takes core number of threads and it may creates ephemeral threads until it reaches the max thread number.

CAVEAT: The implementation increases threads rather quick, which means it reaches the max thread number very easily if the thread pool receives large number of tasks. This behaviour may change in the near future not to make threads too soon.

Record type <fork-join-pool>

Record type of fork join pool.

Function fork-join-pool? obj

Returns `#t` if the given obj is a fork-join-pool, otherwise `#f`.

Function make-fork-join-pool core-threads :optional parameter

Creates a fork join pool with core thread count of core-threads.

If the optional argument parameter is given, then it must be a fork join pool parameter. The parameter controls creating fork join pool.

Function fork-join-pool-thread-count fork-join-pool

Returns number of threads currently the given fork-join-pool is having.

Function fork-join-pool-max-threads fork-join-pool

Returns max thread number of the given fork-join-pool.

Function fork-join-pool-push-task! fork-join-pool thunk

Pushes the given thunk into the fork-join-pool. The thunk will be executed on the fork-join-pool when there's an available thread.

Function fork-join-pool-wait-all! fork-join-pool :optional timeout

Waits fork-join-pool to finish all tasks. The procedure blocks the calling thread and may not return if there's a task which hanged.

Optional argument timeout specifies the timeout. It can be either an integer represents milliseconds or absolute time.

The procedure returns `#t` if all the core threads are freed. otherwise `#f`. (e.g. timeout)

NOTE: At this moment, this procedure doesn't guarantee the tasks are finished, if it's running on a spawned thread.

Function fork-join-pool-shutdown! fork-join-pool

Shutdowns the given fork-join-pool.
This procedure discards all the threads. After this procedure is called, then the given fork-join-pool is no longer available.

Function fork-join-pool-available? fork-join-pool

Returns `#t` if the given fork-join-pool is available.

### Shared queues

Library (util concurrent shared-queue)

A sub library of `(util concurrent)`. This library provides shared queue APIs.

A shared queue is a queue whose operations are done atomically.

    (import (rnrs) (util concurrent) (srfi :18))

    (define shared-queue (make-shared-queue))

    (define thread
      (thread-start!
        (make-thread
          (lambda ()
            ;; waits until the queue has an element
            (let ((value (shared-queue-get! shared-queue)))
              (* value value))))))

    (shared-queue-put! share-queue 5)

    (thread-join! thread)

25

Record <shared-queue>

Record type of shared queue.

Function shared-queue? obj

Returns #t if given obj is shared queue, otherwise #f.

Function make-shared-queue :optional (max-length -1)

Creates a shared queue.

If optional argument max-length is 0, then the queue can be used as synchronised queue. If the value is positive number, then the queue can only have specified number of elements. If it overflows, then it waits until the number of elements is less than max-length.

Function shared-queue-empty? shared-queue

Returns #t if the number of elements inside of shared-queue is 0. Otherwise #f.

Function shared-queue-size shared-queue

Returns the number of elements inside of shared-queue.

Function shared-queue-max-length shared-queue

Returns max length of shared-queue.

Function shared-queue-overflows? shared-queue count

Returns #t if putting count of element into _shared-queue_overflows. Otherwise #f.

Function shared-queue-get! shared-queue :optional (timeout #f) (timeout-val #f)

Retrieves the first element from shared-queue.

If the queue is empty and optional argument timeout is #f, then this procedure waits until the queue gets something.

If the optional argument timeout is specified, then the procedure only waits specified amount of time. timeout can be either integer or time object defined in SRFI-19. If the queue didn't get any object within the timeout, then timeout-val is returned.

Function shared-queue-put! shared-queue obj :optional (timeout #f) (timeout-val #f)

Puts obj into shared-queue and returns obj.

If the queue has `max-length` and overflows, then it wait until it's available.

If the optional argument timeout is specified, then the procedure only waits specified amount of time. timeout can be either integer or time object defined in SRFI-19. If the queue didn't get any object within the timeout, then timeout-val is returned.

Function shared-queue-remove! shared-queue obj :optional (= equal?)

Removes the given obj from the shared-queue. The procedure returns #t if obj is removed, otherwise #f.

Optional argument =, must be a comparison procedure, specifies how to compare the element of the shared-queue and given obj. Default value is `equal?`.

Function shared-queue-clear! shared-queue

Clears all element inside of shared-queue.

Function shared-queue-find shared-queue pred

Finds an elements which satisfies pred. This operations locks the given shared-queue.

Function shared-queue-locked? shared-queue :optional (wait? #f)

Returns #t if the given shared-queue is locked by other thread, otherwise #f.

If the optional argument wait? is given, then the procedure waits until the queue is available and returns #f.

### Actor

Library (util concurrent actor)

A sub library of `(util concurrent)`. This library provides actor model like APIs.

An actor is an object which contains thread, input receiver and output sender. This is based on the Actor model. Communication between an actor and outside of the actor can only be done via input receiver or output sender. From here, we call them channel. The following is a simple bank account example using actor.

    (import (rnrs) (util concurrent actor) (match))

    (define (open-account initial-amount)
      (define balance initial-amount)
      (make-shared-queue-channel-actor
       (lambda (input-receiver output-sender)
         (let loop ()
           (match (input-receiver)
    	 (('withdrow how-much)
    	  (if (< balance how-much)
    	      (output-sender "invalid amount")
    	      (begin
    		(set! balance (- balance how-much))
    		(output-sender (cons how-much balance))))
    	  (loop))
    	 (('deposite a)
    	  (if (negative? a)
    	      (output-sender "invalid amount")
    	      (begin
    		(set! balance (+ balance a))
    		(output-sender (cons 0 balance))))
    	  (loop))
    	 (('close) #t)
    	 (else "invalid message"))))))

    (define client (open-account 1000))

    (actor-send-message! client '(withdrow 100))
    (actor-send-message! client '(deposite 100))
    (actor-send-message! client '(close))

    (actor-receive-message! client) ;; => (100 . 900)
    (actor-receive-message! client) ;; => (0 . 1000)

Function actor? obj

Returns #t if the given obj is an actor, otherwise #f.

Function make-shared-queue-channel-actor task
Function make-shared-priority-queue-channel-actor task compare

Creates actors with shared-queue or shared-priority-queue as underlying channel implementation, respectively.

If the `make-shared-priority-queue-channel-actor` is used, then the compare must be a procedure which takes 2 arguments and returns the comparison result of given 2 arguments. The value should be, -1, 0 or 1.

task must be an procedure accepts 2 argument, input-receiver and output-sender. The procedures' signatures are the followings:

Function input-receiver :optional timeout timeout-val
Function output-sender messge :optional timeout timeout-val

The input-receiver receives a message from outside of the actor.

The output-sender sends a message message to outside of the actor.

Messages can be sent to an actor via `actor-send-message!`, and be received from an actor via `actor-receive-message!`.

The optional arguments timeout and timeout-val are given, it shall behave the same as `shared-queue-get!` or `shared-queue-put!`.

Function actor-send-message! actor message :optional timeout timeout-val

Sends the given message to the actor. The operation may block the caller thread depending on the underlying channel implementation.

If optional argument timeout and timeout-val are given, it shall behave the same as `shared-queue-put!`.

Function actor-receive-message! actor :optional timeout timeout-val

Receives a message from given actor. The operation may block the caller thread depending on the underlying channel implementation.

If optional argument timeout and timeout-val are given, it shall behave the same as `shared-queue-get!`.

Function actor-running? actor

Return #t if the given actor is running, otherwise #f.

Function actor-wait! actor :optional timeout timeout-val

Waits until the given actor is finished.

The optional arguments works the same as `thread-join!`.

Function actor-terminate! actor

Terminates the given actor.

NOTE: This operation is not safe. It is users' responsibility to release resource if it's needed.

Library (util concurrent completable-future)

A sub library of `(util concurrent)`. This library provides Java's CompletableFuture like interface

Function thunk->future thunk
Function thunk->future thunk executor

Provide a future whose value supplier is the thunk.

If the second form is used, then the execution will be done by the given executor otherwise `*completable-future:default-executor*`will be used.

Function future-map proc future ...

proc must accept the same number of arguments as the given futures

Apply the procedure proc to the result of the futures. And return a newly created future.

These procedures return immediately and the computation of proc will be done in some future.

Function future-map/executor executor proc future ...

The same as `future-map`, the only diffrence is that it takes exeuctor as its execution environment.

Function future-flatmap proc future ...

proc must accept the same number of arguments as the given futures, and return a future.

Apply the procedure proc to the result of the futures. And return a newly created future which returns the result of the future returned by the proc.

These procedures return immediately and the computation of proc will be done in some future.

Function future-flatmap/executor executor proc future ...

The same as `future-flatmap`, the only diffrence is that it takes exeuctor as its execution environment.

Function future-guard proc future

Guards the future and apply the raised condition to proc.

    (future-get (future-guard (lambda (e) 'ok)
                              (thunk->future (lambda () (raise 'boo)))))

'ok

These procedures return immediately and the computation of proc will be done in some future.

### Atomic

Library (util concurrent atomic) 0.9.13

A sub library of `(util concurrent)`. This library provides atomic operations implemented atop `(sagittarius atomic)`

The below procedures and constants are re-exported from `(sagittarius atomic)`.

Function atomic?
Function make-atomic
Function atomic-flag?
Function make-atomic-flag
Function atomic-fixnum?
Function make-atomic-fixnum
Function atomic-pair?
Function make-atomic-pair
Function memory-order?
Constant *memory-order:relaxed*
Constant *memory-order:consume*
Constant *memory-order:acquire*
Constant *memory-order:release*
Constant *memory-order:acq-rel*
Constant *memory-order:seq-cst*
Function atomic-load
Function atomic-store!
Function atomic-fixnum-load
Function atomic-fixnum-store!
Function atomic-fixnum-add!
Function atomic-fixnum-sub!
Function atomic-fixnum-ior!
Function atomic-fixnum-xor!
Function atomic-fixnum-and!
Function atomic-exchange!
Function atomic-fixnum-exchange!
Function atomic-compare-and-swap!
Function atomic-fetch-compare-and-swap!
Function atomic-fixnum-inc!
Function atomic-fixnum-dec!
Function atomic-thread-fence

#### Lock free queue

Lock free queue is a queue whose operation is atomic without locking. The implementation uses DCAS, a.k.a. `atomic-pair`.

The procedures are experimental, means it's subjected to change.

Function lock-free-queue? obj

Returns `#t` if the given obj is lock free queue, otherwise `#f`.

Function make-lock-free-queue :optional ( lis `'()` )

Creates a lock free queue whose initial elements are the given `_lis_`

Function list->lock-free-queue lis

Creates a lock free queue whose initial elements are the given `_lis_`

Function lock-free-queue element s ...

Creates a lock free queue whose initial elements are the given `_element_`s

Function lock-free-queue-size ( lfq `lock-free-queue?` )

Returns the current size of the given lock free queue lfq.

Function lock-free-queue-empty? ( lfq `lock-free-queue?` )

Returns `#t` if the given lock free queue is empty, otherwise `#f`.

Function lock-free-queue-push! ( lfq `lock-free-queue?` ) e

Pushes the given e into the given lock free queue lfq.

Function lock-free-queue-pop! ( lfq `lock-free-queue?` ) :optional (fallback `#f` )

Retrieves an element from the back of the given lock free queue lfq.

It returns the fallback if the queue is empty.

Function lock-free-queue-get! ( lfq `lock-free-queue?` ) :optional (fallback `#f` )

Retrieves an element from the front of given lock free queue lfq.

It returns the fallback if the queue is empty.

Function lock-free-queue->list ( lfq `lock-free-queue?` )

Returns all elements of the given lfq as a list.

Function lock-free-queue-remove! ( lfq `lock-free-queue?` ) e :optional ( = `equal?` )

Removes the given element e from the lfq and returns the removed elements.

Optional argument = specifies how to compare.

Function lock-free-queue-remp! ( lfq `lock-free-queue?` ) pred

Removes all the element satisfying the given pred and returns the removed elements.

## (crypto) - Cryptographic library

### Deprecated library

This library is deprecated, please consider to use Cryptographic libraries instead.

This documentation does not describe cryptography itself. For example, it does not describe what initial vector is and how long it must be. So users must know about cryptography's this library supports.

This library uses `libtomcrypt`'s functionalities. The library is public domain. Thank you for the great library.

Note: the `libtomcrypt` is a huge cryptographic library and I am not so good with cryptographics, so the `(crypto)` library is not totally tested. Just the functionalities which I usually use are tested. If you find a bug or wrong documentation, pleas report it.

Library (crypto)

This library is the top most library, it exports all the other libraries procedures. Users must import only this and not to use the others.

`(crypto)` library supports both symmetric cryptography and public/private key mechanism. For public/private key, it only supports RSA for now.

Function crypto-object? obj

Returns #t if obj is `crypto-object`.

`crypto-object` can be either `cipher` or `key`.

### Cipher operations

Function make-cipher type key mode :key (mode-parameter #f) :allow-other-keys :rest options

Creates a cipher object.

type must be known cryptographic algorithm. Currently, `(crypto)`library exports the algorithm below.

The symmetric key algorithms.

Constant Blowfish
Constant X-Tea
Constant RC2
Constant RC5-32/12/b
Constant RC6-32/20/b
Constant SAFER+
Constant SAFER-K64
Constant SAFER-SK64
Constant SAFER-K128
Constant SAFER-SK128
Constant AES
Constant AES-128
Constant AES-192
Constant AES-256
Constant Twofish
Constant DES
Constant DES3
Constant DESede
Constant CAST5
Constant CAST-128
Constant Noekeon
Constant Skipjack
Constant Khazad
Constant SEED
Constant KASUMI
Constant Camellia

`AES-128`, `AES-192` and `AES-256` are fixed key size AES algorithms. `AES` allows key size of 16, 24 or 32 bytes, however, fixed sized version only accepts 16 for `AES-128`, 24 for `AES-192` and 32 for `AES-256`.

The public key algorithm

Constant DSA
Constant ECDSA
Constant RSA

key must be a key object which will be created by key generate procedures described below.

mode specifies the symmetric cipher's encryption and description mode. If the cipher type is public key cipher, it will be ignored. Some modes require initial vector iv. The possible mods are below.

Constant MODE_ECB
Constant MODE_CBC
Constant MODE_CFB
Constant MODE_OFB
Constant MODE_CTR
Constant MODE_GCM

The keyword argument mode-parameter is specified, it must be a mode parameter object, then the object will be parsed properly by the cipher.

Function cipher-keysize cipher test

Returns given cipher type's recommended keysize.

cipher must cipher object created by `cipher` procedure.

test must be fixnum.

If test is too small for the cipher, it will raise an error.

Note: this procedure is for helper. It is designed to use check keysize you want to use.

Function cipher? obj

Returns #t if the obj is cipher object.

Function cipher-encrypt cipher pt

cipher must be a cipher object.

pt must be a bytevector.

`encrypt` encrypts given plain text pt according to the given cipher.

Function cipher-encrypt/tag cipher pt :key tag-size

Similar with `cipher-encrypt`. The difference is that this procedure returns 2 values, encrypted pt and calculated tag if the given cipher supports authentication.

If the keyword argument tag-size is specified and must be an integer, then the returning tag has the specified size. If the cipher supports less size than the specified size, then the remaining tag contains unspecified value. To retrieve the maximum length of tag, use `cipher-max-tag-size`.

Function cipher-decrypt cipher ct

cipher must be a cipher object.

ct must be a bytevector.

`decrypt` decrypts given encrypted text ct according to the given cipher.

Function cipher-decrypt/tag cipher ct :key tag-size

Similar with `cipher-decrypt`. The difference is that this procedure returns 2 values, decrypted ct and calculated tag if the given cipher supports authentication.

If the keyword argument tag-size is specified and must be an integer, then the returning tag has the specified size. If the cipher supports less size than the specified size, then the remaining tag contains unspecified value. To retrieve the maximum length of tag, use `cipher-max-tag-size`.

Function cipher-decrypt/verify cipher ct tag

Similar with `cipher-decrypt`. The difference is that this procedure validates the calculated tag. If the given tag and calculated tag are not the same, then `&decrypt` is raised.

NOTE: if the tag is *not* calculated by the cipher, then this procedure always raises an error.

Function cipher-max-tag-size cipher

Returns the maximum length of tag size.

If the given cipher does not support authentication tag, then returning value is `0`.

Function cipher-update-aad! cipher aad

Updates the additional authentication data.

Function cipher-tag! cipher dst

dst must be a bytevector.

Retrieves the authentication tag from given cipher.

NOTE: this procedure must be called after either `cipher-encrypt` or `cipher-decrypt`. Otherwise the filled value is unspecified.

Function cipher-tag cipher :key size

Retrieves the authentication tag from given cipher.

If the keyword argument size is specified, then the returning bytevector has the size length, otherwise maximum tag length.

NOTE: this procedure must be called after either `cipher-encrypt` or `cipher-decrypt`. Otherwise the filled value is unspecified.

Function cipher-signature public-cipher data :optional opt

public-cipher must be a cipher object created with public/private key algorithm.

data must be a bytevector.

Signs given data. This procedure is just a wrapper for the real implementations. Currently Sagittarius supports only RSA sign.

opt can specify the signer behaviour. Default supported RSA cipher can accept keyword argument encode.

encode specifies the encoder. The default encoder is `pkcs1-emsa-pss-encode`. And the rest keyword arguments will be passed to the encoder. Supported encoders are described below.

The following shows how to implement `SHA256WithRSA` signature

    ;; Importing a RSA private key.
    (define private-key (import-private-key RSA #vu8(...)))

    (define signer (make-cipher RSA private-key))
    (cipher-signature signer #vu8() :encode pkcs1-emsa-v1.5-encode :hash SHA-256)

Function cipher-verify public-cipher M S :optional opt

public-cipher must be a cipher object created with public/private key algorithm.

M and S must be bytevectors.

M is master message which will be compared with encoded message.

S is signed message.

The `verity` procedure verifies two messages.

opt can specify the verifier behaviour. Default supported RSA cipher can accept keyword argument verify.

verify specifies the verifier. The defaule verifier is `pkcs1-emsa-pss-verify`. And the rest keyword arguments will be passed to verifier. Supported verifiers are described below.

### Mode parameters

Mode parameters are pareters which can be used by specified mode. For example, `iv-parameter` is a parameter contains an IV.

Function mode-parameter? obj

Returns #t if the given obj is a mode parameter, otherwise #f.

Function make-composite-parameter parameters ...

Creates a composite mode parameter.

A composite parameter can hold multiple parameters.

Record Type <iv-paramater>

Record type for initial vector (IV) parameter.

Function make-iv-paramater iv

iv must be a bytevector or #f.

Creates an IV mode parameter.

IV is required by some modes. e.g. `MODE_CBC`.

Record Type <ctr-paramater>

Record type for counter mode parameter.

This parameter is a subclass of `<iv-parameter>`.

Function make-ctr-paramater iv :key (rounds 0) (mode CTR_COUNTER_BIG_ENDIAN)

Creates a counter mode parameter. This is used by `MODE_CTR`.

iv is passed to parent constructor.

The followings are description of keyword parameters.

rounds specify how many times the cipher rounds the key.

ctr-mode specifies counter mode. The possible mode is blow.

Constant CTR_COUNTER_LITTLE_ENDIAN
Constant CTR_COUNTER_BIG_ENDIAN
Record Type <rfc3686-paramater>

Record type for AES-CTR mode parameter defined in RFC 3686.

This parameter is a subclass of `<ctr-parameter>`.

Function make-rfc3686-paramater iv nonce :key (rounds 0) (mode CTR_COUNTER_BIG_ENDIAN)

Creates RFC3686 mode parameter.

Record Type <padding-paramater>

Record type for padding parameter.

Function make-padding-paramater padder

Creates a padding mode parameter.

padder must be an procedure such as `pkcs5-padder`.

### Key operations

Generic generate-secret-key (type ) (key )

type must be one of the supported symmetric algorithm.

key must be a bytevector and its length must satisfy the keysize which the given algorithm requires.

Returns a sercret key object.

Generic generate-key-pair (type ) . options

type is for despatch. For default implementation, it must be `RSA`.

Generates a key pair object.

Default implementation supports RSA key geneartion and options can be keyword arguments described below.

size keyword argument is decides key length. Default value is 1024.

prng keyword argument is given, it will be passed to `random-prime`. For more detail, see (math random) library. Default value is `(secure-random RC4)`.

e keyword argument is an exponent. Usually it does not have to be specified with other number. Default value is 65537.

Generic generate-private-key type . options

type is for despatch. For default implementation, it must be `RSA`.

Returns private key object.

Default RSA implementation options can be these arguments.

modulus

  The private key's modulus

private-exponent

  The private key's exponent

public-exponent

  keyword argument. Used for CRT private key object.

p

  keyword argument. Used for CRT private key object.

q

  keyword argument. Used for CRT private key object.

Function generate-public-key type :optional opt

type is for despatch. For default implementation, it must be `RSA`.

Returns public key object.

Default RSA implementation opt can be these arguments.

modulus

  The public key's modulus

exponent

  The public key's exponent

Function keypair? obj

Returns #t if given obj is keypair object, otherwise #f

Function keypair-private keypair

Returns private key from keypair

Function keypair-public keypair

Returns public key from keypair

Function key? obj

Returns #t if given obj is key object, otherwise #f

Class <private-key>

CLOS class of private key object.

Class <public-key>

CLOS class of public key object.

Function private-key? obj

Returns #t if given obj is private key object, otherwise #f

Function public-key? obj

Returns #t if given obj is public key object, otherwise #f

Function split-key key :optional (count 3) (prng (secure-random RC4))

key must be a bytevector and plain key.

Splits the given key to count components and returns _count_values as key components.

The return values might be different each time.

Function combine-key-components component1 components ...
Function combine-key-components! result component1 components ...

Renaming export of `bytevector-xor` and `bytevector-xor!`respectively.

For more detail, see (util bytevector).

### PKCS operations

The procedures described in this section is implemented according to PKCS#1. I don't have any intend to describe functionality. If you need to know what exactly these procedures do, please see the PKCS#1 document.

Function pkcs5-padder bv block-size padding?

bv must be a bytevector.

block-size must be a non negative exact integer.

padding? must be a boolean.

Pads or Unpads paddings from bv according to PKCS#5.

If padding? is #t, the procedure will pad. otherwise it will unpad.

Function pkcs-v1.5-padding prng key block-type

prng must be prng object. See (math random).

key must be either private or public key object.

block-type must be one of these.

Constant PKCS-1-EME
Constant PKCS-1-EMSA

Returns a padding procedure. The procedure signature is the same as pkcs5-padder.

Function pkcs1-emsa-pss-encode m em-bits _

_ :key (hash `(hash-algorithm SHA-1)` ) (mgf mgf-1) (salt-length #f) _ _ (prng `(secure-random RC4)` )

m must be a bytevector.

em-bits must be non negative exact integer.

Encodes given message m according to the PKCS#1 section 9.1.1.

The keyword arguments specified some behaviour.

hash specifies the hash algorithm. For more detail, see (math hash) library.

mgf specifies mask generation procedure.

Note: PKCS#1 only specifies MGF-1.

salt-length specifies salt's length. If it's #f encoder does not use salt.

prng is a pseudo random see (math random).

Function pkcs1-emsa-pss-verify m em-bits _

_ :key (hash `(hash-algorithm SHA-1)` ) (mgf mgf-1) _ _ (prng `(secure-random RC4)` )

m must be a bytevector.

em-bits must be non negative exact integer.

Verify given message m according to the PKCS#1 section 9.1.1.

Other keyword arguments are the same as `pkcs1-emsa-pss-encode`.

Function mgf-1 mgf-seed mask-length hasher

mgf-seed must be a bytevector.

mask-length must be a non negative exact integer.

hasher must be a hash algorithm. See (math random).

Creates a mask bytevector, according to PKCS#1 MGF-1.

Function pkcs1-emsa-v1.5-encode m em-bits :key (hash `(hash-algorithm SHA-1)` )

m must be a bytevector.

em-bits must be non negative exact integer.

Encodes given message m according to the PKCS#1 section 9.2.

Other keyword arguments are the same as `pkcs1-emsa-pss-encode`.

Function pkcs1-emsa-v1.5-verify m em-bits :key (hash `(hash-algorithm SHA-1)` )

m must be a bytevector.

em-bits must be non negative exact integer.

Verify given message m according to the PKCS#1 section 9.2. Other keyword arguments are the same as `pkcs1-emsa-pss-encode`.

### Key wrapping

Function make-aes-key-wrap wrapping-key :key iv

Returns AES key wrapping procedure which accepts one argument of bytevector to be wrapped.

The returning procedure wraps the given bytevector with AES Key Wrap algorithm specified by NIST or RFC 3394.

The keyword argument iv specifies initial value (IV) for data integrity. The default value is `#vu8(#xa6 #xa6 #xa6 #xa6 #xa6 #xa6 #xa6 #xa6)`specified by the specification.

Function make-aes-key-unwrap wrapping-key :key iv

Returns AES key unwrapping procedure which accepts one argument of bytevector to be unwrapped.

The returning procedure wraps the given bytevector with AES Key Wrap algorithm specified by NIST or RFC 3394.

The keyword argument iv specifies initial value (IV) for data integrity. The default value is `#vu8(#xa6 #xa6 #xa6 #xa6 #xa6 #xa6 #xa6 #xa6)`specified by the specification.

### Cryptographic conditions

Condition Type &crypto-error
Function crypto-error? obj

Subcondition of `&error`.

Base condition type of all cryptographic conditions.

Condition Type &encrypt-error
Function encrypt-error? obj
Function condition-encrypt-mechanism encrypt-error

This condition will be raised when encrypt operation is failed.

Condition Type &decrypt-error
Function decrypt-error? obj
Function condition-decrypt-mechanism decrypt-error

This condition will be raised when decrypt operation is failed.

Condition Type &encode-error
Function encode-error? obj

This condition will be raised when encoding operation is failed.

Condition Type &decode-error
Function decode-error? obj

This condition will be raised when decoding operation is failed.

Function raise-encrypt-error who message mechanism :optional irritants

who, message and irritants are the same as `assertion-violation`.

mechanism should be a name of cryptographic algorithm.

Raises `&encrypt-error`.

Function raise-decrypt-error who message mechanism :optional irritants

who, message and irritants are the same as `assertion-violation`.

mechanism should be a name of cryptographic algorithm.

Raises `&decrypt-error`.

Function raise-encode-error who message :optional irritants

who, message and irritants are the same as `assertion-violation`.

Raises `&encode-error`.

Function raise-decode-error who message :optional irritants

who, message and irritants are the same as `assertion-violation`.

Raises `&decode-error`.

Condition Type &integrity-error
Function integrity-error? obj

Subcondition of `&crypto-error`This condition will be raised when key unwrap failed due to the integrity check error.

### Creating own cipher

If Sagittarius does not support sufficient cipher algorithm for you, then you can write own cipher such as DSA. For this purpose, you might need to know how this library works. It will be described the bottom of this section. If you just want to create a new cipher, you just need to follow the example.

    (import (rnrs) (crypto) (clos user) (sagittarius))

    (define (sample-encrypt pt key) pt)
    (define (sample-decrypt ct key) ct)

    (define-class <sample-cipher-spi> (<cipher-spi>) ())
    (define-method initialize ((o <sample-cipher-spi>) initargs)
      (slot-set! o 'name 'sample)
      (slot-set! o 'key #f)
      (slot-set! o 'encrypt sample-encrypt)
      (slot-set! o 'decrypt sample-decrypt)
      (slot-set! o 'padder #f)
      (slot-set! o 'signer (lambda _ #vu8()))
      (slot-set! o 'verifier (lambda _ #t))
      (slot-set! o 'keysize (lambda _ 0)))

    (define sample :sample)
    (register-spi sample <sample-cipher-spi>)
    ;; test sample-cipher
    (define sample-cipher (cipher sample #f))
    (define message (string->utf8 "sample message"))
    (let ((encrypted-message (encrypt sample-cipher message)))
      (decrypt sample-cipher encrypted-message))
    ;; -> #vu8(115 97 109 112 108 101 32 109 101 115 115 97 103 101)

The sample code actually does nothing. If you want to see real working code, `ext/crypto/crypto/key/rsa.scm` might be a good example for you.

The basic idea of creating a new cipher is that you need to define own subclass of `<cipher-spi>` and register it.

Class <cipher-spi>

The base class for all SPI (Service Provider Interface).

Subclass must set these slots.

encrypt

  The value must be a procedure which takes 2 arguments.

decrypt

  The value must be a procedure which takes 2 arguments.

NOTE: Default symmetric key ciphers use `pkcs5-padder` which takes 3 arguments, bytevector, block-size and padding flag. This is because the procedure can be used by multi ciphers. And custom cipher must know its own block size.

These slots are optional.

name

  Describe the cipher.

key

  The value will be passed to `encrypt`, `decrypt`, `sign` and `verify` to be used.

signer

  A procedure for signing. The given procedure must accept at least 2 arguments.

verifier

  A procedure for verifying. The given procedure must accept at least 3 arguments.

keysize

  A procedure to get recommended keysize of this cipher. The given procedure must accept 1 argument.

padder

  The value must be #f or a procedure which takes 2 arguments.

update-aad

  The value must be #f or a procedure which takes 1 arguments. This is called when `cipher-update-aad!` is called.

tag

  The value must be #f or a procedure which takes 1 arguments. This is called when `cipher-tag!` is called.

tagsize

  The value must be an integer. This represents the maximum length of authentication tag.

NOTE: Even required slots, Sagittarius does not check if it's set or not.

During its initialisation, the initargs (the second argument of the `initialize` method) takes at least 3 arguments, key, `:mode-parameter` keyword and parameter passed to `make-cipher`. The rest of other arguments are also passed if exist.

Function cipher-spi? o

Returns #t if the given object o is a cipher SPI. Otherwise #f.

Function register-cipher-spi mark spi

Register custom cipher SPI.

mark can be any thing which returns #t then compared by `equal?`spi must be subclass of `<cipher-spi>`NOTE: We recommend to make mark the same as example code does and export the registered mark. And the mark must be unique enough not to overwrite existing SPI names.

e.g. `:rsa`, `:dsa` and `:ecdsa` are already used for RSA, DSA and ECDSA

The concept of this SPI is influenced by Java's JCE. The toplevel of cipher is just a wrapper for real implementaion (SPI). When a cipher is created, the `cipher` procedure actually creates an instance of SPI class and set it to the cipher object. So users need not to know about the implementation and if the implementation supply default parameter then users even can use it by default.

This is the class hierarchy of these crypto objects.

    + <top>
      + <crypto>
          + <cipher>
          + <cipher-spi>
              + <builtin-cipher-spi> <- default implementations of symmetric keys.
              + <rsa-cipher-spi>     <- default RSA implementation
          + <key>
              + <symmetric-key>
                  + <builtin-symmetric-key> <- default symmetric key. ex. DES
              + <asymmetric-key>
                  + <private-key>
                      + <rsa-private-key>
                          + <rsa-private-crt-key>
                  + <public-key>
                      + <rsa-public-key>

The `<cipher>` and `builtin-` prefixed classes can not have any subclass.

### Backward compatibility

The following procedures are kept for backward compatibility.

- `cipher` - Use `make-cipher` instead.

- `encrypt` - Use `cipher-encrypt` instead.

- `decrypt` - Use `cipher-decrypt` instead.

- `sign` - Use `cipher-signature` instead.

- `verity` - Use `cipher-verify` instead.

- `register-spi` - Use `register-cipher-spi` instead.

## (dbi) - Database independent access layer

Library (dbi)

This library provides database independent access procedures. The database specific operations are provided in database driver (DBD) libraries.

Following example describes how to query a database using `(dbd odbc)`DBD library.

    (import (dbi))
    (define conn (dbi-connect "dbi:odbc:server=XE"
                              :username "username"
                              :password "password"))
    (let* ((query (dbi-prepare conn "SELECT * FROM table WHERE id > ?"))
           (result (dbi-execute-query! query 1)))
      (do ((row (dbi-fetch! result) (dbi-fetch! result)))
          ((not row))
       (vector-for-each (lambda (col) (print col)) row)))

There is nothing specific to the underlying database system except the argument `"dbi:odbc:server=XE"` passed to `dbi-connect`, from which `dbi` library figures out that it is an access to `odbc`, loads `(dbd odbc)` library and let it handle the specific operations.

If you want to use other database named boo, then you just need to pass `"dbi:_boo_:_parameter_"` to `dbi-connect` instead. As long as you have `(dbd boo)` installed then everything stays the same.

### DBI user APIs

#### Database connection

Function dbi-connect dsn . rest

Connects to a database using a data source specified by dsn (data source name). dsn is a string with the following syntax.

`dbi:_driver_:_options_`driver part names a specific driver. You need to have a corresponding driver library, `(dbd _driver_)`, installed in your system.

Interpretation of the options part is up to the driver. Usually it is in the form of `key1=value1;key2=value2;...`. However the DBD implementations can have different format so you need to check the document of each driver for exact specification of options.

rest argument will be passed to the underlying procedure.

NOTE: username, password and auto-commit are strongly encouraged to be implemented in the DBD library.

If a connection to the database is successfully established, a connection object is returned.

Method dbi-open? c

Checks if the given connection is still open.

The method shall return #t if the given connection is still open, otherwise it shall return #f.

Method dbi-close c

Closes a connection to the database.

NOTE: Users are strongly encouraged to close a connection explicitly. DBD might not close opened connections automatically.

Method dbi-commit! (c )
Method dbi-rollback! (c )

Commits or rollback transactions on the given connection, respectively.

#### Preparing and executing queries

Method dbi-prepare conn sql . args

From a string representation of SQL sql, creates and returns a query object for the database connection conn.

sql may contain parameter slot, denoted by `?`.

    (dbi-prepare conn "insert into tab (col1, col2) values (?, ?)")

    (dbi-prepare conn "select * from tab where col1 = ?")

If args is not null, then the procedure shall bind given parameters to the place holder.

Method dbi-open? (query )

Checks if the given query is still open.

The method shall return #t if the given query is still open, otherwise it shall return #f.

Method dbi-close (query )

Closes a query.

NOTE: Users are strongly encouraged to close a query explicitly. DBD might not close opened query automatically.

Method dbi-bind-parameter! query index value

Binds the given value to query at index.

The procedure shall accept integer index and may accept other type of index.

Method dbi-execute! query . args
Method dbi-execute-query! query . args

Executes given query. If the args is not null, then procedure shall bind the given args as its parameters.

The `dbi-execute!` shall return a integer value representing affected row count.

The `dbi-execute-query!` shall return a result set object which can be used with `dbi-fetch!` or `dbi-fetch-all!`. The implementation may allow to return a specific result set object and it is users' responsibility to use it with fetching the result.

NOTE: There is a default implementation of `dbi-execute-query!` and returns the given query as a result set object.

Method dbi-fetch! query
Method dbi-fetch-all! query

Fetches a row or all rows from the given query.

The `dbi-fetch!` shall return a vector representing the query result, if there is no more data available it shall return #f.

The `dbi-fetch-all!` shall return a list of vectors representing the query result.

NOTE: There is a default implementation of `dbi-fetch-all!`, it calls `dbi-fetch!` until it returns #f.

Method dbi-commit! (query )
Method dbi-rollback! (query )

Commits or rollback transactions on the given query, respectively.

Method dbi-columns query

Returns a column names affected by the given query.

The procedure shall return a vector as its result.

#### Conditions

The DBI library provides some of conditions which should be raised by underlying DBD implementations.

NOTE: The listed conditions may or may not be raised by underlying DBD implementation.

Condition &dbi-error
Function dbi-error? object
Function make-dbi-error

Root condition of DBI condition. `&dbi-error` is a sub condition of `&error`.

All DBI related condition should inherit this condition.

Condition &dbi-driver-not-exist
Function dbi-driver-not-exist? object
Function condition-driver-name condition

This condition is raised when DBD implementation can't be found.

`condition-driver-name` returns missing driver name.

Condition &dbi-unsupported
Function dbi-unsupported? object
Function make-dbi-unsupported

This condition indicates that DBI feature is not supported.

Implementations should raise this condition when methods can't be implemented on the target DBMS.

Condition &dbi-sql-error
Function dbi-sql-error? object
Function make-dbi-sql-error
Function dbi-sql-error-code

This condition holds SQL status code.

Implementations should raise this condition when SQL execution is failed with SQL status code.

### Writing drivers for DBI

Writing a driver for specific data base system means implementing a library `(dbd _foo_)` where foo is the name of the driver.

The library have to implement a creating a driver procedure and several classes and methods as explained below.

The method described above section must behave as it expected there, especially behaviours described with shall.

#### DBI driver procedure

The driver will be created by the procedure named `make-_foo_-driver`. And it is strongly encouraged to be implemented as a subclass of `<dbi-driver>` for future extension.

#### DBI classes to implement

You have to define the following classes.

- Subclass `<dbi-connection>`. An instance of this class is created by `dbi-make-connection`. It needs to keep the information about the actual connections.

- Optional: subclass `<dbi-driver>` for actual driver instance.

- Optional: subclass `<dbi-query>` to keep driver specific information of prepared statement.

#### DBI methods to implement

The driver needs to implement the following methods.

Method dbi-make-connection driver (options ) (options-alist ) . rest

This method is called from `dbi-connect`, and responsible to connect to the database and to create a connection object. It must return a connection object or raise an error which should be a sub condition of `&dbi-error`.

options is the option part of the data source name (DSN) given to `dbi-connect`. options-alist is an assoc list of the result of parsing options. Both are provided so that the driver may interpret options string in nontrivial way.

For example, given `"dbi:foo:myaddressbook;host=dbhost;port=8998"` as DSN, foo's `dbi-make-connection` will receive `"myaddressbook;host=dbhost;port=8998"` as options, and `(("myaddressbook" . #t) ("host" . "dbhost") ("port" . "8998"))` as options-alist.

After options-alist, whatever given to `dbi-connect` are passed. The driver is strongly encouraged to implement `:username`, `:password` and `:auto-commit` (if the database is supported) keyword arguments to specify the authentication information and commit mode.

Method dbi-prepare (c ) (sql ) . rest

The method must create and return a prepared query object which is an instance of `<dbi-query>` or its subclass.

sql is an SQL statement. It may contain placeholders represented by `'?'`. The implementation must accept it to keep DBI portable even though the database doesn't.

Method dbi-bind-parameter! (q ) index value

Binds a parameter value at the place index.

Method dbi-open? (c )
Method dbi-open? (q )
Method dbi-close (c )
Method dbi-close (q )

Queries open/close status of a connection and a query, and closes a connection and a query. The close method should cause releasing resources used by connection/query. The driver has to allow `dbi-close` to be called on a connection or a query which has already been closed.

Method dbi-commit! (c )
Method dbi-commit! (q )
Method dbi-rollback! (c )
Method dbi-rollback (q )

Commits/rollbacks a connection or a query.

Method dbi-execute! (q ) . args
Method dbi-fetch! (q )
Method dbi-columns q

Implementation must behave as described above section.

#### Data conversion guide

Database data type and Scheme type are usually not the same. However to keep DBI portable it is important to follow a guideline. Here I suggest the data conversion between a database and Scheme object.

Following is database data type to Scheme type conversion guideline. The driver implementation should follow.

Text (VARCHAR2 etc)

  String

Binary (BINARY etc)

  Bytevector

Date

  Date from SRFI-19

Time and Timestamp

  Time from SRFI-19

Blob

  Binary port, preferably not retrieving all data at once.

Clob

  Textual port, preferably not retrieving all data at once.

## (dbm) - Generic DBM interface

Library (dbm)

The library provides the generic interface to access DBM.

Sagittarius currently supports following DBM implementation;

(dbm dumb)

  DBM-like library. Inspired by Python's dbm.dumb. This library must be used as the last resort. It has poor performance and memory usage.

The following code shows a typical usage;

    (import (dbm))

    ;; Open the database
    (define *db* (dbm-open (dbm-type->class 'dumb) :path "dumb.db"))

    ;; Put the value to the database
    (dbm-put! *db* "key1" "value1")

    ;; Get the value from the database
    (dbm-get *db* "key1")

    ;; Iterate over the database
    (dbm-for-each *db* (lambda (key val) #| do something useful |#))

    ;; Close the database
    (dbm-close *db*)

### Opening and closing a dbm database

Class <dbm>

An abstract class for DBM-like database. The class has the following slots. It must be filled by `dbm-open`.

path

  Pathname of the dbm database.

rw-mode

  Specifies read/write mode. Can be one of the following keywords:

  read

  The database will be opened in read-only mode.

  write

  The database will be opened in read-write mode. If the database file does not exist, `dbm-open` creates one.

  write

  The database will be opened in read-write mode. If the database file exists, `dbm-open` truncates it. The keywords are indication so actual implementation may not behave as it described.

key-convert
value-convert

  By default, you can use only strings for both key and values. With this option, however, you can specify how to convert other Scheme values to/from string to be stored in the database. The possible values are the followings: #f

  The default value. Keys (values) are not converted. They must be a string. #t

  Keys (values) are converted to its string representation, using `write/ss`, to store in the database and convert back Scheme values, using `read/ss`, to retrieve from the database. a list of two procedures

  Both procedure must take a single argument. The first procedure must receive a Scheme object and returns a string. It is used to convert the keys (values) to store in the database. The second procedure must receive a string and returns a Scheme object. It is used to convert the stored data in the database to a Scheme object.

Metaclass <dbm-meta>

A metaclass of `<dbm>` and its subclasses.

Method dbm-open (dbm )

Opens a dbm database. dbm must be an instance of one of the concrete classes derived from the `<dbm>`.

Method dbm-open (dbm-class ) options ...

A convenient method that creates dbm instance and opens it.

Method dbm-close (dbm )

Closes a dbm database dbm. If the database is not closed, then the database file may not be synchronised properly. So it is user's responsibility to close it.

Method dbm-closed? (dbm )

Returns true if the dbm database dbm is closed, otherwise #f.

The returned value may be non boolean value.

Function dbm-type->class dbmtype

Returns DBM class if DBM implementation dbmtype exists, otherwise #f.

The dbmtype must be a symbol that names the type of dbm implementation, and the implementation library name must be `(dbm _dbmtype_)`. For example, to get the foo DBM then the library name must be `(dbm foo)`.

### Accessing a dbm database

Once a database is opened, you can use the following methods to access individual key/value pairs.

Method dbm-put! (dbm ) key value

Put a value with key

Method dbm-get (dbm ) key :optional default

Get a value associated with key. If no value exists for _key_and default is specified, it will be returned. If no value exists for key and default is not specified, then an error will be raised.

Method dbm-exists? (dbm ) key

Return true value if a value exists for key, #f otherwise.

Method dbm-delete! (dbm ) key

Delete a value associated with key.

### Iterating on a dbm database

To walk over the entire database, following methods are provided.

Method dbm-fold (dbm ) procedure knil

The basic iterator. For each key/value pair, procedure is called as `_procedure_ key value r`, where r is knil for the first call of procedure, and the return value of the previous call for subsequent calls. Returns the result of the last call of procedure. If no data is in the database, knil is returned.

Method dbm-for-each (dbm ) procedure

For each key/value pair in the database dbm, procedure is called. The procedure must accept 2 arguments, a key and a value respectively. The result of procedure is discarded.

Method dbm-map (dbm ) procedure

For each key/value pair in the database dbm, procedure is called. The procedure must accept 2 arguments, a key and a value respectively. The result of procedure is accumulated to a list which is returned as a result of `dbm-map`.

### Managing dbm database instance

Method dbm-db-exists? (class ) name

Returns #t if a database of class class specified by _name_exists.

Method dbm-db-remove (class ) name

Removes an entire database of class class specified by name.

Method dbm-db-copy (class ) from to

Copy a database of class specified by from to to.

Method dbm-db-move (class ) from to

Moves or renames a database of class specified by _from_to to.

## (util deque) - Deque

Library (util deque)

This library provides deque (double-ended queue) data structure and its operations.

You can create a simple deque, which is not thread-safe, or an MT deque, a thread-safe deque. Basic deque operations work on both type of deques. When a mtdeque is passed to the procedures listed in this section, each operation is done in atomic way, unless otherwise noted.

There are also a set of procedures for mtdeques that can be used for thread synchronisation; for example, you can let the consumer thread block if an mtdeque is empty, and/or the producer thread block if the number of items in the mtdeque reaches a specified limit. Using these procedures allows the program to use an mtdeque as a channel.

NOTE: (util queue) is implemented using this library.

Class <deque>

A class of simple deque.

Class <mtdeque>

A class of mtdeque. Inherits `<deque>`.

Function make-deque

Creates and return an empty simple deque.

Function make-mtdeque :key max-length

Creates and return an empty mtdeque.

The keyword argument max-length specifies the maximum entry count of the deque. Negative number indicates unlimited number of entry. If the given number is zero then the deque cannot hold any item.

Function deque? obj

Returns #t if obj is a deque (either a simple deque or an mtdeque).

Function deque? obj

Returns #t if obj is an mtdeque.

Function deque-empty? deque

Returns #t if deque is an empty deque.

Function deque-length deque

Returns the number of the items in the deque.

Function mtdeque-max-length mtdeque

Returns the maximum number of items mtdeque can hold. #f indicates unlimited.

Function mtdeque-room mtdeque

Returns the number of elements mtdeque can accept at this moment before it hits its maximum length. If the deque has unlimited capacity then the procedure returns `+inf.0`.

Function copy-deque deque

Returns a copy of deque.

Function deque-push! deque obj more-objs ...

Adds obj to the end of deque. You may give more than one object, and each of them are pushed in order.

If deque is an mtdeque, all the objects are pushed atomically; no other objects from other threads can be inserted between the objects given to a single `deque-push!` call. Besides, if the value of the result of `mtdeque-max-length` is positive, and adding objs makes the number of element in deque exceeds it, an error is raised and deque won't be modified. (If the maximum length is zero, this procedure always fail. Use `deque-push/wait!` below.)

Function deque-unshift! deque obj more-objs ...

Adds obj to in front of deque. You may give more than one object, and each of them are pushed in order.

Like `deque-push!`, when deque is an mtdeque, all objects are added atomically, and the value of max length is checked. See `deque-push!` above for more detail.

The name unshift is taken from Perl.

Function deque-push-unique! deque eq-proc obj more-objs ...
Function deque-unshift-unique! deque eq-proc obj more-objs ...

Like `deque-push!` and `deque-unshift!`, respectively, except that these don't modify deque if it already contains objs (elements are compared by two-argument procedure eq-proc).

When deque is an mtdeque, all objects are added atomically, and the max length is checked. See `deque-push!` above for the detail.

Function deque-pop! deque :optional fallback
Function deque-shift! deque :optional fallback

Take one object from the end or the front of deque, respectively, and return it.

If deque is empty, fallback is returned if give, otherwise an error is raised.

If deque is mtdeque and its max length is zero, then the deque is always empty. Use `deque-pop/wait!` or `deque-shift/wait!` to use such a deque as a synchronisation device.

The name shift is take from Perl.

Function deque-pop-all! deque
Function deque-shift-all! deque

Returns the whole content of deque by a list, with emptying deque. If deque is empty, returns an empty list.

The the returning list of `deque-pop-all!` is constructed from the end of queue and `deque-shift-all!`'s one is constructed from the front of queue.

See also `deque->list` below.

Function deque-front deque :optional fallback
Function deque-rear deque :optional fallback

Peek the head or the tail of deque and return the object, respectively.

If deque is empty, fallback is returned if give, otherwise an error is raised.

Function list->deque list :optional class :rest initargs

Returns a new deque which content is the elements in list, in the given order.

By default the created deque is a simple deque, but you can create mtdeque or instance of other subclass `<deque>` by giving the class to the optional class arguments. The optional initargs arguments are passed to the constructor of class.

Function deque->list deque

Returns a list whose content is the items in deque in order. Unlike `deque-shift-all!`, the content of deque remains intact. The returning list is a copy of the content. So modifying the list won't affect deque.

Function find-in-deque pred deque

Returns the first item in deque that satisfies a predicate pred.

Function any-in-deque pred deque

Apply pred on each item in deque until it evaluates true, and returns that true value. If no item satisfies pred, #f is returned.

Function every-in-deque pred deque

Apply pred on each item in deque. If pred returns #f, stops iteration and returns #f immediately. Otherwise, returns the result of pred on the last item of deque. If the deque is empty, #t is returned.

Function remove-from-deque! pred deque

Removes all items in deque that satisfies pred. Returns #t if any item is removed. Otherwise #f.

Function deque-unshift/wait! mtdeque obj :optional timeout timeout-val
Function deque-push/wait! mtdeque obj :optional timeout timeout-val
Function deque-shift/wait! mtdeque :optional timeout timeout-val
Function deque-pop/wait! mtdeque :optional timeout timeout-val

These synchronising variants work on an mtdeque and make the caller thread block when the mtdeque has reached its maximum length (for `deque-unshift/wait!` and `deque-push/wait!`), or the mtdeque is empty (for `deque-shift/wait!` and `deque-pop/wait!`). The blocked caller thread is unblocked either the blocking condition is resolved, or the timeout condition is met.

The optional timeout argument specifies the timeout condition. If it is #f, those procedure wait indefinitely. If it is a real number, they wait at least the given number of seconds.

In case the call is blocked then timed out, the value of timeout-val is returned, which default value is #t.

When `deque-unshift/wait!` and `deque-push/wait!` succeeds without hitting timeout, they return #t.

## (util duration) - Duration

Library (util duration)

This library provides a set of utility procedures of duration.

Function duration:of-nanos n
Function duration:of-millis n
Function duration:of-seconds n
Function duration:of-minutes n
Function duration:of-hours n
Function duration:of-days n

Returns a time of object of type `duration` with the value of n units.

For example, `(duration:of-millis 10)` returns 10 milli seconds equivalent value of time duration object.

## (util file) - File operation utility library

Library (util file)

This library provides file operation utilities which is not exported from `(sagittarius)` library.

### File to Scheme object operations

Function file->list reader path :key (transcoder (native-transcoder))

reader must be a procedure accept one argument which is a port. path must be a string indicating existing file.

Returns a list which elements are read by reader from the given _path_file. reader reads the file contents until it reads EOF object.

The keyword argument transcoder can specify which transcoder will be used to open a port. It must be either #f or transcoder. The default value is the value `(native-transcoder)` returns.

Function file->sexp-list path
Function file->string-list path

Thin wrapper of `file->list`. The procedures defined as following;

    (file->list `read/ss` _path_)

    (file->list `get-line` _path_)

respectively.

Function file->string path

Reads all file contents indicated path as a string and return it.

Function file->bytevector path

Reads all file contents indicated path as a bytevector and return it.

### Temporary directory operations

Function temporary-directory :optional path

Returns operating system specific temporary directory path.

If optional argument path is given, the procedure replace the temporary directory path.

Function make-temporary-file :optional prefix

Creates temporary file and returns 2 values. One is the port, the other one is created file path.

The created temporary file won't be deleted automatically so it is users responsibility to delete.

### Path operations

Function decompose-path path

path must be a string.

Decompose the given path to directory path, base name, and extension then returns these decomposed elements as 3 values.

The returning value can be #f if the path does not contains corresponding element.

Function path-extension path

Returns the extension of given path. If it does not contains extension then the procedure returns #f.

Function path-sans-extension path

Removes extension from given path and return it.

Function path-basename path

Returns the basename of given path. If it does not contains basename then the procedure returns #f.

Function find-files target :key (pattern #f) (all #t) (sort string<=?) (recursive #t)

target must be a string indicating existing file system path.

Find files from target if it's a directory and return the found files as a list.

Keyword arguments:

pattern

  Specifies the file pattern to be returned. This can be either string or regular expression pattern object.

all

  When this keyword argument is #t, then returns all files including hidden files which file name starting with `.`. If this is #f, the procedure excludes hidden files.

physical

  If this is #t, then the proc is only given either `directory` or `file`. No symbolic likes are given.

sort

  This specifies how to sort the result list. If the value is #f, then the result order is unspecified.

recursive

  If this keyword argument is #t then the procedure finds files recursively, otherwise only the first target directory.

Function path-for-each path proc :key (physical #t) (file-only #f) (absolute-path #t) _

_ (stop-on-file #f) (all #t) (recursive #t)

path must be a string indicating existing file path. _proc_must be a procedure accepts 2 arguments, a path string and a symbol. The given symbol can be `directory`, `symbolic-link` or `file`.

Apply given proc to the found paths starting from path and returns unspecified value. The second argument of proc indicates the file type with following meaning;

`directory`

  The path is a directory.

`symbolic-link`

  The path is a symbolic link.

`file`

  The path is a file

The keyword arguments:

file-only

  If this is #t, then the proc is only given a file. Otherwise all file types.

absolute-path

  If this is #t, then the proc is given absolute path. Otherwise only the filename.

stop-on-false

  If this is #t, then when proc returns #f the process will stop. Otherwise it continues the process.

The rest of the keyword arguments are the same as `find-files`.

Function path-map path proc :key (physical #t) (file-only #f) (absolute-path #t) (all #t) _

_ (recursive #t)

path must be a string indicating existing file path. _proc_must be a procedure accepts 2 arguments, a path string and a symbol. The given symbol can be `directory`, `symbolic-link` or `file`.

Process the path string starting from path with given proc and returns a list which elements are the result value of proc.

The keyword arguments are the same as `path-for-each`.

Function build-path paths ...

Re-exported procedure from `(sagittarius)` for convenience. See Sagittarius extensions.

Function build-path* paths ...

paths must be list of strings.

Compose given list to platform specific path. This procedure doesn't put path separator at the end of composed string.

### Directory operations

Function create-directory path
Function delete-directory path

Re-exported procedures from `(sagittarius)` for convenience. See Sagittarius extensions.

Function create-directory* path
Function delete-directory* path

Convenient procedures to create or delete directories.

These are the same as UNIX command `mkdir -p` and `rm -rf`, respectively.

Function copy-directory src dst :key (excludes '()) options ...

src and dst must be string and src must indicates an existing path.

Copies src directory to dst. Keyword argument excludes must be a list of string and the procedure won't copy files which contain the excludes string(s).

The options is passed to `path-for-each`.

## (getopt) - Parsing command-line options

Library (getopt)

This library defines a convenient way to parse command-line options.

The library exports a thin wrapper of SRFI-37: args-fold.

Macro with-args args (bind-spec ... [. rest]) body ...

This macro wraps `args-fold` provided by SRFI-37. It takes a list of arguments, args, and scans it to find Unix-style command-line options and binds their values to local variables according to bind-spec, then executes body.

Following is the example how to use;

    (define (usage args) ...)

    (define (main args)
      (with-args args
         ((verbose (#\v "verbose") #f #f)
          (file    (#\f "file") #t (usage args))
          (debug-level   (#\d "debug-level") #t "0")
          . rest)
        ...))

The bind-spec must be one of the following forms;

- (var (short long) value-required? default)

- (var (short long) `*` default)

var is variable name. short must be a character represents the short argument name. long must be a string represents the long argument name. value-required? specifies whether or not the optional argument has the value. default is the default form of the variable so it will be evaluated when the input args didn't have the specified option.

If the second form is used, the `*` is syntactic keyword and the passed value will be packed to list. Thus the script can take more than one the same options.

If rest is not presented and args contains non listed argument, then it raises an `&assertion`. If it is, then it will pack the rest of non listed argument as a list.

## (util hashtables) - Hashtable utilities

Library (util hashtables)

This library provides extra utilities for hashtable operation.

Function hashtable-for-each proc hashtable
Function hashtable-map proc hashtable

proc must be a procedure which accepts 2 arguments. hashtable must be a hashtable.

Iterates all keys and values in the given hashtable and passes them to proc respectively.

The `hashtable-for-each` returns unspecified value. The `hashtable-map` returns a list of the proc result.

These procedures are analogous to `for-each` and `map` respectively.

Function hashtable-fold kons hashtable knil

kons must be a procedure which accepts 3 arguments. hashtable must be a hashtable.

Iterates all keys and values in the given hashtable and passes them and the result of kons to kons respectively. The first iteration of the third argument is knil. The procedure returns the result of all iterations.

Analogous to `fold`.

Function hashtable->alist hashtable

Converts to hashtable to an alist.

Function alist->hashtable alist :key (compare eq?) (hasher symbol-hash)

Converts alist to hashtable.

The keyword arguments specify how to create the returning hashtable. By default, it will use `make-eq-hashtable`. If it's specified then it will use `make-hashtable` to create a hashtable.

## (util heap) - Heap

Library (util heap)

This library provides heap data structure and its operations. The implementation of heap is Fibonacci heap. Running time of heap operations are followings;

- Insert(key, data): O(1)

- FindMin(): O(1)

- DeleteMin(): Amortized O(log n)

- Delete(node): Amortized O(log n)

- DecreaseKey(node): Amortized O(1)

- Merge(heap1, heap2): O(1)

- Search(key): O(n)

### Constructors, predicates and accessors

Class <heap>

A class of Fibonacci heap.

Function heap? obj

Return #t if obj is a heap, otherwise #f.

Function make-heap compare

compare must be a procedure which takes 2 argument and returns an exact integer indicates the order of given arguments.

Creates a heap.

Function copy-heap heap

Creates copy of heap.

Function alist->heap compare alist

compare must be a procedure which takes 2 argument and returns an exact integer indicates the order of given arguments.

Creates a heap whose keys and values are car/cdr part of alist.

Function heap-empty? heap

Returns #t if heap is empty, otherwise #f.

Function heap-size heap

Returns the number of entries of heap.

Function heap-compare heap

Returns comparison procedure of heap.

Function heap-entry? obj

Returns #t if obj is a heap entry, otherwise #f.

Function heap-entry-key entry
Function heap-entry-value entry

Returns key and value of entry, respectively.

Function heap-entry-value-set! entry value

Sets value as entry's value.

### Heap operations

Function heap-min heap

Returns the smallest entry of heap. If heap is empty, then #f is returned.

To get the key and value from the returning entry, use `heap-entry-key`and `heap-entry-value` procedures, respectively.

Function heap-set! heap key value

Inserts an entry whose key is key, value is value and returns the entry.

Function heap-extract-min! heap

Removes smallest entry and returns it. It is an error if _heap_is empty.

Function heap-delete! heap entry/key

Removes target entry/key from heap and returns the removed entry.

If entry/key is an entry then this operation is done in amortized O(log n). If not, then O(n).

NOTE: If entry/key is an entry, then it must exist in heap. However the procedure won't check so it is user's responsibility to make sure.

Function heap-delete! heap entry/key new-key

Change the key value of given entry/key to new-key. The new-key must be smaller than current key in sense of the returning value of `heap-compare`, otherwise it's an error.

If entry/key is an entry then this operation is done in amortized O(log n). If not, then O(n).

NOTE: If entry/key is an entry, then it must exist in heap. However the procedure won't check so it is user's responsibility to make sure.

Function heap-clear! heap

Clears all entry of heap and returns heap.

Function heap-merge! heap1 heap2

Merge heap2 into heap1 and empty it. Then returns heap1.

This procedure changes both heaps destructively, if you want to kepp heap2 intact, use `merge-heaps` or `merge-heaps!` instead.

Function merge-heaps heap1 heap2 more ...
Function merge-heaps! heap1 heap2 more ...

Merges heap and returns merged heap.

If the first procedure is used then the returning heap is freshly created according to heap1. The second form merged the rest of heaps to heap1.

The running time of these procedures is O(nm) where m is number of heaps to merge.

Function heap-ref heap key :optional (fallback #f)

Returns entry value associated with key in heap. If there is no entry, then fallback is returned.

The running time of this procedures is O(n).

Function heap-update! heap key proc default

proc must be a procedure accepts one argument.

Updates the entry value associated to key with the returned value of proc. If the entry doesn't exist then default will be passed to the proc.

The running time of this procedures is O(n).

Function heap-search heap key :optional finish

Searches the entry associated to key and returns it. If there is no entry then #f is returned.

If optional argument finish given then it must be a procedure which takes one argument. The procedure is called when search process is finished. The given argument is either an entry of #f.

## (util list) - Extra list utility library

Library (util list)

This library provides extra list utility procedures.

Function for-each-with-index proc list1 list2 ...
Function map-with-index proc list1 list2 ...

Like `for-each` and `map`, expect proc receives the index as the first argument.

    (map-with-index list '(a b c) '(e f g))

((0 a e) (1 b f) (2 c g))
Function intersperse item list

Inserts item between elements in the list.

    (intersperse '+ '(1 2 3))

(1 + 2 + 3)

    (intersperse '+ '(1))

(1)

    (intersperse '+ '())

()
Function slices list k :optional fill? padding

Splits list into the sublists (slices) where the length of each slice is k. If the length of list is not multiple of k, the last slice is dealt in the same way as `take*`; this is, it is shorter than k by default, or added padding if fill? is true.

    (slices '(a b c d e f g) 3)

((a b c) (d e f) (g))

    (slices '(a b c d e f g) 3 #t 'z)

((a b c) (d e f) (g z z))
Function split-at* list k :optional (fill? #t) (padding #f)

Splits the list list at index k. This is more tolerant version of `split-at` defined in SRFI-1 library. Returns the results of `take*` and `drop*`.

    (split-at* '(a b c d) 6 #t 'z)

(a b c d z z) and ()
Function take* list k :optional (fill? #f) (padding #f)
Function drop* list k

More tolerant version of `take` and `drop` defined in SRFI-1 library. These won't raise an error when k is larger than the size of the given list.

If the list is shorter than k elements, `take*` returns a copy of list by default. If fill? is true, padding is added to the result to make its length k.

On the other hand, `drop*` just returns as empty list when the input list is shorter than k elements.

    (take* '(a b c d) 3)

(a b c)

    (take* '(a b c d) 6)

(a b c d)

    (take* '(a b c d) 6 #t)

(a b c d #f #f)

    (take* '(a b c d) 6 #t 'z)

(a b c d z z)

    (drop* '(a b c d) 3)

(d)

    (drop* '(a b c d) 5)

()
Macro cond-list clause ...

Construct a list by conditionally adding entries. Each clause must have a test and expressions. When its test yields true, then result of associated expression is used to construct the resulting list. When the test yields false, nothing is inserted.

Clause must either one of the following form:

(test expr ...)

  Test is evaluated, and when it is true, expr ... are evaluated, and the return value becomes a part of the result. If no expr is given, the result of test is used if it is not false.

(test => proc)

  Test is evaluated, and if it is true, proc is called with the value, and the return value is used to construct the result

(test expr ...)

  Like `(test expr ...)`, except that the result of the last expr must be a list, and it is spliced into the resulting list, like unquote-splicing.

(test => proc)

  Like `(test => proc)`, except that the result of the last proc must be a list, and it is spliced into the resulting list, like unquote-splicing.

    (let ((alist '((x 3) (y -1) (z 6))))
     (cond-list ((assoc 'x alist) 'have-x)
                ((assoc 'w alist) 'have-w)
                ((assoc 'z alist) => cadr)))

(have-x 6)

    (let ((x 2) (y #f) (z 5))
      (cond-list (x   `(:x ,x))
                 (y   `(:y ,y))
                 (z   `(:z ,z))))

(:x 2 :z 5)

## (util logging) - Logging utilities

Library (util logging)

This library provides logging utilities.

`(util logger)` provides logger and appender style logging utilility. Loggers determine loging level and appenders determin how to write logs. This example shows the concept.

    (import (rnrs) (util logging))

    ;; Appenders
    (define console-appender (make-appender "[~w5] ~l ~m"))
    (define file-appender
      (make-file-appender "[~w5] ~l ~m" "useful.log"))

    ;; Logger
    (define logger (make-logger +debug-level+ console-appender file-appender))

    ;; This won't be logged since the logger level is debug.
    (trace-log logger "trace log message")
    (debug-log logger "debug log message")

    ;; If the logging requires heavy process, then it's better to
    ;; check the level
    (when (logger-info? logger)
      (let ((message (construct-message)))
        (info-log logger message)))

    ;; stop logging
    (terminate-logger! logger)

### Loggers

Loggers contains collection of appenders and level of logging. Once a logger is created, appenders and threshold can't be modified.

Record Type <logger>
Function logger? obj
Function make-logger threshold appenders ...

Basic logger.

Record type `<logger>` is a base type of loggers.

`logger?` returns #t if obj is a logger otherwise #f.

`make-logger` creates a logger whose threshold is threshold and appenders are appenders. The threshold must be one of the followings:

Constant +trace-level+
Constant +debug-level+
Constant +info-level+
Constant +warn-level+
Constant +error-level+
Constant +fatal-level+

Logging level constants.

The `+trace-level+` is the lowest level (`0`) and `+fatal-level+` is the highest level (`5`). The values are integers so users can extend the level for both side.

Record Type <async-logger>
Function async-logger? obj
Function make-async-logger threshold appenders ...

Asynchronous logger.

Record type `<async-logger>` is a type of asynchronous loggers. It inherits the `<logger>`.

`async-logger?` returns #t if obj is an asynchronous logger otherwise #f.

`make-async-logger` creates an asynchronous logger. The arguments are passed to parent protocol.

Asynchronous logger logs message asynchronously. Means it creates a background thread and lets it log. It is useful if a logger has a lot of appenders and logging process may take a lot of time.

To stop background thread, `terminate-logger!` needs to be called. It is users responsibility to do it.

Function trace-log logger message . arguments
Function logger-trace? logger
Function debug-log logger message . arguments
Function logger-debug? logger
Function info-log logger message . arguments
Function logger-info? logger
Function warn-log logger message . arguments
Function logger-warn? logger
Function error-log logger message . arguments
Function logger-error? logger
Function fatal-log logger message . arguments
Function logger-fatal? logger

Logging APIs.

`_level_-log` procedures log message on logger if logger has its threshold lower than the level.

`logger-_level_?` procedures check if the logger has threshold lower than level.

Generic Function terminate-logger!
Method terminate-logger (logger )
Method terminate-logger (logger )

Terminates logging of the given logger.

The method calls `appender-finish` for all appenders of give logger.

If the logger is an asynchronous logger, then it also stops background thread.

### Appenders

Appenders are actual logging mechanisms. Each appender must be responsible how to write a log message and resource management such as log file.

Record Type <appender>
Function appender? obj
Function make-appender log-format

Base appender. This appender emits log messages into `current-output-port`.

`appender?` returns #f if obj is an appender otherwise #f.

`make-appender` creates an appender. The log-format argument must be a string and specifying the format of the log line.

The log-format can contains place holders stating with the character `#\~`. The followings are the defined place holders:

`#\w_date-format_`

  Puts logging date on this location. The date-format specifies format of the log. It must be a character or string which is surrounded by `#\{ #\}`. The format is passed to the `date->string` procedure defined in SRFI-19.

`#\l`

  Puts logging level on this location.

`#\m`

  Puts log message on this location.

`#\a[n]`

  Puts _n_th log argument on this location.

`#\a`

  Puts all log arguments on this location.

The following example shows when log-format is `"[~w5] ~l ~m"`and logging with info level.

    (define logger (make-logger +info-level+ (make-appender "[~w5] ~l ~m")))
    (info-log logger "message of the log")
    ;; [2016-09-06T12:32:06] info message of the log

Record Type <file-appender>
Function file-appender? obj
Function make-file-appender log-format filename

File appender. This is a subtype of `<appender>`. This appender emits log messages to the file named filename.

`file-appender?` returns #f if obj is a file appender otherwise #f.

`make-file-appender` creates a file appender. The log-format is passed to parent protocol. The file creation is done with file options of `no-fail`, `no-truncate` and `append`. Thus if the file exists then it would append the log line.

The given filename will be converted to absolute path so changing directory will not affect the log file location.

Generic Function file-appender-filename
Method file-appender-filename (file-appender )

Returns log file name.

Record Type <rolling-file-appender>
Function make-rolling-file-appender log-format filename :optional (rolling-size 10485760)
Function rolling-file-appender? obj

Rolling file appender. This is a subtype of `<file-appender>`. This appender emits log message to the file named filename and if the file size is more than rolling-size, then it renames the old file to indexed file and new log file named filename is created.

`rolling-file-appender?` returns #f if obj is a rolling file appender otherwise #f.

Record Type <daily-rolling-file-appender>
Function make-daily-rolling-file-appender log-format filename :optional (date-pattern "~Y-~m-~d")
Function daily-rolling-file-appender? obj

Daily rolling file appender. This is a subtype of `<file-appender>`. This appender emits log message to the file named filename and if the date string of last file modified time formatted to _date-pattern_is differ from log time, then the appender rolls the old log file to a backup file. The backup file is concatenation of filename and last modified date.

`daily-rolling-file-appender?` returns #f if obj is a daily rolling file appender otherwise #f.

#### Creating appenders

Users would soon face that predefined appenders are not enough or don't satisfy the requirement. For that case, appenders can easily be created.

The following example shows how to create an Email appender.

    (import (rnrs)
            (rfc smtp)
            (rfc smtp authentications)
            (util logging)
            (clos user))

    (define-record-type (<smtp-appender> make-smtp-appender smtp-appender?)
      (parent <appender>)
      (fields (immutable connection smtp-appender-connection)
              (immutable username smtp-appender-username)
              (immutable password smtp-appender-password))
      (protocol (lambda (p)
                  (lambda (format host port username password)
                    ((p format)
                     (make-smtp-connection host port) username password)))))

    (define-method append-log ((appender <smtp-appender>) log)
      (let ((message (format-log appender log))
            (conn (smtp-appender-connection appender)))
        (guard (e (else (report-error e)))
          (smtp-connect! conn)
          (when (smtp-authentication-required? conn)
            (let* ((methods (smtp-connection-authentication-methods conn))
                   (username (smtp-appender-username appender))
                   (password (smtp-appender-password appender))
                   (method (cond ((memq 'PLAIN methods)
                                  (list (smtp-plain-authentication username password)))
                                 ((memq 'PASSWORD methods)
                                  (let-values ((init&next (smtp-login-authentication username password)))
                                    init&next))
                                 (else #f))))
              (if methods
                  (apply smtp-authenticate! conn method)
                  (begin
                    (smtp-disconnect! conn)
                    (error 'append-log "not supported")))))
          (smtp-send! conn (smtp:mail
                            (smtp:from "Takashi Kato" "ktakashi@ymail.com")
                            (smtp:to "Takashi Kato" "ktakashi@ymail.com")
                            (smtp:subject "Logging with email")
                            message))
          (smtp-disconnect! conn))))

The example is not really useful since it sends only the fixed recipient with fixed format. If you need to use it, you need to modify.

Only what users need to do to create an appender is the followings:

- Creates a record type inherits `<appender>`.

- Specialising `append-log` method with the above record.

Generic Function append-log appender log

Core process of appending logs.

log is an object of `<log>` or its subtype. This method should emit logs.

Generic Function appender-finish appender

Finishing appender if necessary. This method is called when `terminate-logger` is called.

Implementation should release resource of the appender.

Generic Function format-log appender log

Formats log object. log is an object of `<log>` or its subtype.

The method must return a string representation of given log.

The default implementation handles the log format described in the `make-logger` description.

Function appender-log-format appender

Returns log format of the given appender.

Record Type <log>
Function log? obj
Function make-log when level message . arguments
Function log-when log
Function log-level log
Function log-message log
Function log-arguments log

Default log object.

`<log>` has 4 fields `when`, `level`, `message` and `arguments`. By the default creation, they are UTC time object, symbol of log level, log message and a vector of extra logging arguments, respectively.

If you want to create own logger which handles log object differently, then you need to specialise the following generic function with the logger.

Generic Function push-log logger log

Pushes log to appenders of the logger.

### Singleton logger

Asynchronous logger or other loggers should sometimes be singleton. This type of thing might need to be done in users responsibility however I think it's common idiom. So the very simple one is added to the library.

Macro define-logger-storage lookup clause* ...
Macro define-logger-storage (lookup register) clause* ...

This macro defines a logger lookup procedure. If the second form is used then, a registration procedure.

The generated procedures have the following signatures

(@var{lookup} @var{name})

  Looks up the logger named name

(@var{register} @var{name} @var{logger})

  Registers the given logger with name, name

The registration procedure stores the given logger to hidden storage. If the procedure called the same name argument twice, then the latter logger overwrites the previous one.

`clause*` must the following form:

- `(loggers (_logger-name_ _make-logger_) ...)`

`loggers` is an auxiliary syntax. If the `loggers`clause is specified, then the macro stores the logger logger-name which is created by make-logger thunk as its predefined loggers.

## (math) - Mathematics library

### Deprecated library

This library is deprecated, please consider to use Cryptographic libraries instead.

This section describes matheatics operations which are used by `(crypto)`library.

This library also uses `libtomcrypt` as its implemention except prime number operations.

Library (math)

The top most level library of mathematics. It exports all of procedures from `(math random)`, `(math hash)`, `(math prime)` and `(math helper)`

### Random number operations

Library (math random)

This library exports procedures for random numbers.

Function pseudo-random type :key (seed #f) (reader #f)

type must be a string.

Creates a pseudo random object (prng). If keyword argument reader is given it creates a custom prng. The reader must be a procedure which accepts two argument, a bytevector and integer. It must fill the given bytevector with random numbers.

type is used to specify the builtin pseudo random algorithm. The possible algorithms are below:

Constant Yarrow
Constant Fortuna
Constant RC4
Constant SOBER-128

The following is also a psuedo random but this may or may not be cryptographic random generator.

Constant System

`System` prng uses platform random generator. For example, on Unix like environment, this uses `/dev/urandom` or `/dev/random` if the first option is not available.

seed is entropy of the pseudo random.

Note: each time if you create pseudo random, it returns exactly the same value. For example:

    (do ((i 0 (+ i 1)) (r '() (cons (random (pseudo-random RC4) 10) r)))
        ((= i 10) r))

'(0 0 0 0 0 0 0 0 0 0)

So if you need different number as I believe, you need to reuse the prng object like this

    (let ((rc (pseudo-random RC4)))
      (do ((i 0 (+ i 1)) (r '() (cons (random rc 10) r)))
          ((= i 10) r)))

'(3 4 0 6 7 4 3 4 2 0)

If you don't want to care this behaviour, use `secure-random` below.

Function secure-random type :key (bits 128)

type must be one of the pseudo random algorithms.

Creates secure random object.

bit is initial entropy of the pseudo random. It must be in between 64 to 1028.

Function prng? obj
Function pseudo-random? obj
Function secure-random? obj

Returns #t if obj is prng object, builtin pseudo random objcet, custom random object or secure random object respectively.

Function random-seed-set! prng seed

seed must be a bytevector or integer.

Add entropy to given prng.

Function random prng size :key (read-size 100)

Returns random number according to given prng algorithm. The result number will be less than size.

Keyword argument read-size will be passed to `read-random-bytes`.

Function random prng size

size must a positive fixnum.

Reads size bytes of random byte from prng.

Method prng-state (prng )

Returns given prng's state if the pseudo random implementation allows.

For default built in pseudo randoms return #f.

NOTE: if <secure-random> is implemented, then the pseudo random implementation should not return the state.

Function read-random-bytes prng size
Function read-random-bytes! prng bv size

Reads random bytes from given prng.

The first form creates fresh bytevector with size size.

The second form reads random bytes from prng and sets the result into the given bv destructively.

If the second form is used, bv must have the length at least size.

Function read-sys-random bits

Returns given the `(+ (* bits 8) (if (zero? (mod bits 8)) 1 0))` bits of random bytevector.

Function read-sys-random! bv
Function read-sys-random! bv start
Function read-sys-random! bv start len

bv must be a bytevector.
start must be an exact non negative integer.
len must be an exact non negative integer.

Reads random bytes from a system random generator and store it into bv.
If the second form is used, then it stores from the start position.
If the third form is used, then it stores the len bytes from the start.

#### Custom pseudo random operations

Since version 0.3.2, pseudo random also has custom operations. Similar with cipher spi or hash algorithm.

The following example describes how to make it.

    ;; the code snipet is from math/mt-random
    (define-class <mersenne-twister> (<user-prng>)
      (;; The array for the state vector
       ;; using bytevector, it needs to be 64 bit aligned.
       (state :init-keyword :state :init-form (make-bytevector (* NN 8)))
       ;; mti==NN+1 means MT[NN] is not initialized
       (mti   :init-keyword :mti   :init-form (+ NN 1))))
    (define-method initialize ((o <mersenne-twister>) initargs)
      (call-next-method)
      (let ((seed (get-keyword :seed initargs #f)))
        (slot-set! o 'set-seed! mt-set-seed)
        (slot-set! o 'read-random! mt-read-random!)
        (when seed
          (mt-set-seed o seed))))

User just need to set the slots `set-seed!` and `read-random!`. Then other process is done by lower layer.

Following describes the meaning of these slots.

The slot `set-seed!` requires a procedure which accepts 2 arguments, target pseudo random and seed. seed must be bytevector.

The slot `read-random!` requires a pseudo which accepts 3 arguments, target pseudo random buffer and bytes. buffer must be a bytevector and have bigger size than given bytes. bytes must be a non negative fixnum.

NOTE: The custom pseudo random interface has been changed since version 0.3.6. Make sure which version of Sagittarius your application using.

### Hash operations

Library (math hash)

This library exports procedures for hash (digest) operations.

Function hash-algorithm name . options

name must be a string.

Creates a hash-algorithm object. name specifies its algorithm. The predefined algorithms are blow:

Constant WHIRLPOOL
Constant SHA-512
Constant SHA-384
Constant SHA-256
Constant SHA-224
Constant SHA-512/256
Constant SHA-512/224
Constant Tiger-192
Constant SHA-1
Constant RIPEMD-320
Constant RIPEMD-256
Constant RIPEMD-160
Constant RIPEMD-128
Constant MD5
Constant MD4
Constant MD2
Constant SHA-3-224
Constant SHA-3-256
Constant SHA-3-384
Constant SHA-3-512
Constant BLAKE2s-128
Constant BLAKE2s-160
Constant BLAKE2s-224
Constant BLAKE2s-256
Constant BLAKE2b-160
Constant BLAKE2b-256
Constant BLAKE2b-384
Constant BLAKE2b-512

If you want to use other hash algorithm, you can also create a new hash algorithm. It is described the section Custom hash algorithm.

Function hash-algorithm? obj

Return #t if obj is hash-algorithm object otherwise #f.

Function hash-oid hash-algorithm

Return OID of given hash-algorithm if it has otherwise #f.

#### User level APIs of hash operations

Function hash type bv . options

type must be a string which specifies hash algorithms or hash-algorithm object.

The `hash` procedure generates digest from given bytevector _bv_according to the given algorithm. The result digest will be a bytevector.

If type is not a hash algorithm object nor predefined hash algorithm, then options will be passed to the custom hash algorithm creation.

Function hash-size hash-algorithm

Returns hash size of given hash-algorithm.

Function hash-block-size hash-algorithm

Returns hash block size of given hash-algorithm.

#### Low level APIs of hash operations

Most of the time User level APIs are sufficient enough, however for some cases, for example multiple input datas, you might need to use these low leve APIs.

Function hash-init! hash-algorithm

Initialise given hash-algorithm.

Function hash-process! hash-algorithm bv :optional (start 0) (end (bytevector-length bv))

bv must be a bytevector.

Process hash process with input data bv. The result will be stored in the hash-algorithm.

Optional arguments start and end limits the input bv.

Function hash-done! hash-algorithm out :optional (start 0) (end (bytevector-length bv))

out must be a bytevector and must have hash size which the `hash-size` procedure returns.

Flushes stored hash result in hash-algorithm into out.

Once this procedure is called hash-algorithm's state will be changed. If you want to reuse it, you need to call `hash-init!`.

Optional arguments start and end specifies the offset of output bytevector.

#### Custom hash algorithm

Since version 0.3.1, user can create a custom hash algorithm. Similar with cipher spi described section Creating own cipher.

The following example describes how to make it.

    (import (rnrs) (sagittarius) (math) (clos user))
    ;; hash operations
    (define (foo-init hash) #t)
    (define (foo-process hash bv)
      (let ((len (bytevector-length bv)))
        (bytevector-copy! bv 0 (slot-ref hash 'buffer) 0 (min len 16))))
    (define (foo-done hash out)
      (let ((v (integer->bytevector (equal-hash (slot-ref hash 'buffer)))))
        (bytevector-copy! v 0 out 0 (min 8 (bytevector-length v)))))

    (define-class <foo-hash> (<user-hash-algorithm>)
      ((buffer :init-form (make-bytevector 16))))
    (define-method initialize ((o <foo-hash>) initargs)
      (call-next-method)
      (slot-set! o 'init foo-init)
      (slot-set! o 'process foo-process)
      (slot-set! o 'done foo-done)
      (slot-set! o 'block-size 16)
      (slot-set! o 'hash-size 8)
      (slot-set! o 'oid #f)
      (slot-set! o 'state #f))
    ;; marker
    (define-class <foo-marker> () ())
    (define FOO (make <foo-marker>))
    (register-hash FOO <foo-hash>)

    ;; use with APIs
    (hash FOO (string->utf8 "hash")) ;; -> #vu8(245 221 54 232 0 0 0 0)

The slots `init`, `process` and `done` must be set with a procedure which will be called by `hash-init!`, `hash-process!` and `hash-done!` respectively.

The procedure set to `process` and `done` must accept 2 or 4 arguments. If it can accept 4 arguments, then optional argumens _start_and end are passed. Implementation can use these information to ptimise memory allocation. If it can accept 2 argumens, then framework handles the range. In this case, uneccesarry allocation may happen.

The slots `block-size` and `hash-size` must be non negative exact integer and will be returned by `hash-block-size` and `hash-size`procedures respectively.

The slot `oid` must be set #f or string which represent OID of the custom hash algorithm. If you don't have it, it's better to set #f.

The slot `state` can be anything, this slot is for storing the hash state if you need.

### Prime number operations

Library (math prime)

This library exports procedures for prime number operations.

Function prime? q :optional (k 50) (rand (secure-random RC4))
Function is-prime? q :optional (k 50) (rand (secure-random RC4))

Tests if given q is a prime number or not.

This procedure uses Miller Rabin primality test. So there is slight possibility to pass non prim number.

The optional argument k is the test times. The default 50 makes failure ratio very low. And rand specifies whith pseudo random algorithm uses in the test.

The latter form is for backward compatibility.

Function random-prime size :key (prng (secure-random RC4))

Find a prime number from size bytes. So the minimum range will be `1 <= p <= 251`.

Keyword argument prng specifies which pseudo random uses to find a prime number.

### Misc arithmetic operations

Library (math helper)

This library exports procedures for misc arithmetic operations.

Function mod-inverse x m

Re exporting `mod-inverse` defined in `(sagittarius)` library.

Function mod-expt x e m

Re exporting `mod-expt` defined in `(sagittarius)` library.

## (net mq amqp) - AMQP library

Library (net mq amqp)

Providing APIs for AMQP, Advanced Message Queuing Protocol.

Currently, the library lacks security layer such as TLS and SAML, and transaction support.

### Example

Following examples describes how to send and receive messages from remote queues.

    (import (rnrs) (net mq amqp api))

    ;; Sends text message to SAMPLE.QUEUE on localhost:5672
    (call-with-amqp-connection "localhost" "5672"
      (lambda (conn)
        (call-with-amqp-session conn
          (lambda (session)
            (let ((sender (create-amqp-sender session "SAMPLE.QUEUE"))
                  (message (create-amqp-text-message "Hello AMQP!!")))
              (send-amqp-message sender message)
              (destroy-amqp-sender sender))))))

    ;; Receives text message from SAMPLE.QUEUE on localhost:5672
    (call-with-amqp-connection "localhost" "5672"
      (lambda (conn)
        (call-with-amqp-session conn
          (lambda (session)
            (let* ((receiver (create-amqp-receiver session "SAMPLE.QUEUE"))
                   (message (receive-amqp-message receiver)
              (destroy-amqp-sender receiver)
              message)))))))

### High level APIs

Function amqp-connection? obj

Returns #t if given obj is AMQP connection. Otherwise #f.

Function open-amqp-connection host port

Creates an AMQP connection object.

Function close-amqp-connection! connection

Closes given AMQP connection.

Function call-with-amqp-connection host port proc

Creates an AMQP connection and pass it to proc. Then returns the result of proc.

The created connection will be closed both proc returns or raises an error. Thus Invoking captured continuation inside of proc would not work.

Function amqp-session? obj

Returns #t if given obj is AMQP session. Otherwise #f.

Function begin-amqp-session! connection

Starts AMQP session on the given connection

Function end-amqp-session! session

Ends given AMQP session.

Function call-with-amqp-connection connection proc

Starts an AMQP session and pass it to proc. Then returns the result of proc.

The stated session will be ended both proc returns or raises an error. Thus Invoking captured continuation inside of proc would not work.

Function amqp-sender? obj
Function amqp-receiver? obj

Returns #t if given obj is AMQP sender and receiver, respectively. Otherwise #f.

Function create-amqp-sender session source-queue
Function create-amqp-receiver session target-queue

Creates an AMQP sender or receiver, respectively.

source-queue and target-queue must be strings and indicating queue names on the remote server.

Function destroy-amqp-sender sender
Function destroy-amqp-receiver receiver

Destory given sender and receiver, respectively.

Function send-amqp-message sender message

Sends message to sender's queue.

message must be am AMQP message object.

Function receive-amqp-message receiver :key (timeout #f)

Receives an AMQP message from receiver's queue.

Keyword argument timeout must be #f or integer. If this is specified then the procedure waits only specified milliseconds.

Function amqp-message? obj

Returns #t if given obj is AMQP message. Otherwise #f.

Function create-amqp-text-message text
Function create-amqp-binary-message data
Function create-amqp-mime-message content-type data

Creates an AMQP text message, binary message and data message, respectively.

text must be a string. data must be a bytevector. content-type must be a string.

## (net http-client) - Modern HTTP client

Library (net http-client)

Providing, probably, modern HTTP client.

The `(net http-client)` provides a modern HTTP client, which handles connection pooling, client certificate, redirect and cookie. The client also provides asynchronous calling atop future object of `(util concurrent)`.

The following example shows how to use in a nutshell.

    (import (rnrs)
            (net http-client)
            (util concurrent))

    (define client (http:client-builder
                    (follow-redirects (http:redirect normal))))

    (let ((future (http:client-send-async client
                                          (http:request-builder
                                           (uri "http://google.com")))))
      ;; do whatever you need to do during the above HTTP call
      (let ((response (future-get future)))
        (http:response-status response)  ;; -> 200
        (http:response-headers response) ;; -> header object
        (http:response-body response)    ;; -> body as bytevector
        ))

### HTTP client

Function http:client? o

Returns `#t` if the given o is a HTTP client, otherwise `#f`.

Function http:client-send ( client `http:client?` ) ( request `http:request?` )

Sends the given request via the client and returns `http:response`.

This procedure is synchronous procedure, so it blocks.

Function http:client-send-async ( client `http:client?` ) ( request `http:request?` )

Sends the given request via the client and returns a future which returns `http:response`.

Function http:client-shutdown! ( client `http:client?` ) :optional ( shutdown-executor? `#t` )

Shutdowns the given client. If the optional argument shutdown-executor? is specified to `#f`, then the underlying executor won't be shutdown.

If the underlying executor is the default executor, then it won't be shutdown, even if the optional argument is true value.

Macro http:client-builder field ...

A constructor macro to build a HTTP client.

The _field_s must be one or more of the following:

`follow-redirects`

  Specifies redirection strategy, the value must be a valid value of `http:redirect`.

`cookie-handler`

  Specifies a cookie handler. Currently, `http:make-default-cookie-handler` is the only option.

`connection-manager`

  Specifies a connection manager. See Connection Manager section for more detail.

`version`

  Specifies a HTTP version. The value must be a valid value of `http:version`. The client handles both HTTP/1.1 and HTTP/2 by default.

`executor`

  Specifies an executor. The the default executor has 5 threads, but it'd be shared by all the client created without this field, so if you want to use the client in a intense situation, it's a good idea to specify own executor.

Macro http:version value

A macro checks if the given value is a valid supporting HTTP version.

The value must be either `http/1.1` or `http/2`. If the later one is specified, it first tries to connect with HTTP/2, and falls back to HTTP/1.1 if HTTP/2 is not avaiable.

HTTP/2 works only on TLS environment, as the client uses ALPN to detect the version.

Macro http:redirect value

A macro checks if the given value is a valid supporting redirect strategy.

The value must be one of `never`, `always` or `normal`. The default value is `never`.

`never`

  Won't redirect, it is suitable if you want to handle 3xx result manually.

`always`

  Redirects as long as the 3xx status is returned. This means insecure redirection may happen (i.e. HTTPS to HTTP)

`normal`

  Redirects 3xx status if the scheme is the same or more secure.

### HTTP request and response

Function http:request? o

Returns #t if the given o is an HTTP request object, otherwise #f.

Macro http:request-builder field* ...

Builds a HTTP request object.

The `field` must be one or more the followings.

`uri`

  The URI of the request, it has to be an URI object of `(net uri)` or valid URI string. This field is mandatory.

`method`

  A valid HTTP method. Default value is `GET`.

`content-type`

  A content type header, this is used when the method is allowed to have body. Default value `"application/octet-stream"`.

`body`

  Content of the request. The value must be either a bytevector ot binary input port.

`headers`

  A list of headers or a HTTP header object. If it's a list of header, then the element must contain a pair of name and values.

`cookies`

  A list of cookies. The elements must be cookie object of `(rfc cookie)`

`auth`

  An authentication provider. Must be a thunk providing the `Authorization` header value.

Function http:headers? o

Returns #t if the given o is a HTTP headers object, otherwise #f.

Function http:make-headers

Make a HTTP headers object.

A HTTP headers object can contain multiple values on one headers.

Function http:headers-ref* headers name

Retrieve a list of value of the header name from headers.

If the name doesn't exists, then it returns `()`.

Function http:headers-ref headers name

Retrieve the first value of the header name from headers.

If the name doesn't exists, then it returns `#f`.

Function http:headers-set! headers name value

Sets the single value of value into the headers with header name of name.

Function http:headers-add! headers name value

Adds the value in the headers to the header value list of name.

If the name doesn't exist, then it works the same as `http:headers-set!`.

Function http:headers-names headers

Returns a list of header names of the given headers

Function http:response? o

Returns #t if the given o is an HTTP response object, otherwise #f.

Function http:response-status response

Returns the response HTTP status code.

The code is a string.

Function http:response-headers response

Returns the response HTTP headers object.

Function http:response-cookies response

Returns a list of the response cookie, if exists.

The element of the list is a cookie object of `(rfc cookie)`.

Function http:response-body response

Returns the body of the response. The value is bytevector.

#### Authorization header value providers

Authorization header value providers can be used for `auth` field of the HTTP request.

Function http:request-basic-auth username password

Provides basic auth value provider of the given username and password.

Function http:request-basic-bearer token

Provides bearer auth value provider of the given token.

### Connection Manager

A connection manager manages the connections of a HTTP client. By default, we support these three types of connection managers; ephemeral, pooling, and logging.

The ephemeral connection manager creates a connection per request and discards it. This connection manager should only be used in disposable scripts.

The pooling connection manager pools the created connection and try to reuse if possible.

Below example shows how to create a HTTP client with pooling connection manager.

    (define pool-config
      (http-pooling-connection-config-builder
        (connection-timeout 1000)     ;; 1 sec, connection timeout
        (max-connection-per-route 20) ;; pooling connection number per route
        (read-timeout 3000)           ;; 3 sec, read timeout
        (dns-timeout 1000)            ;; 1 sec, DNS lookup timeout
        (time-to-live 120)            ;; 120 sec, expiration time of a connection
    	))
    (define http-client
      (http:client-builder
        (connection-manager (make-http-pooling-connection-manager pool-config))))

Function make-http-default-connection-manager

Creates a default connection manager. This is at this moment an ephemeral connection manager without any timeout or key configuration.

#### Ephemeral Connection Manager

Function http-connection-config? obj

Returns #t if the obj is an instance of `http-connection-config`, otherwise #f.

Macro http-connection-config-builder field ...

A constructor macro to build a `http-connection-config` record.

The _field_s must be one or more of the following:

`connection-timeout`

  Specifies connection timeout in milli second.

`read-timeout`

  Specifies read timeout in milli second.

`key-manager`

  Specifies a key manager. See Key Manager section for more detail.

Function http-ephemeral-connection-manager? obj

Returns #t if the obj is an ephemeral connection manager, otherwise #f.

Function make-http-ephemeral-connection-manager config

Config must be a `http-connection-config` record instance.

Creates an ephemeral connection manager.

#### Pooling Connection Manager

Function http-pooling-connection-config? obj

Returns #t if the obj is an instance of `http-pooling-connection-config`, otherwise #f.

The `http-pooling-connection-config` record is a child record of `http-connection-config`.

Macro http-pooling-connection-config-builder field ...

A constructor macro to build a `http-pooling-connection-config`record.

The _field_s must be one or more of the following and the ones from `http-connection-config-builder`:

`connection-request-timeout`

  Specifies connection request timeout in milli second. The timeout is only for the waiting time of the connection retrieval from the pool.

`max-connection-per-route`

  Specifies pool size per route. A route is defined with the combination of hostname and port. Default value is 5.

`time-to-live`

  Specifies the life time of the pooled connection in seconds

`delegate-provider`

  Specifies connection manager delegate provider. Default value is `default-delegate-connection-manager-provider`

A delegate connection manager is an underlying connection manager of the pooling connection manager. The delegate creates and closes the actual connection.

Function http-pooling-connection-manager? obj

Returns #t if the obj is a pooling connection manager, otherwise #f.

Function make-http-pooling-connection-manager config

Config must be a `http-pooling-connection-config`record instance.

Creates a pooling connection manager.

#### Delegate Connection Manager providers

A delegate connection provider is a procedure which accepts one argument config and returns a connection manager.

Function default-delegate-connection-manager-provider config

Synonym of `make-http-ephemeral-connection-manager`.

### Key Manager

Key manager manages client certificate of HTTP connections. A key manager may contain multiple of key providers. A key provider should provide a list whose the first element is a private key and the rest are certificate chain.

The following example shows how to make a key manager with multiple key providers.

    (import (rnrs)
            (net http-client)
            (rfc base64)
            (security keystore))
    (define (host-a p)
      (define node (socket-parameter-socket-node p))
      (cond ((string=? node "host-a.com") "host-a-key-alias")
            (else #f)))
    (define (host-b p)
      (define node (socket-parameter-socket-node p))
      (and (string-suffix? ".host-b.com" node) "host-b-key-alias"))
    (define keystores
      ;; keystore file (PKCS12 base64 encoded), store pass, key pass, alias selector
      `(("host-a.b64" "password0" "password0a" ,host-a)
        ("host-b.b64" "password1" "password1a" ,host-b)))

    (define (->keystore-key-provider keystore-info)
      (let ((file (car keystore-info))
            (storepass (cadr keystore-info))
            (keypass (caddr keystore-info))
            (strategy (cadddr keystore-info)))
        (make-keystore-key-provider
         (call-with-input-file file
           (lambda (in)
             (let ((bin (open-base64-decode-input-port in)))
               (load-keystore 'pkcs12 bin storepass)))
           :transcoder #f)
         keypass
         strategy)))

    (make-key-manager (map ->keystore-key-provider keystores))

Function key-manager? obj

Returns #t if the obj is a key manager, otherwise #f.

Function make-key-manager key-providers
Function list->key-manager key-providers

Key-providers must be a list of key provider.

Creates a key manager.

Function key-manager key-provider ...

Key-provider must be a provider.

Creates a key manager.

#### Key Provider

Key provider provides keys. The key can be retrieved from anywhere but must be a format of a list of private key and certificate chain.

We provide keystore key provider by default. If you need other key provider, you need to create a custom one.

Record Type <key-provider>

An abstruct record type of key provider. Users must inherit this record type to create a custom key provider.

This record type has a filed named `key-retrievers`.

Function key-provider? obj

Returns #t if the obj is a key provider otherwise #f.

Function make-key-provider key-obtainer

key-obtainer must be a procedure which receives one argument, `socket-parameter`.

Creates a key provider.

Function key-provider-key-retrievers key-provider

Returns the value of field `key-retrievers` of the key provider key-provider.

This procedure is not meant to be used by a user of HTTP client.

Function keystore-key-provider? obj

Returns #t if the obj is a keystore key provider otherwise #f.

Function make-keystore-key-provider keystore password alias-provider

Keystore must be a keystore object of `(security keystore)`. password must be a string of valid key password. alias-provider must be a procedure which accepts one argument, socket parameter, and returns either string of key alias or #f.

Creates a key provider with one key retriever.

Function keystore-key-provider-add-key-retriever! keystore-key-provider password alias-provider

Add a key retriever to the keystore-key-provider and returns keystore-key-provider.

This procedure is convenient if you have multiple keys in one keystore.

#### Socket parameter

Socket parameter is used to determine which private key to be used. The object contains basic socket information.

Function socket-parameter? obj

Returns `#t` if the given obj is a socket parameter, otherwise `#f`.

Function socket-parameter-socket-hostname ( sp `socket-parameter?` )
Function socket-parameter-socket-ip-address ( sp `socket-parameter?` )
Function socket-parameter-socket-node ( sp `socket-parameter?` )
Function socket-parameter-socket-service ( sp `socket-parameter?` )

Returns `hostname`, `ip-address`, `node` and `service` respectively.

The first 2 values are peer information, the latter 2 are local information.

## (net http) - Async HTTP client

Library (net http)

This library provides a wrapper of `(net http-client)` library, for convenience especially scripting purpose.

To simplify the document, here we use methods, nobody-methods and bodied-methods to refer sets of HTTP methods. The mapping of the methods are blow:

methods

  All HTTP methods, at this moment we support the below methods:

  - GET

  - HEAD

  - OPTIONS

  - POST

  - PUT

  - PATCH

  - DELETE

  nobody-methods

  HTTP methods which don't have body, these are the ones:

  - GET

  - HEAD

  - OPTIONS

  bodied-methods

  HTTP methods which may have body, these are the ones:

  - POST

  - PUT

  - PATCH

  - DELETE

If these names are used in the procedure names, then lower cased names are used. e.g. `http-{nobody-methods}` will be `http-get` and others.

### HTTP request procedures

Function http-{nobody-methods} request-context
Function http-{nobody-methods} uri callback
Function http-{bodied-methods} request-context
Function http-{bodied-methods} uri body
Function http-{bodied-methods} uri body callback

request-context must be a HTTP request context.
uri must be a string representation of HTTP URI.-- callback must be a procedure which accepts one argument of HTTP response.
body must be a bytevector, HTTP request payload or `#f`.

Synchronous HTTP request procedure. callback is called when the response is received.

These procedure blocks the process.

If the body is a bytevector, then it is sent with content type of `application/octet-stream`.

Function async-http-{nobody-methods} request-context
Function async-http-{nobody-methods} uri callback
Function async-http-{bodied-methods} request-context
Function async-http-{bodied-methods} uri body
Function async-http-{bodied-methods} uri body callback

Asynchronous version of HTTP request procedures. The return value is future object.

Function async-http-{nobody-methods}/client http-client request-context
Function async-http-{nobody-methods}/client http-client uri callback
Function async-http-{bodied-methods}/client http-client request-context
Function async-http-{bodied-methods}/client http-client uri body
Function async-http-{bodied-methods}/client http-client uri body callback

The same as asynchronous version of HTTP request procedures, this procedures accept HTTP client instead of using default one provided by this library.

Function async-http-request request-context
Function async-http-request/client http-client request-context

Underlying HTTP requesting procedure of all the above per method procedure. These procedures can be used not to write manual dispatch by the HTTP method.

The `async-http-request` uses default HTTP client as underlying HTTP client, described below section.

#### Default HTTP client

The default HTTP client is configured as below specification:

- Having pooling connection manager of max connection per route of `100`

- DNS timeout of `30` seconds

- Connection timeout of `60` seconds

- Read timeout of `120` seconds

- Always follows redirection

#### HTTP request context

A HTTP request context is a sub record of `<http:request>` defined in `(net http-client)`. It has extra fields `payload` and `callback`.

`payload` fields provides a convenient access to the `content-type` and `body` fields of the `<http:request>`.

`callback` fields provides a callback for the response.

Function http-request-context? obj

Returns `#t` if the given obj is a HTTP request context, otherwise `#f`.

Macro http-request-context-builder field* ...

Builds a HTTP request context. For the detail of field, see `(net http-client)` .

#### HTTP request payload

The library provides a convenient framework to compose HTTP request body and associated content type. HTTP request payload is a record which contains 3 fields; `content-type`, `content` and `converter`. The `content-type` is the content type value to be sent. The `content` is the raw content of the reuqest payload, for example, a list of key and value pairs. Then the `converter` convers the `content` to a bytevector.

The library provides generic binary payload and 3 most used content types:

- `application/octet-stream`

- `application/json`

- `application/x-www-form-urlencoded`

Users can make own request payload as well.

Record type <http-request-payload>

The base record of HTTP request payload. The record has below 3 fields;

`content-type`

  Accessor `http-request-payload-content-type`

`content`

  Accessor `http-request-payload-content`

`converter`

  Accessor `http-request-payload-converter`

Function http-request-payload? obj

Returns `#t` if the given obj is HTTP request payload, otherwise `#f`.

One of the supporting payload, `<json-request-payload>` is defined like this:

    (define-record-type <json-request-payload>
      (parent <http-request-payload>)
      (protocol (lambda (p)
                  (define (json->string json)
                    (let-values (((out e) (open-string-output-port)))
                      (json-write/normalized json out)
                      (e)))
                  (define (json->bytevector json) (string->utf8 (json->string json)))
                  (lambda (json)
                    ((p "application/json" json json->bytevector))))))

Record type <binary-request-payload>
Function binary-request-payload? obj
Function binary-payload ( binary (or `bytevector?` `binary-port?` )) :optional ( content-type `"application/octet-stream"` )

HTTP request payload for binary input.

If you already have a binary data ready to be sent, then this payload can be the most convenient one to use.

Record type <octet-stream-request-payload>
Function octet-stream-request-payload? obj
Function octet-stream-payload ( bv (or `bytevector?` `binary-port?` ))

HTTP request payload for octet stream.

Record type <json-request-payload>
Function json-request-payload? obj
Function json-payload json-sexp

HTTP request payload for JSON object. The json-sexp must be a valid JSON S-expression.

NOTE: On Sagittarius, JSON S-expression is Chicken's egg style, it's not the same as SRFI JSON. For more detail, see `(text json)`

Record type <x-www-form-urlencoded-request-payload>
Function x-www-form-urlencoded-request-payload? obj
Function x-www-form-urlencoded-payload kv

HTTP request payload for `application/x-www-form-urlencoded`.

kv must be a list of key/value pair.

Example:

    (x-www-form-urlencoded-payload '(("key0" . "value0") ("key1" . "value1")))
    ;; -> represents `key0=value0&key1=value1`

Both key and value are encoded when it's converted to a bytevector.

#### HTTP response

HTTP response related procedures are re-export from `(net http-client)`, for more details, see HTTP request and response

## (net mq mqtt) - MQTT library

Library (net mq mqtt)

Providing MQTT v3.1.1 and partially v3.1 client APIs.

Reference OASIS MQTT.

Following examples describe how to receive and publish messages.

    (import (rnrs) (net mq mqtt))

    (let ((conn (open-mqtt-connection "localhost" "1883")))
      ;; subscribes to "topic" topic with accepting QoS exactly once
      (mqtt-subscribe conn "topic" +qos-exactly-once+
                      (lambda (topic payload)
                        (let ((msg (get-bytevector-all payload)))
                          (cond ((not (eof-object? msg))
                                 (print (utf8->string msg))
                                 (string=? (utf8->string msg) "END"))
                                (else #f)))))
      (let loop ()
        ;; receives until "END" message was sent
        (unless (mqtt-receive-message conn)
          (loop)))
      ;; unsubscribe from "topic"
      (mqtt-unsubscribe conn "topic")
      (close-mqtt-connection! conn))

    (import (rnrs) (net mq mqtt))

    (let ((conn (open-mqtt-connection "localhost" "1883")))
      ;; publish message to "topic" topic.
      (mqtt-publish conn "topic" (string->utf8 "Hello MQTT"))
      (close-mqtt-connection! conn))

Function mqtt-connection? obj

Returns #t if given obj is MQTT connection. Otherwise #f.

Function open-mqtt-connection host port opts ...

Creates a socket connected to host:port and pass it to port->mqtt-connection with opts.

The returning value is an MQTT connection object.

Function port->mqtt-connection in/out :key client-id username password keep-alive version

in/out must be a binary input/outport port.

Creates an MQTT connection object using in/out.

client-id, username, password and _keep-alive_keyword arguments are for optional payload of CONNECT packet. If they are given, then first 3 must be strings and keep-alive must be an integer.

version keyword argument is switches which version it should use. The value must be one of the followings;

Constant +mqtt-3.1+
Constant +mqtt-3.1.1+

By default it uses `+mqtt-3.1.1+`.

This procedure is for future extension such as supporting websocket.

Function close-mqtt-connection! conn

Closes given MQTT connection.

Function mqtt-subscribe conn topic qos callback

Subscribes to given topic with QoS qos.

callback must be a procedure and accept 2 arguments. topic and payload. payload is an binary input port.

To receive messages, use `mqtt-receive-message`.

Function mqtt-receive-message conn

Receives one message from one of subscribed topics and call registered callback.

Function mqtt-unsubscribe conn topic

Unsubscribes conn from topic.

Function mqtt-publish conn topic message :key qos

Publishes application message message to topic.

The topic must be a string. The message must be a bytevector.

If keyword argument qos is specified, it must be one of the followings.

Constant +qos-at-most-once+
Constant +qos-at-least-once+
Constant +qos-exactly-once+

By default, it uses `+qos-at-most-once+`.

Function mqtt-ping conn

Sends PINGREQ packet to the server.

### MQTT broker

Library (net mq mqtt broker)

This library provides simple MQTT broker implementation.

The broker only does what broker suppose to do, thus there is no user customised behaviour.

The simplest broker script would look like this:

    (import (rnrs) (net mq mqtt broker))

    ;; Wait on port 9000
    (define broker (make-mqtt-broker "9000")))

    ;; start the broker.
    (mqtt-broker-start! broker)

Function make-mqtt-broker :key config authentication-handler :allow-other-keys

Creates MQTT broker.

The returning broker is a sub type of `<simple-server>`.

If config keyword argument is specified, the value must be an configuration object created by `make-mqtt-broker-config`, then the specified configuration is used. Otherwise default configuration which can be created by `(make-mqtt-broker-config)` is used.

If authentication-handler keyword argument is specified, then the specified value which must be a procedure takes 2 arguments, username and password, handles authentication. If the procedure doesn't return true value then authentication error packet is sent to the client.

Function make-mqtt-broker-config :key (max-thread 10) :allow-other-keys

Creates a MQTT broker configuration object.

The returning value is a sub type of `<server-config>` with `:non-blocking?` option.

Function mqtt-broker-start! broker opt ...
Function mqtt-broker-stop! broker opt ...

Start and stop procedure for MQTT broker.

These procedures are mere redefinitions of `server-start!` and `server-stop!`.

## (net oauth) - OAuth library

This section describes the APIs for OAuth. OAuth is new secure authentication method for web service. For more detail, see OAuth Community Site.

The following example shows how to obtain an access token from Twitter.

    (import (rnrs) (net oauth) (sagittarius control) (srfi :13 strings))
    ;; obtain a request token.
    ;; type consumer key and secret you have got issued by Twitter
    (define token (obtain-request-token
    	       "http://api.twitter.com/oauth/request_token"
    	       (make-consumer-token
    		:key "consumer key"
    		:secret "consumer secret")))

    (define (get-pin url)
      (print "Open the following url and type in the shown PIN.")
      (print url)
      (let loop ()
        (display "Input PIN: ") (flush-output-port (current-output-port))
        (let1 pin (get-line (current-input-port))
          (cond ((eof-object? pin) #f)
                ((string-null? pin) (loop))
                (else pin)))))

    (define (report token)
      (print "(begin")
      (print " (define consumer-key \"" (token-key (token-consumer token)) "\")")
      (print " (define consumer-secret \""
    	 (token-secret (token-consumer token))"\")")
      (print " (define access-token \""(token-key token)"\")")
      (print " (define access-token-secret \""(token-secret token)"\")")
      (print ")"))

    (define (main args)
      (let1 pin (get-pin (make-authorization-uri
    		      "http://api.twitter.com/oauth/authorize"
    		      token))
        ;; authorize the request token manually.
        (authorize-request-token token pin)
        ;; obtain the access token
        (let1 access-token (obtain-access-token
    			"http://api.twitter.com/oauth/access_token"
    			token)
          (report access-token))))

Now you get the access token to tweet, let's tweet something on Sagittarius:

    (import (rnrs) (srfi :26 cut) (text sxml ssax) (net oauth) (sagittarius io))
    (define consumer-key "your consumer key")
    (define consumer-secret "your consumer secret")
    (define access-token "your access token")
    (define access-token-secret "your access token secret")

    ;; creates an access token to tweet.
    (define access-token
      (make-access-token :key access-token
    		     :secret access-token-secret
    		     :consumer
    		     (make-consumer-token
    		      :key consumer-key
    		      :secret consumer-secret)))

    (define (call/twitter-api->sxml token method path params . opts)
      (define (call)
        (access-protected-resource
         (string-append "http://api.twitter.com" path)
         token
         :request-method method
         :user-parameters params))
      (define (retrieve body status hint advice)
        (if hint (print hint))
        (if advice (print advice))
        (call-with-input-string body (cut ssax:xml->sxml <> '())))
      (call-with-values call retrieve))

    (define (twitter-update/sxml token message . opts)
      (call/twitter-api->sxml
       token 'POST "/1/statuses/update.xml"
       `(("status" ,message))))

    ;; if you want to use this from command line.
    (import (getopt))

    (define (main args)
      (with-args args
          ((message (#\m "message") #t (usage)))
        (print (twitter-update/sxml access-token message))))

The examples explain basic flows. To obtain an access token, and access to protected resource with it.

Library (net oauth)

This library provides OAuth 1.0 procedures. The API's names are compatible with cl-oauth.

Function obtain-request-token uri consumer-token :key (version :1.0) (user-parameters '()) _

_ (timestamp (time-second (current-time))) (auth-location :header) _ _ (request-method 'POST) (callback-uri #f) (additional-headers '()) _ _ (signature-method :hmac-sha1) (error-translator default-message-translator)

uri must be string and URI format.

consumer-token must be a consumer token object.

Obtains request token from given uri with given consumer token.

if the keyword arguments are specified:

version specifies which version uses. We only support 1.0 so this must not be specified.

user-parameters is an alist of the extra parameters to be sent to the server. This parameters are in the body message if the request-method is `POST` or query string if the request-method is `GET`.

timestamp specifies timestamp to send to the server.

auth-location specifies the place where the authentication information located. This can be either `:header` or `:parameters`.

request-method specifies which request method is used. This can be either `GET` or `POST`. `POST` is recommended.

callback-uri specifies call back uri described in OAuth specification. If users don't use specific location to be redirected, this must not be specified.

additional-headers is alist of additional header to be sent to the server.

signature-method specifies which hash method is used. For now we only support `:hmac-sha1`.

error-translator specifies how to treat the error message sent by the server when error occurred. This must be a procedure which accepts 3 arguments, http status, headers and body respectively.

Function make-authorization-uri uri request-token :key (version :1.0) (callback-uri #f) _

_ (user-parameters '())

uri must be string and URI format.

request-token must be a request token retrieved by the procedure `obtain-request-token`.

Creates a authorization URI which user must agree.

The other keyword arguments are the same as `obtain-request-token`.

Function authorize-request-token request-token verificateion-code

request-token must be a request token which retrieved by the procedure `obtain-request-token`.

verificateion-code must be a string returned by the URI generated by the procedure `make-authorization-uri`Sets the given verificateion-code to the request token and authorized flag #t, manually.

Function obtain-access-token uri token :key (consumer-token (token-consumer token)) _

_ (version :1.0) (user-parameters '()) _ _ (timestamp (time-second (current-time))) (auth-location :header) _ _ (request-method 'POST) (callback-uri #f) (additional-headers '()) _ _ (signature-method :hmac-sha1) (error-translator default-message-translator)

uri must a string URI formatted.

token must be either request token or access token.

Obtains access token from the given URI.

The keyword arguments consumer-token specifies which consumer token is used. And must the same one as when you request the request token.

The rest keyword arguments are the same as `obtain-request-token`.

Function access-protected-resource uri access-token :key (consumer-token (token-consumer access-token)) _

_ (on-refresh #f) _ _ (version :1.0) (user-parameters '()) _ _ (timestamp (time-second (current-time))) (auth-location :header) _ _ (request-method 'POST) (callback-uri #f) (additional-headers '()) _ _ (signature-method :hmac-sha1) (error-translator default-message-translator)

uri must a string URI formatted.

access-token must be an access token which obtained by the procedure `obtain-access-token` or created by `make-access-token`.

Accesses to protected resource.

The keyword argument on-refresh is a hook for when token is expired and refreshed. It must accept be a procedure which accepts 1 argument that is a refreshed access token.

The rest keyword arguments are the same as the `obtain-request-token`.

Function oauth-uri-encode string

Encodes given URI and make it OAuth required form.

Function oauth-compose-query parameters

Composes given alist to http query form and make it OAuth required form.

Function make-consumer-token :key (key (random-key)) (secret random-secret) (user-data #f) _

_ (last-timestamp 0)

Creates a consumer token.

Function make-access-token :key (key (random-key)) (secret random-secret) (user-data #f) _

_ consumer (session-handle #f) (expires #f) (authorization-expires #f) _ _ (origin-uri #f)

Creates a access token.

Method token-consumer token

token must be an access token or request token.

Retrieves consumer token from given token.

## (net server) - Simple server framework

Library (net server)

This library provides simple server framework.

Following example describes how to write a simple echo server with the APIs this library provides.

    (import (net server) (sagittarius socket))

    (define (handler server socket)
      ;; echo message is limited to 255 bytes in this example
      (let ((r (socket-recv socket 255)))
        ;; socket will be closed by the framework
        (socket-send socket r)))

    (define server (make-simple-server "5000" handler))

    (server-start! server)

Above example creates only one thread and if there are more than one connection, then the latter one needs to wait until first one is done. The library also provides mult threading server. Following example describes how to make multi threading server.

    (import (net server) (sagittarius socket))

    ;; specifies maximum thread number
    (define server-config (make-server-config :max-thread 5))

    (define (handler server socket)
      (let ((r (socket-recv socket 255)))
        ;; socket will be closed by the framework
        (socket-send socket r)))

    (define server (make-simple-server "5000" handler :config server-config))

    (server-start! server)

If the server gets more than 5 connection simultaneously, then it tries to wait until one of the connection's task finishes. If it doesn't finish in time, then connection will be refused.

If clients keep the connection but server wants to handle requests more than configured thread number, then specify non-blocking? keyword argument with #t.

    (import (net server) (sagittarius socket))

    ;; specifies maximum thread number
    (define server-config (make-server-config :max-thread 5 :non-blocking? #t))

    (define (handler server socket)
      (let ((r (socket-recv socket 255)))
        (if (eof-object? r)
            ;; close the socket after the process
            (socket-close socket)
            (socket-send socket r))))

    (define server (make-simple-server "5000" handler :config server-config))

    (server-start! server)

Above server example creates 5 threads and accept all requests. The requests are dispatched to the least busy thread. There are couple of restrictions to use this server. See the descirption of non-blocking? keyword argument.

### Server

Class <simple-server>

Simple server class.

Function server? obj

Returns #t if the obj is an instance of `<simple-server>`, otherwise #f.

Function make-simple-server service handler :key server-class config :allow-other-keys

Creates a server object.

service must be a string and indicates the service name or port number.

handler must be a procedure accepts 2 arguments, server object server created with this procedure and socket object socket.

Keyword argument server-class is specified, it must be a class inherits `<simple-server>`, then the procedure uses the class to instantiate. And during instantiation, given other keys are passed.

Keyword argument config is specified, it must be an instance of <server-config> or subclass of it, then the server is created according to the configuration.

Function server-config server

Returns configuration object used to create given server object server.

Function server-stopped? server

Returns #t if given server is stopped.

NOTE: this also returns #t if the server is not started.

Function server-start! server :key background :allow-other-keys

Starts the given server.

Keyword argument background is true value then the server is started background. By default it's #f.

The rest of keywords are passed to `on-server-start!`.

NOTE: Server object is not reusable thus once server is started, it is impossible to restart the server.

Function server-stop! server :allow-other-keys

Stops the given server.

The rest of keywords are passed to `on-server-stop!`.

Function wait-server-stop! server :optional timeout

Waits until the server stops.

The server must be stopping by accessing shutdown port otherwise this procedure waits forever/for timeout period.

Optional argument timeout must be #f, time object or real number. If the value is #f then this procedure waits forever until the _server_stops. By default #f.

Method on-server-start! (server ) rest ...
Method on-server-stop! (server ) rest ...

Hook methods for subclasses.

The first method is called when server is starting.

The second method is called after server is stopped.

### Configuration

Class <server-config>

Server configuration class.

Function server-config? obj

Returns #t if the obj is an instance of `<server-config>`, otherwise #f.

Function make-server-config :key shutdown-port shutdown-handler exception-handler max-thread _

_ max-retry use-ipv6? secure? certificates

Creates a server config object.

Following is the description of keyword arguments.

shutdown-port

  Specifying shutdown port. The value must be a string. If this is not specified, then the server doesn't have shutdown port.

shutdown-handler

  This is only used then shutdown-port is specified. The value must be a procedure takes 2 arguments, server and socket. When the procedure returns true value then server will be stopped. By default, it's a procedure always returns #t.

exception-handler

  Specifying exception handler. The value must be a procedure accepts 3 arguments, server, socket and condition. This is called when the server handler raises an error. NOTE: The passing socket is not closed so that the handler can send messages to client socket.

max-thread

  Specifying max thread count. Default value is 1.

max-retry

  Specifying max retry count. When connection reached max-thread, then the server waits if the one of the connections finishes. The waiting period is half second (500 ms) and this value specifies how many times server waits. Default value is 10.

non-blocking?

  Creating non blocking server. If the server is non blocking server, then the server handler must follow the following rules:

  - the handler process must not block/stop even if the given socket is active.

  - the handler process must close the socket when it's not needed. When handler raises an error and exception-handler is specified, then the given socket won't be closed. So exception-handler needs to decide whether the exception is continuable or not. Otherwise, server closes the socket. Specifying this keyword argument makes server ignore max-retry.

use-ipv6?

  Specifying whether or not the server uses IPv6. Default value is #f. (only IPv4)

secure?
certificates

  If secure? is true value and certificates is a list of X509 certificates, then the server uses TLS.

private-key

  If the server uses TLS, then this keyword argument is passed to `make-server-tls-socket`. It is strongly recommended to specify this keyword argument, otherwise key exchange is done anonymously, means no signature is sent.

### Socket detaching

Non blocking server manages sockets per threads. This feature is useful if the server handler is reused per socket. However this prevents users to write asynchronous call. The following procedure allow users to detach sockets from the server.

Function server-detach-socket! server socket

Detaches the given socket.

If the socket is detached, then all resource managements, including closing socket, become users' responsibility.

This procedure is only available on non blocking server and can be called inside of server handler. If the condition is not met, then `&assertion`is signaled.

## (net socket) - Modern Socket library

Library (net socket)

Providing, probably, modern socket library.

Most of the bindings defined in this library is identical as `(sagittarius socket)`, so this document will describe only the differences.

Function socket-options? o
Function tls-socket-options? o
Function server-tls-socket-options? o

Returns #t if the given o is a `socket-options`, `tls-socket-options`, or `server-tls-socket-options`, respectively.

The `socket-options?` returns #t for all 3 types.

Macro socket-options-builder (fields ... )

Builds a socket-options object. The `field` must be one or multiple of the followings:

ai-family

  See `ai-family` of `(sagittarius socket)`

ai-socktype

  See `ai-socktype` of `(sagittarius socket)`

ai-flags

  See `ai-flags` of `(sagittarius socket)`

ai-protocol

  See `ai-protocl` of `(sagittarius socket)`

non-blocking?

  Specifies if the socket is non blocking or not, default #t

connection-timeout

  Specifies connection timeout in micro seconds, default #f (infinite)

read-timeout

  Specifies read timeout, default #f (infinite) see `socket-set-read-timeout!` for more details.

Macro tls-socket-options-builder (fields ... )

Builds a tls-socket-options object. The `fields` must be the ones from `socket-options-builder` or one or multiple of the followings:

handshake

  Specifes if handshake must be done or not. Default #t

private-key

  A client private key

certificates

  A list of client certificates, must be specified when `private-key` is specified

certificate-verifier

  A certificate verifier procedure

sni*

  A list of server name indicators, a list of string

alpn*

  A list of application layer protocol negotiation names

Macro server-tls-socket-options-builder (fields ... )

Builds a server-tls-socket-options object. The `fields` must be the ones from `tls-socket-options-builder` or one or multiple of the followings:

client-certificate-required?

  Specifes if client certificate is required or not. Default #f

trusted-certificates

  A list of trusted certificates

Function make-client-socket node service :optional options

Creates a client socket. This is almost the same as the one from `(sagittarius socket)`, the only difference is it takes options to specify extra options, such as read timeout or connection timeout.

Function make-client-tls-socket node service :optional options

Creates a client socket. This is almost the same as the one from `(rfc tls)`, the only difference is it takes options to specify extra options, such as client certificate, alpn, etc.

Function make-server-socket node service :optional options

Creates a client socket. This is almost the same as the one from `(sagittarius socket)`, the only difference is it takes options to specify extra options, such as read timeout or connection timeout.

Function make-server-tls-socket node service :optional options

Creates a client socket. This is almost the same as the one from `(rfc tls)`, the only difference is it takes options to specify extra options, such as private key, etc.

Function socket-options->client-socket options node service

Creates a client socket from the given options, node and service.

This is a convenient procedure to make a socket from the options instead of let user dispatch manually.

## (odbc) - ODBC binding

Library (odbc)

This library provides ODBC access procedures.

ODBC is a common database access interface so that it doesn't depend on specific APIs. This library is for implementing ODBC DBD for DBI, using this library directly is not recommended.

NOTE: the library is supported only your platform is supporting ODBC.

Function create-odbc-env

Creates and returns ODBC environment object.

Function odbc-env? obj

Returns #t if the given obj is ODBC environment object.

Function free-handle odbc-ctx

Releases given ODBC resource.

Function connect! ocbc-env server username password :optional (auto-commit #t)

odbc-env must be an ODBC environment object created by `create-odbc-env`.

server must be a string indicating ODBC database name.

username and password must be string.

Connects to server with authentication of username and password and returns ODBC database connection object. If optional argument auto-commit is #f then the connection won't commit transaction automatically.

Function odbc-connection? obj

Returns #t if the given obj is ODBC connection object.

Function disconnect! odbc-dbc

Disconnect from the database.

Function connection-open? odbc-dbc

Returns #t if the given ODBC connection is available, otherwise #f.

Function prepare odbc-dbc sql

Creates and returns a ODBC statement object.

Function odbc-statement? obj

Returns #t if the given obj is ODBC statement object.

Function statement-open? odbc-stmt

Returns #t if the given ODBC statement is available, otherwise #f.

Function num-prams odbc-stmt

Returns number of parameters in an SQL statement.

Function bind-parameter! odbc-stmt index value

Binds the given value at position index.

Function execute! odbc-stmt

Execute given ODBC statement.

Function fetch! odbc-stmt

Forwarding current cursor to next and returns #t if there is data otherwise #f.

Function get-data! odbc-stmt index

Retrieve data from statement at position index.

Function row-count odbc-stmt

Returns the number of rows affected by UPDATE, INSERT or DELETE statement.

Function column-count odbc-stmt

Returns the number of columns in a result statement.

Function result-columns odbc-stmt

Returns the column names in a result statement.

Function commit! odbc-ctx
Function rollback! odbc-ctx

Commits/rollbacks given ODBC context.

### (dbd odbc) - DBD for ODBC

Library (dbd odbc)

This library provides database driver (DBD) for ODBC .

Importing this library is done by DBI automatically so users should not use this directly.

The DSN should specify the connecting database name with `server` keyword. Following DSN is connecting foo database configured in ODBC.

`"dbi:odbc:server=_foo_"`The `dbi-connect` supports `:username`, `:password` and `:auto-commit` keyword arguments. The detail about DBI see (dbi) - Database independent access layer.

## (peg) - PEG library

Library (peg)

A parser combinators library.

This library is named PEG (Paring Expression Grammar), howerver it only provides parser combinator not syntactical layer, yet.

The following example shows parsing simple arithmetic expressions.

The first part of the example shows how to define the parser. The parser is defined with the name of `calc:expr`. This parser accepts one argument which is a lazy sequence provided by SRFI-127 `(srfi :127)`, and returns 3 values, parse state, parser value and next input.

NOTE: A lazy sequence is a pair, whose `cdr` part might be a generator. A normal pair can also be a lazy sequence.

    (import (rnrs)
    	(peg)
    	(peg chars)
    	(srfi :14 char-sets)
    	(srfi :121 generators)
    	(srfi :127 lseqs))

    (define ascii-digits (char-set-intersection char-set:digit char-set:ascii))
    (define calc:num
      ($do (s ($optional ($or ($eqv? #\+) ($eqv? #\-)) #\+))
           (n ($many ($char-set-contains? ascii-digits) 1))
           ($return (string->number (apply string s n)))))
    (define (calc:op c)
      ($seq ($many ($satisfy char-whitespace?))
    	($eqv? c)
    	($many ($satisfy char-whitespace?))))
    (define calc:+ (calc:op #\+))
    (define calc:* (calc:op #\*))
    (define calc:open (calc:op #\())
    (define calc:close (calc:op #\)))

    (define calc:simple
      ($or ($do calc:open (a ($lazy calc:expr)) calc:close ($return a))
           calc:num))
    (define calc:mulexp
      ($or ($do (a calc:simple) calc:* (b calc:simple) ($return (* a b)))
           calc:simple))
    (define calc:expr
      ($or ($do (a calc:mulexp) calc:+ (b calc:mulexp) ($return (+ a b)))
           calc:mulexp))

The parser can be called like this:

    (calc:expr (generator->lseq (string->generator "1 + 2")))

#\<parse-succcess> 3 '()

The parser doesn't check if the input is consumed entirely. So this also returns success:

    (calc:expr (generator->lseq (string->generator "1 - 2")))

#\<parse-succcess> 1 '(#space #- #space #2)

If you want to make sure that the entire input is consumed, then you need to check if the next input is `()` or not.

NOTE: An input of parsers, which is lazy sequence, doesn't necessarily be a character sequence. So users can implmenet own lexer.

NOTE2: The above example of the parser usage can also be like this:

    (calc:expr (string->list "1 + 2"))

#\<parse-succcess> 3 '()

In this document, we always convert to a lazy sequence.

### Predefined parsers

Function $return v
Function $return v state
Function $return v state l

Returns a parser which returns given v as its value.

The second form specifies the state of parser result, which must be one of the followings:

- `+parse-success+` - Indicating successful parse result

- `+parse-fail+` - Indicating failure parse result

- `+parse-expect+` - Indicating different from expected input

- `+parse-unexpect+` - Indicating unexpectedly matched input

The third form specifies the state described above and the next input. The next input must be a lazy sequence.

Function $fail message

Returns a parser whose returning state is `+parse-fail+` and return value is given message.

Function $expect message

Returns a parser whose returning state is `+parse-expect+` and return value is given message.

Function $eof input

A parser which check if the input is exhausted or not.

It returns success if the input is exhausted otherwise `+parse-expect+` as its state.

Function $any input

A parser which consume the first element of input and returns success.

Function $empty v

Returns a parser which returns success and given v as its value without consuming input.

In the context of BNF term, this is called epsilon.

Function $satisfy pred
Function $satisfy pred message

Returns a parser which check if the first element of the input of the parser satisfies the given pred or not.

If the pred returns true value, then it return success and the first element. Otherwise `+parse-expect+`.

If the second form is used, then the message is returned when the pred returned `#f`.

Function $not parser

Returns a parser which uses the given parser as its parser and check if the returning state is not successful or not.

If the state is successful, then returns `+parse-unexpect+`, otherwise return successful and `#f` as its returning value.

Function $seq parser ...

Returns a parser which uses the given _parser_s as its parser.

It returns successful if all the given _parser_s return successful. The returning value is the last parser's value. Otherwise `+parse-expect+` is returned.

Function $or parser ...

Returns a parser which uses the given _parser_s as its parser.

It returns successful if one of the given _parser_s return successful. The returning value is the first successful parser's value. Otherwise `+parse-expect+` is returned.

If one of the parser returns `+parse-fail+`, then the entire parser returned by this procedure fails. For example, the parser after the `$fail` won't be evaluated.

    ($or ($satisfy char-whitespace?)
         ($fail "Boom!")
         ($satisfy char-lower-case?))

Function $many parser
Function $many parser at-least
Function $many parser at-least at-most

Returns a parser which uses the given parser as its parser.

The parser parses the input as long as the given parser returns successful state. The returning value is a list of the values returned by the given parser.

If the second or third form is used, then it limits the number of trial.

at-least specifies the number of minimum parse. If the given parser returned non successful state before this number, then the parser return `+parse-expect+`.

at-most specifies the number of maximum parse. If the parser parsed at-most input, then it returns successful even the rest of the input contains the valid input of the given parser.

Function $peek parser

Returns a parser which uses the given parser as its parser.

The parser returns successful if the given parser returns successful. The returning next input will not be consumed by the parser.

Function $eqv? obj

Returns a parser which compares the first element of the input and the given obj using `eqv?`.

If the comparison result is `#t`, then it returns successful.

This procedure is equivalent with the following:

    (define ($eqv? v) ($satisfy (lambda (e) (eqv? e v))))

Function $optional parser
Function $optional parser fallback

Returns a parser which uses the given parser as its parser.

The parser returns always successful state. The returning value is the value of the given parser if the parser returns successful. Otherwise `#f`.

If the second form is used, then fallback is returned when the parser returned non successful.

Function $repeat parser n

Returns a parser which uses the given parser as its parser.

The parser parses input exactly n times and returns a list of result value if the given parser returns n times successful.

This is equivalent with the following code:

    (define ($repeat parser n) ($many parser n n))

Function $bind parser f

Returns a parser which uses the given parser as its parser.

The f must be a procedure which takes one argument and returns a parser.

The parser returns the result of the parser created by f. The f is called when the given parser returned successful state, passed the returning value of the given parser.

The `$bind` is useful to take the result of the parsers.

This procedure is used to implement `$do` described below.

Macro $do clause . body

A macro which creates a parser.

The `$do` macro makes users easier to bind variables. The syntax is the following:

    $do    ::= ($do clause ... parser)
    clause ::= (var parser)
             | (parser)
    	 | parser

The following example shows how to bind a variable returned by the `$many`procedure.

    ($do (c* ($many ($satisfy char-numeric?)))
         ($return (string->number (list->string c*))))

The above parser parses given numeric character sequence and returns a number. The c* is the result of the $many.

Macro $lazy parser

A macro which creates a parser.

The `$lazy` macro delays the creation of parser. This macro is useful to handle cross reference. For example:

    (define a ($do (c b) ($return c)))
    (define b ($do (c a) ($return c)))

The above code causes unbound variable in runtime when the definition of `a` is evaluated. To avoid this, users can use the `$lazy` like this:

    (define a ($do (c ($lazy b)) ($return c)))
    (define b ($do (c a) ($return c)))

Macro $if pred then else

A macro which creates a parser.

The returning parser calls either then or else parser depending on the result of pred.

This is the simple example.

    ($if #t ($eqv? #\t) ($eqv? #\f))
    ;; ($eqv? #\t) will ba called

The `$if` can be used to dispatch parsers by the results like this:

    ($do (c ($optional ($eqv? #\t)))
         ($if c
              ($return c)
    	  ($return 'something)))

Macro $cond clause ...
Macro $cond clause ... (else parser)

A macro which creates a parser.

The clause must be the following form:

    clause ::= (pred parser)

The parser returned by this macro is similar with the one from `$if`, the difference is this macro can handle multiple predicates.

Macro $when pred parser
Macro $unless pred parser

A macro which creates a parser.

The `$when` macro returns a parser which calls the given _parser_only if the pred returned true value.

The `$unless` macro returns a parser which calls the given _parser_only if the pred returned `#f`.

They are defined like this:

    (define-syntax $when
      (syntax-rules ()
        ((_ pred body)
         ($if pred body ($fail 'pred)))))

    (define-syntax $unless
      (syntax-rules ()
        ((_ pred body)
         ($when (not pred) body))))

Macro $parameterize bindings parser

A macro which creates a parser.

The `$parameterize` macro returns a parser which calls the given parser in the extended dynamic extend with the given bindings.

The bindings must be the following form:

    bindings ::= ((parameter value) ...)

Macro $guard guard-clause parser

A macro which creates a parser.

The `$guard` macro returns a parser which is wrapped by the `guard`. When the given parser raises an error during parsing, then the guard-clause will be executed.

The guard-clause must be the following form: `guard-clause ::= (variable (pred clause) ...)` The pred must be a expression which checks if the raised condition should be handled by the coupled clause or not. If the _pred_is evaluated to true value, then the coupled clause is called with the input of the given parser.

### Character specific parsers

The procedures provided by the `(peg)` can be used for all kinds of input. This section describes parsers which can only be used for character input.

Library (peg chars)

Character specific PEG parser library.

Function $char-set-contains? char-set

Returns a parser which returns successful if the given char-set contains the input of the parser.

This procedure is defined like this:

    (define ($char-set-contains? s)
      ($satisfy (lambda (c) (char-set-contains? s c)) s))

Function $token string

Returns a parser which returns successful if the input of the parser matches with the given string.

This procedure is defined like this:

    (define ($token s) (apply $seq (map $eqv? (string->list s))))

## (rsa pkcs :5) - Password Based Cryptography library

This section describes the implementation of PKCS#5 specification library. However we do not describe PKCS#5 itself and I don't think it is necessary to know it if you just want to use it.

This example is the simplest way to use.

    (import (rnrs) (crypto) (rsa pkcs :5))
    (define salt (string->utf8 "salt"))
    (define iteration-count 1024)
    (define pbe-parameter (make-pbe-parameter salt iteration-count))
    (define pbe-key (generate-secret-key pbe-with-sha1-and-des "password"))
    (define pbe-cipher (cipher pbe-with-sha1-and-des pbe-key
                               :parameter pbe-parameter))
    (encrypt pbe-cipher (string->utf8 "This is an example."))
    ;; -> #vu8(254 229 155 168 167 192 249 43 33 192 161 215 28 117
    ;;         169 129 147 60 16 52 235 79 90 23)
    (decrypt pbe-cipher
    	 #vu8(254 229 155 168 167 192 249 43 33 192 161 215
                  28 117 169 129 147 60 16 52 235 79 90 23))
    ;; -> #vu8(84 104 105 115 32 105 115 32 97 110 32 101 120 97
    ;;         109 112 108 101 46)

The library itself defines simply its cipher and key generate methods. Hence user can use it with (crypto) library (see (crypto) - Cryptographic library)

NOTE: Currently the library only supports encryption and decryption, not MAC generation nor verification.

NOTE: When you create cipher object with PBE related algorithms, the you need to pass `:parameter` keyword to `cipher` procedure, otherwise raises an error.

Library (rsa pkcs :5)

This library exports PKCS#5 related cryptographic procedures.

### User level APIs

Variable pbe-with-md5-and-des
Variable pbe-with-md5-and-rc2
Variable pbe-with-sha1-and-des
Variable pbe-with-sha1-and-rc2

The algorithms used in PBES1 encryption and decryption and key generation.

The names describe the using hash functions and cryptographic schemes. For example, `pbe-with-md5-and-des` uses MD5 hash and DES algorithm.

Function make-pbe-parameter salt iteration-count

salt must be a bytevector.

iteration-count must be a non negative exact integer.

Creates a parameter for PBE key generation. salt is salt and iteration-count is the iteration count for key derivation.

Generic generate-secret-key algorithm (password )

algorithm must be one of the algorithms describes above.

Creates PBE secret key based on given password and algorithm.

### Low level APIs

These APIs are for users who want to create own PBE mechanism such as PKCS#12.

Function pbkdf-1 P S c dk-len :key (hash (hash-algorithm SHA-1)

Implementation of PBKDF1 describes in PKCS#5 specification.

The arguments are plain text (bytevector), salt (bytevector), iteration count (non negative exact integer) and key length (non negative exact integer) respectively.

The keyword argument hash specifies which hash algorithm will be used. The default is SHA-1.

Function pbkdf-2 P S c dk-len :key (hash (hash-algorithm SHA-1) _

_ (prf (hash-algorithm HMAC :key P :hash hash))

Implementation of PBKDF2 describes in PKCS#5 specification.

The arguments are plain text (bytevector), salt (bytevector), iteration count (non negative exact integer) and key length (non negative exact integer) respectively.

The keyword argument hash specifies which hash algorithm will be used in PRF function. The default is SHA-1 and if you don't have any reasonable reason, this must not be changed.

The keyword argument prf specifies underlying pseudo random function which must be hash object implemented with `<user-hash-algorithm>` describes in Custom hash algorithm. The default is HMAC and if you don't have any reasonable reason, this must not be changed.

Function derive-key P S c dk-len :key (kdf pbkdf-2) :allow-other-keys

The implementation of key derive function. The required arguments are the same as above `pbkdf-1` and `pbkdf-2`.

This procedure just calls given kdf with given arguments and returns derived key bytevector.

Generic derive-key&iv marker (key ) (parameter )

marker is user defined cipher type. key must be subclass of `<pbe-secret-key>`. parameter must be subclss of `<pbe-parameter>`.

This method is called in the `initialize` method of `<pbe-cipher-spi>` and must return 2 values; the first one is derived key as bytevector and second one is initial vector as bytevector.

The PKCS#5 encryption and decryption procedures require to derive both key and initial vector from given password and parameter (salt and iteration count). This method is used in PBE cipher to derive key and initial vector.

The purpose of this method is to re-use `<pbe-cipher-spi>`. For example, PKCS#12 can use this cipher, however it requires different key derivation mechanism.

### Supporting PBES2 functionality

Since I could not find any standard implementation, Sagittarius actually does not support PBES2 encryption and decryption. However supporting it is not so difficult. This is the sample code to support it.

    (import (rnrs) (clos user) (rfc hmac) (math))
    (define-class <pbkef2-with-hmac-sha1-des3> () ())
    (define pbkdf2-with-hmac-sha1-des3 (make <pbkef2-with-hmac-sha1-des3>))
    (define-method generate-secret-key ((mark <pbkef2-with-hmac-sha1-des3>)
    				    (password <string>))
      (make <pbe-secret-key> :password  password :hash (hash-algorithm HMAC)
    	:scheme DES3 :iv-size 8 :length 24
    	:type PKCS5-S2))
    (register-spi pbkdf2-with-hmac-sha1-des3 <pbe-cipher-spi>)

And using this supported PBES2 cipher is like this;

    (let* ((param (make-pbe-parameter (string->utf8 "saltsalt") 1024))
           (key (generate-secret-key pbkdf2-with-hmac-sha1-des3 "password"))
           (pbe-cipher (cipher pbkdf2-with-hmac-sha1-des3 key :parameter param))
           (ciphertext (encrypt pbe-cipher (string->utf8 "This is an example."))))
      (utf8->string (decrypt pbe-cipher ciphertext)))

I suppose this is correct, but I could not find any implementation which supports PBES2. I usually test with JCE, so if you have some recommendation, please let me know.

## (rsa pkcs :12) - PKCS#12

This section describes the implementation of PKCS#12 specification library. However we do not describe PKCS#12 itself and I don't think it is necessary to know it if you just want to use it.

Library rsa pkcs :12

This library provides procedures for PKCS#12 operations.

### Keystore APIs

The example shows how to use keystore APIs:

    (import (rnrs) (rsa pkcs :12))

    (define keystore (load-pkcs12-keystore-file "keystore.p12" "pass"))

    (pkcs12-keystore-get-key keystore "key-name" "key-pass")
    ;; -> <private-key>

    (pkcs12-keystore-get-certificate keystore "cert-name")
    ;; -> <x509-certificate>

    ;; certs are list of X509 certificate associated with given private-key
    (pkcs12-keystore-set-key! keystore "key-name2" private-key "key-pass2" certs)

    ;; cert must be an X509 certificate
    (pkcs12-keystore-set-certificate! keystore "cert-name2" cert)

    (store-pkcs12-keystore-to-file keystore "keystore2.p12" "pass2")

Class <pkcs12-keystore>

PKCS#12 keystore class.

Function pkcs12-keystore? obj

Returns #t if given obj is PKCS#12 keystore object, otherwise #f.

Function make-pkcs12-keystore

Returns newly created PKCS#12 keystore object.

Function load-pkcs12-keystore input-port storepass
Function load-pkcs12-keystore-file file storepass

Loads PKCS#12 keystore from given input-port or file and returns newly created keystore object.

The `load-pkcs12-keystore` loads from given binary input port.

The `load-pkcs12-keystore-file` loads from given file.

storepass must be a string and a password for given keystore.

Function pkcs12-keystore-get-key keystore alias keypass

Retrives a private key associated with alias from keystore. If there is no key entry associated with alias then #f is returned.

alias must be a string.

keypass must be a string. It is used to decrypt the private key and it is not allowed to pass empty password.

Function pkcs12-keystore-get-certificate keystore alias

Retrives a certificate associated with alias from keystore. If there is no certificate entry associated with alias then #f is returned.

alias must be a string.

Function pkcs12-keystore-get-certificate-chain keystore alias

Retrives certificate chain associated with given key alias _alias_from keystore. If there is no certificate chain then `'()` is returned.

alias must be a string.

Function pkcs12-keystore-contains-alias? keystore alias

Returns #t if keystore contains alias. Otherwise #f.

Function store-pkcs12-keystore keystore output-port storepass
Function store-pkcs12-keystore-to-file keystore file storepass

Writes given keystore to output-port or file.

The `store-pkcs12-keystore` writes to given binary output port output-port.

The `store-pkcs12-keystore-to-file` writes to given file file.

storepass must be a string and is used to encrypt whole contents.

Function pkcs12-keystore-set-key! keystore alias private-key key-pass certs

alias must be a string represents the name of private-key in the keystore.

private-key must be an RSA private key.

key-pass must be a string and is used to encrypt given private-key.

certs must be a list of X509 certificates which associated with private-key.

Stores given private-key to keystore.

The implementation allows users to set separate password from storepass. Be aware that current implementation of Bouncy Castle JCE uses the same password as storepass to encrypt a private key. Thus if you use different password, then it is not compatible with Bouncy Castle.

Function pkcs12-keystore-set-certificate! keystore alias cert

alias must be a string represents the name of cert in keystore.

cert must be an X509 certificate.

Stores given cert to keystore.

Function pkcs12-keystore-delete-entry! keystore alias

alias must be a string.

Removes the entry associated with alias in keystore.

Function pkcs12-keystore-aliases keystore

Returns all defined names in keystore.

## (util queue) - Queue

Library (util queue)

This library provides queue (FIFO) data structure and its operations.

You can create a simple queue, which is not thread-safe, or an MT queue, a thread-safe queue. Basic queue operations work on both type of queues. When a mtqueue is passed to the procedures listed in this section, each operation is done in atomic way, unless otherwise noted.

There are also a set of procedures for mtqueues that can be used for thread synchronisation; for example, you can let the consumer thread block if an mtqueue is empty, and/or the producer thread block if the number of items in the mtqueue reaches a specified limit. Using these procedures allows the program to use an mtqueue as a channel.

The simple queue API is a super set of SLIB's queue implementation.

NOTE: (util deque) is used as underlying library.

Class <queue>

A class of simple queue.

Class <mtqueue>

A class of mtqueue. Inherits `<queue>`.

Function make-queue

Creates and return an empty simple queue.

Function make-mtqueue :key max-length

Creates and return an empty mtqueue.

The keyword argument max-length specifies the maximum entry count of the queue. Negative number indicates unlimited number of entry. If the given number is zero then the queue cannot hold any item.

Function queue? obj

Returns #t if obj is a queue (either a simple queue or an mtqueue).

Function mtqueue? obj

Returns #t if obj is an mtqueue.

Function queue-empty? queue

Returns #t if queue is an empty queue.

Function queue-length queue

Returns the number of the items in the queue.

Function mtqueue-max-length mtqueue

Returns the maximum number of items mtqueue can hold. #f indicates unlimited.

Function mtqueue-room mtqueue

Returns the number of elements mtqueue can accept at this moment before it hits its maximum length. If the queue has unlimited capacity then the procedure returns `+inf.0`.

Function copy-queue queue

Returns a copy of queue.

Function enqueue! queue obj more-objs ...

Adds obj to the end of queue. You may give more than one object, and each of them are enqueued in order.

If queue is an mtqueue, all the objects are enqueued atomically; no other objects from other threads can be inserted between the objects given to a single `enqueue!` call. Besides, if the value of the result of `mtqueue-max-length` is positive, and adding objs makes the number of element in queue exceeds it, an error is raised and queue won't be modified. (If the maximum length is zero, this procedure always fail. Use `enqueue/wait!` below.)

Function queue-push! queue obj more-objs ...

Adds obj to in front of queue. You may give more than one object, and each of them are pushed in order.

Like `enqueue!`, when queue is an mtqueue, all objects are added atomically, and the value of max length is checked. See `enqueue!` above for more detail.

Function enqueue-unique! queue eq-proc obj more-objs ...
Function queue-push-unique! queue eq-proc obj more-objs ...

Like `enqueue!` and `queue-push!`, respectively, except that these don't modify queue if it already contains objs (elements are compared by two-argument procedure eq-proc).

When queue is an mtqueue, all objects are added atomically, and the max length is checked. See `enqueue!` above for the detail.

Function dequeue! queue :optional fallback
Function queue-pop! queue :optional fallback

Take one object from the front of queue and return it. Both function work the same, but `queue-pop!` may be used to emphasize it works with `queue-push!`.

If queue is empty, fallback is returned if give, otherwise an error is raised.

If queue is mtqueue and its max length is zero, then the queue is always empty. Use `dequeue/wait!` to use such a queue as a synchronisation device.

Function dequeue-all! queue

Returns the whole content of queue by a list, with emptying queue. If queue is empty, returns an empty list. See also `queue->list` below.

Function queue-front queue :optional fallback
Function queue-rear queue :optional fallback

Peek the head or the tail of queue and return the object, respectively.

If queue is empty, fallback is returned if give, otherwise an error is raised.

Function list->queue list :optional class :rest initargs

Returns a new queue which content is the elements in list, in the given order.

By default the created queue is a simple queue, but you can create mtqueue or instance of other subclass `<queue>` by giving the class to the optional class arguments. The optional initargs arguments are passed to the constructor of class.

Function queue->list queue

Returns a list whose content is the items in queue in order. Unlike `dequeue-all!`, the content of queue remains intact. The returning list is a copy of the content. So modifying the list won't affect queue.

Function find-in-queue pred queue

Returns the first item in queue that satisfies a predicate pred.

Function any-in-queue pred queue

Apply pred on each item in queue until it evaluates true, and returns that true value. If no item satisfies pred, #f is returned.

Function every-in-queue pred queue

Apply pred on each item in queue. If pred returns #f, stops iteration and returns #f immediately. Otherwise, returns the result of pred on the last item of queue. If the queue is empty, #t is returned.

Function remove-from-queue! pred queue

Removes all items in queue that satisfies pred. Returns #t if any item is removed. Otherwise #f.

Function enqueue/wait! mtqueue obj :optional timeout timeout-val
Function queue-push/wait! mtqueue obj :optional timeout timeout-val
Function dequeue/wait! mtqueue :optional timeout timeout-val
Function queue-pop/wait! mtqueue :optional timeout timeout-val

These synchronising variants work on an mtqueue and make the caller thread block when the mtqueue has reached its maximum length (for `enqueue/wait!` and queue-push/wait!), or the mtqueue is empty (for `dequeue/wait!` and queue-pop/wait!). The blocked caller thread is unblocked either the blocking condition is resolved, or the timeout condition is met.

The optional timeout argument specifies the timeout condition. If it is #f, those procedure wait indefinitely. If it is a real number, they wait at least the given number of seconds.

In case the call is blocked then timed out, the value of timeout-val is returned, which default value is #t.

When `enqueue/wait!` and `queue-push/wait!` succeeds without hitting timeout, they return #t.

## (record builder) - Record builder

Library (record builder)

Record builder library. This library provides utilities to construct a record instance easily.

The following example shows how to use the `make-record-builder`macro.

    (define-record-type base
      (fields a b c))
    (define-syntax base-builder
      (make-record-builder base ((a 'a) (c 'c symbol->string))))

    (base-builder)

#\<base a='a b=#f c="c">

    (define-record-type child
      (parent base)
      (fields d e f))
    (define-syntax child-builder
      (make-record-builder child ((a 'b))))

    (child-builder)

#\<child a='b b=#f c=#f d=#f e=#f f=#f>

Macro make-record-builder rtd (default ... )

Make a record builder macro transformer.

Default must be one of the following form:

    (_field-name_ _value_)

    (_field-name_ _value_ _converter_)

field-name must be a field name of the rtd. value is a default in case the builder didn't receive the field. The _converter_of the second form must be a procedure which accepts one argument. The result of this procedure will be used to instantisate the record. It will also apply the value.

The result of the macro transformer accepts the following forms:

    (_field-name_ _value_) ...

    (`from` _record-instance_) (_field_ _value_) ...

The `from` is an auxiliary macro bound in the `(record builder)`. The value of `from`, record-instance, will be copied to the creating record.

## (rfc :5322) - Internet message format library

Library (rfc :5322)

This library provides the procedures for internet message format defined in RFC5322(RFC 5322).

### Parsing message headers

Function rfc5322-read-headers input-port :key (strict? #f) reader

input-port must be input port and will be passed to reader.

Reads RFC5322 format message from the given port until it reaches the end of the message header and returns a list of the following format;

    ((name body) ...)

name ... are the field names and body ... are the correspoinding field body. Both are as string. Field names are converted to lower-case characters.

The keyword argument strict? switches the behaviour when the procedure encounter EOF. If it's #f, then it simply ignore the field and return the composed list. And if it's #t, it raises `&rfc5322-parse-error`.

The keyword argument reader reads a line from given port. The default is `rfc5322-line-reader` and it treats both LF and CRLF eof style. If you want to read from binary port, you need to pass own reader.

Function rfc5322-line-reader input-port

input-port must be textual input port.

Reads a line from given port. If the last character is CR chop it off.

Function rfc5322-header-ref header-list field-name . maybe-default

An utility procedure to get a specific field from the parsed header list, which is returned by `rfc5322-read-headers`.

If the field with given field-name is in header-list, the procedure returns its value in a string. Otherwise, if default is given, it is returned, and if not, #f is returned.

Function rfc5322-header-ref* header-list field-name

An utility procedure to get a specific field from the parsed header list, which is returned by `rfc5322-read-headers`.

This procedure collects all the given field-name from the header-list. If there's no header named field-name, then the procedure returns `()`.

### Basic field parsers

Function rfc5322-next-token input-port :optional tokenizer-spec

input-port must be textual input port.

A basic tokenizer. First it skips whitespaces and/or comments (CFWS) from input-port, if any. Then reads one token according to var{tokenizer-specs}. If input-port reaches EOF before any token is read, EOF is returned.

tokenizer-specs is a list of tokenizer spec. which is a cons of a char-set and a procedure.

After skipping CFWS, the procedure peeks a character at the head of input-port, and checks it against the char-sets in _tokenizer-specs_one by one. If a char-set that contains the character belongs to is found, then a token is retrieved with calling the procedure with input-port to read a token.

If the head character doesn’t match any char-sets, the character is taken from input-port and returned.

The default tokenizer-specs is as follows:

    (list (cons (string->char-set ":") rfc5322-quoted-string) (cons *rfc5322-atext-chars* rfc5322-dot-atom))

Function rfc5322-field->tokens field :optional tokenizer-spec

A convenience procedure. Creates a string input port from given field and calls `rfc5322-next-token` repeatedly on it until it consumes all input, and returns a list of tokens.

Function rfc5322-skip-cfws input-port

Consumes whitespace characters and/or any comments from _input-port_and returns a non comment and whitespace character. The returned character remains in input-port.

Variable *rfc5322-atext-chars*

A character set which is defined RFC 5322 section 3.2.3 Atom.

Variable *rfc5322-standard-tokenizers*

Default tokenizer.

Function rfc5322-dot-atom input-port
Function rfc5322-quoted-string input-port

Tokenizers for `dot-atom` and `quoted-string` respectively.

### Specific field parsers

Function rfc5322-parse-date string

Takes RFC-5322 type date string and returns eight values:

`year, month, day-of-month, hour, minute, second, time-zone, day-of-week.`time-zone is an offset from UT in minutes. day-of-week is a day from sunday, and may be #f if that information is not available. month is an integer between 1 and 12, inclusive. If the string is not parsable, all the elements are #f.

### Message constructors

Function rfc5322-write-headers headers :key (output (current-output-port)) _

_ (check :error) (continue #f)

Writes the given header to the port output.

Function date->rfc5322-date date

date must be SRFI-19 date.

Returns RFC 5322 date formatted string.

## (rfc base32) - Base 32 encode and decode library

Library (rfc base32) 0.9.12

This library provides Base 64 encoding and decoding procedures.

### Encoding procedures

Function base32-encode in . keyword-options
Function base32hex-encode in . keyword-options

in must be either a bytevector or binary input port.

Encodes given input in to Base 64 encoded bytevector.

The `base32hex-encode` encodes the given input to Base 32 Hex encoded bytevector.

The keyword-options will be passed to the encoder. See `make-base32-encoder` procedure for more detail.

Function base32-encode-string string :key transcoder :allow-other-keys keyword-options
Function base32hex-encode-string string :key transcoder :allow-other-keys keyword-options

Convenient procedure for string.

Encodes given string to Base 64 encoded string.

The keyword argument transcoder is used to convert given string to bytevector. The converted bytevector will be passed to the `base32-encode`procedure. The default value is a transcoder with UTF-8 codec with EOL style none.

The `base32hex-encode-string` encodes the given input to Base 32 Hex encoded bytevector.

The keyword-options will be passed to the encoder. See `make-base32-encoder` procedure for more detail.

Function open-base32-encode-input-port source :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32-encode-output-port sink :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32hex-encode-input-port source :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32hex-encode-output-port sink :key ( owner? #f) :allow-other-keys keyword-options

Creates binary Base32 encode input and output port, respectively.

source must be binary inpurt port.

The input port reads bytes from source and returns Base32 encoded result.

sink must be binary inpurt port.

The output port puts encoded bytes to sink. The port must be closed to finish the encoding process properly.

The `open-base32hex-encode-input-port` and `open-base32hex-encode-output-port` encode to Base32 Hex encode.

The keyword-options will be passed to the encoder. See `make-base32-encoder` procedure for more detail.

### Decoding procedures

Function base32-decode in . keyword-options
Function base32hex-decode in . keyword-options

in must be a bytevector or binary input port.

Decode Base 64 encoded input in to original bytevector.

The `base32hex-decode` decodes Base32 Hex encoded value.

The keyword-options will be passed to the encoder. See `make-base32-decoder` procedure for more detail.

Function base32-decode-string string :key (transcoder (native-transcoder)) :allow-other-keys keyword-options
Function base32hex-decode-string string :key (transcoder (native-transcoder)) :allow-other-keys keyword-options

Convenient procedure.

Decode Base 64 encoded string to original string. The procedure is using `base32-decode`.

The keyword argument specifies how to convert the decoded bytevector to string. If this is #f, the procedure returns raw bytevector.

The `base32hex-decode-string` decodes Base32 Hex safe encoded value.

The keyword-options will be passed to the encoder. See `make-base32-decoder` procedure for more detail.

Function open-base32-decode-input-port source :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32-decode-output-port sink :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32hex-decode-input-port source :key ( owner? #f) :allow-other-keys keyword-options
Function open-base32hex-decode-output-port sink :key ( owner? #f) :allow-other-keys keyword-options

Creates binary Base32 decode input and output port, respectively.

source must be binary inpurt port.

The input port reads Base32 encoded bytes from source and returns decoded results.

sink must be binary inpurt port.

The output port puts decoded bytes to sink. The port must be closed to finish the encoding process properly.

The `open-base32hex-decode-input-port` and `open-base32hex-decode-output-port` decode Base32 Hex safe encoded value.

The keyword-options will be passed to the encoder. See `make-base32-decoder` procedure for more detail.

### Low level APIs

Both encode and decode procedures are using encoder and decoder. Both encoder and decoder are just a procedure which takes 2 arguments get and put and not reentrant as they have own internal buffer to process the input.

Function make-base32-encoder :key ( encode-table `*base32-encode-table*` ) ( line-width 76) ( padding? #t) ( linefeeds #f)
Function make-base32hex-encoder :key ( encode-table `*base32hex-encode-table*` ) ( line-width 76) ( padding? #t) ( linefeeds #f)

encode-table must be a valid Base 32 encode table.
line-width must be either `#f` or integer.
padding? must be a boolean value.
linefeeds must be `#f` or u8 list reporesents end of line.__

Creates a Base32 encoder. An encoder is a procedure which takes 2 arguments get and put.

get must be a procedure takes 0 argument and it must return one of the followings; a fixnum of range 0 to 255, EOF object, or negative integer. The fixnum value is treated as an input of the encoding value. The negative integer value is treated as a continue marker. When the encoder receives this value, then it won't encode until the next value is available.

put must be a procedure takes 1 argument which is either a fixnum of range 0 to 255 or `#f`. The fixnum is the encoded value of the input. `#f` indicates line break point, so user can determine which line break this encoder should use.

The keyword argument encode-table specifies the encoding rule. The procedure name represents the default value of the rule, however if you specify the other table, then it can encode the value according to the given value.

The keyword argument line-width specifies where the encode procedure should put linefeed. If this is less than 1 or #f, encoder does not put linefeed.

The keyword argument padding? controls if the result encoded value contains padding character `#\=` or not. If this is #f, then the result value won't contain padding character.

The keyword argument linefeeds controls the end of line. By default, it emits `LF (0x0a)`. If you want to put CRLF, then you can specify this value with `(#x0d #x0a)`

Function make-base32-decoder :key ( decode-table `*base32-decode-table*` )
Function make-base32hex-decoder :key ( decode-table `*base32hex-decode-table*` )

decode-table must be a valid Base 32 decode table.

Creates a Base32 decoder. A decoder is a procedure which takes 2 arguments get and put.

get is the same as the one from encoder.

put must be a procedure takes 1 arguments which is a fixnm of range 0 to 255. The value is always a decoded byte.

The keyword argument decode-table specifies the decoding rule. The procedure name represents the default value of the rule, however if you specify the other table, then it can decode the value according to the given value.

Constant *base32-encode-table*
Constant *base32-decode-table*
Constant *base32hex-encode-table*
Constant *base32hex-decode-table*

Default encode or decode tables. If the name contains `url`, then it is suitable for "base32hex".

## (rfc base64) - Base 64 encode and decode library

Library (rfc base64)

This library provides Base 64 encoding and decoding procedures.

### Encoding procedures

Function base64-encode in :key ( line-width 76) ( padding? #t)
Function base64url-encode in :key ( line-width #f) ( padding? #f)

in must be either a bytevector or binary input port.

Encodes given input in to Base 64 encoded bytevector.

The keyword argument line-width specifies where the encode procedure should put linefeed. If this is less than 1 or #f, encoder does not put linefeed.

The keyword argument padding? controls if the result encoded value contains padding character `#\=` or not. If this is #f, then the result value won't contain padding character.

The `base64url-encode` encodes the given input to Base 64 URL safe encoded bytevector. Which doesn't use `+` and `/`.

Function base64-encode-string string :key ( line-width 76) transcoder ( padding? #t)
Function base64url-encode-string string :key ( line-width #f) transcoder ( padding? #f)

Convenient procedure for string.

Encodes given string to Base 64 encoded string.

The keyword argument transcoder is used to convert given string to bytevector. The converted bytevector will be passed to the `base64-encode` procedure. The default value is a transcoder with UTF-8 codec with EOL style none.

The keyword argument padding? is the same as `base64-encode`.

The `base64url-encode-string` encodes the given input to Base 64 URL safe encoded bytevector. Which doesn't use `+` and `/`.

Function open-base64-encode-input-port source :key ( owner? #f) ( line-width #f) ( padding? #t)
Function open-base64-encode-output-port sink :key ( owner? #f) ( line-width #f) ( padding? #t)
Function open-base64url-encode-input-port source :key ( owner? #f) ( line-width #f) ( padding? #f)
Function open-base64url-encode-output-port sink :key ( owner? #f) ( line-width #f) ( padding? #f)

Creates binary Base64 encode input and output port, respectively.

source must be binary inpurt port.

The input port reads bytes from source and returns Base64 encoded result.

sink must be binary inpurt port.

The output port puts encoded bytes to sink. The port must be closed to finish the encoding process properly.

The keyword argument padding? is the same as `base64-encode`.

The `open-base64url-encode-input-port` and `open-base64url-encode-output-port` encode to Base64 URL safe encode.

### Decoding procedures

Function base64-decode in
Function base64url-decode in

in must be a bytevector or binary input port.

Decode Base 64 encoded input in to original bytevector.

The `base64url-decode` decodes Base64 URL safe encoded value.

Function base64-decode-string string :key ( transcoder `(native-transcoder)` )
Function base64url-decode-string string :key ( transcoder `(native-transcoder)` )

Convenient procedure.

Decode Base 64 encoded string to original string. The procedure is using `base64-decode`.

The keyword argument specifies how to convert the decoded bytevector to string. If this is #f, the procedure returns raw bytevector.

The `base64url-decode-string` decodes Base64 URL safe encoded value.

Function open-base64-decode-input-port source :key ( owner? #f)
Function open-base64-decode-output-port sink :key ( owner? #f)
Function open-base64url-decode-input-port source :key ( owner? #f)
Function open-base64url-decode-output-port sink :key ( owner? #f)

Creates binary Base64 decode input and output port, respectively.

source must be binary inpurt port.

The input port reads Base64 encoded bytes from source and returns decoded results.

sink must be binary inpurt port.

The output port puts decoded bytes to sink. The port must be closed to finish the encoding process properly.

The `open-base64url-decode-input-port` and `open-base64url-decode-output-port` decode Base64 URL safe encoded value.

### Low level APIs

Both encode and decode procedures are using encoder and decoder. Both encoder and decoder are just a procedure which takes 2 arguments get and put and not reentrant as they have own internal buffer to process the input.

Function make-base64-encoder :key ( encode-table `*base64-encode-table*` ) ( line-width 76) ( padding? #t) ( linefeeds #f)

encode-table must be a valid Base 32 encode table.
line-width must be either `#f` or integer.
padding? must be a boolean value.
linefeeds must be `#f` or u8 list reporesents end of line.__

Creates a Base64 encoder. An encoder is a procedure which takes 2 arguments get and put.

get must be a procedure takes 0 argument and it must return one of the followings; a fixnum of range 0 to 255, EOF object, or negative integer. The fixnum value is treated as an input of the encoding value. The negative integer value is treated as a continue marker. When the encoder receives this value, then it won't encode until the next value is available.

put must be a procedure takes 1 argument which is either a fixnum of range 0 to 255 or `#f`. The fixnum is the encoded value of the input. `#f` indicates line break point, so user can determine which line break this encoder should use.

The following shows how to make Base64 encoder with line break of CRLF.

    (define (base64-encode-w/crlf bv)
      (let-values (((out e) (open-bytevector-output-port)))
        (define (put v)
          (if v
    	  (put-u8 out v)
    	  (begin (put-u8 out #x0d) (put-u8 out #x0a))))
        (define inp (open-bytevector-input-port bv))
        (define (in) (get-u8 inp))
        (define encoder (make-base64-encoder))
        (do () ((encoder in put)))
        (e)))

Function make-base64-decoder :key ( decode-table `*base64-decode-table*` )

Creates a Base64 decoder. A decoder is a procedure which takes 2 arguments get and put.

get is the same as the one from encoder.

put must be a procedure takes 1 arguments which is a fixnm of range 0 to 255. The value is always a decoded byte.

Constant *base64-encode-table*
Constant *base64-decode-table*
Constant *base64-encode-url-table*
Constant *base64-decode-url-table*

Default encode or decode tables. If the name contains `url`, then it is suitable for "base64url".

## (rfc cmac) - CMAC library

This section describes the CMAC extension of hash algorithm. The CMAC itself is described RFC 4493.

Library (rfc cmac)

This library is kept only for backward compatibility purpose. For newer application, use `(sagittarius crypto mac)` .

Provides CMAC hash algorithm.

The RFC is defined for only AES block cipher however the implementation can take any block cipher such as DES3.

CAUTION: only AES cipher is tested.

Function make-cmac key opts ...

Creates a MAC object of CMAC algorithm. key must be a bytevector.

Function generate-mac ( mac `mac?` ) ( message `bytevector?` ) :optional length
Function generate-mac! ( mac `mac?` ) ( message `bytevector?` ) ( out `bytevector?` ) :optional start length
Function verify-mac ( mac `mac?` ) ( message `bytevector?` ) ( auth-mac `bytevector?` )
Function mac-init! ( mac `mac?` )
Function mac-process! ( mac `mac?` ) ( message `bytevector?` ) :optional start length
Function mac-done! ( mac `mac?` ) ( out `bytevector?` ) :optional start length

These procedures are re-exported from `(sagittarius crypto mac)`.

Variable CMAC

The name for CMAC hash algorithm, which can be used with `(math hash)` library.

The following example explains, how to use it.

    (import (rnrs) (rfc cmac) (math) (crypto))

    (define K (generate-secret-key AES (integer->bytevector
    				    #x2b7e151628aed2a6abf7158809cf4f3c)))

    (define aes-cipher (cipher AES K))

    (hash CMAC #vu8() :cipher aes-cipher)
    ;; => #vu8(187 29 105 41 233 89 55 40 127 163 125 18 155 117 103 70)

    ;; for AES-CMAC-96
    (hash CMAC #vu8() :cipher aes-cipher :size (/ 96 8))
    ;; => #vu8(187 29 105 41 233 89 55 40 127 163 125 18)

## (rfc hmac) - HMAC library

This section describes the HMAC extension of hash algorithm. The HMAC itself is described RFC 2104. The provided library make user be able to use the algorithm with the APIs of math library's hash algorithm APIs. For the APIs detail, see Hash operations.

Library (rfc hmac)

Provides HMAC hash algorithm.

Variable HMAC

The name for HMAC hash algorithm.

The following example explains, how to use it.

    (import (rnrs) (rfc hmac) (math))
    ;; the keyword arguments can be omitted, then it will use an empty bytevector
    ;; as HMAC key and SHA-1 algorithm as digest algorithm.
    (define hmac (hash-algorithm HMAC :key (string->utf8 "hmac key") :hash SHA-1))
    (hash hmac (string->utf8 "test"))
    ;; -> #vu8(57 255 153 118 15 133 255 73 12 199 199 115 185 32 43 225 61 254 159 94)

## (rfc http) - HTTP client

Library (rfc http)

This library provides simple HTTP client defined in RFC 2616.

The library only talks to HTTP 1.1 and provides part of the specified features. We may implement complete specification in future.

Following is the simple example to send GET method to a HTTP server.

    (import (rfc http))

    (define url "http://example.com/path")

    (let-values (((server path) (url-server&path url)))
      (http-get server path))
    ;; -> return 3 values
    ;; status
    ;; header
    ;; body

Condition &http-error

HTTP error condition.

Function http-error? obj

Return #t if given obj is HTTP condition, otherwise #f.

### Request APIs

Function http-get server path options ...
Function http-head server path options ...
Function http-post server path body options ...
Function http-put server path body options ...
Function http-delete server path options ...

Sends HTTP request to given path on server. The using methods are `GET`, `HEAD`, `POST`, `PUT`, and `DELETE`, respectively.

The body argument of `http-post` and `http-put` can be UTF-8 string, bytevector or list of body parameters. The parameters are used for sending multipart form data. The detail parameter form is described in the `http-compose-form-data`.

The keyword :value and file should not be represented simultaneously, if both keywords are found then :file is used.

Optional arguments options are passed to underling procedure `http-request`.

Function http-request method server request-uri _

_ :key (no-redirect #f) _ _ (auth-handler #f) _ _ (auth-user #f) _ _ _ _ (auth-password #f) _ _ _ _ (user-agent (http-user-agent)) _ _ _ _ (secure #f) _ _ _ _ (receiver (http-string-receiver)) _ _ _ _ (sender #f) _ _ :allow-other-keys opts

Sends HTTP request to request-uri on server with method.

The keyword argument receiver is used to receive the response data. The value must be a procedure which takes four arguments, status code, headers, size of content, and thunk to retrieve remote binary port and its size.

The keyword argument sender is used for `POST` and `PUT`HTTP method to send data. If it's specified then it must be a procedure which takes three arguments, headers, encoding and header-sink.

NOTE: Users can define own receiver and sender however the API may change in the future. So if the predefined ones are sufficient, it is safe to use them.

The keyword arguments start with auth- handle authentication. If the server respond status code `401` then those values are used. auth-handler must be a procedure and takes five arguments alist of connection-info, auth-user, auth-password, response headers and response body. If the handler returns list of "authorization" value then `http-request` sends it as the authentication data. For example, if the server requires BASIC authentication then the procedure should return something like following value;

    (("authorization" "Basic dXNlcjpwYXNz"))

Following is the complete example of auth-handler;

    (define (basic-auth-handler info user pass headers body)
      (let ((m (format "~a:~a" user pass)))
        `(("authorization" ,(format "Basic ~a" (base64-encode-string m))))))

`http-request` supports BASIC authentication and Digest authentication by default. If you know that the server requires one of each then specifying auth-user and auth-password is sufficient.

If keyword argument secure is true value then TLS socket is used for physical connection.

The rest arguments opts is converted to request header.

Parameter *http-user-agent*

This parameter value is used for `user-agent` header.

### Senders and receivers

Function http-null-sender

Creates a sender which sends nothing.

Function http-string-sender str

Creates a sender which content is str.

The string will be converted to bytevector according to the encoding argument when the sender is called.

Function http-blob-sender blob

blob must be a string or bytevector.

Creates a sender which content is blob. If the blob is string, it will be converted to bytevector with `string->utf8`.

Function http-multipart-sender params

Creates a sender which send `multipart/form-data` with content of param.

The content will be created by `http-compose-form-data` procedure passing param.

Function http-string-receiver
Function http-binary-receiver
Function http-null-receiver

Creates a receiver which returning content is string, bytevecotor and unspecified value, respectively.

    (http-get "google.com" "/" :receiver (http-string-receiver))

status headers and string representation of received content

    (http-get "google.com" "/" :receiver (http-binary-receiver))

status headers and bytevector representation of received content

    (http-get "google.com" "/" :receiver (http-null-receiver))

status headers and unspecified value

Function http-oport-receiver sink flusher

The sink must be a binary output port, flusher must be a procedure takes two arguments, sink and headers.

Creates a receiver which stores the content of response to sink and returns the result of flusher.

    (http-get "google.com" "/"
              :receiver (let-values (((port extract)
                                      (open-bytevector-output-port)))
                          (http-oport-receiver port
                                               (lambda (port size) (extract)))))

status headers and bytevector representation of received content

Function http-file-receiver filename :key (temporary? #f)

filename must be a string.

Creates a receiver which stores the content to a file. The receiver returns the file name.

If keyword arguments temporary? specified with true value, then the returning file name is temporary file.

If there is no response or `content-length` header contains non number value, then the file will be cleaned.

    (http-get "google.com" "/" :receiver (http-file-receiver "google.html"))

status headers and "google.html"

Function http-gzip-receiver receiver

receiver must be an HTTP receiver.

Creates a receiver which handles gzip encoded response. If HTTP response contains `Content-Encoding` header with value `gzip`, then the receiver decodes the response and propagates to given receiver. Otherwise, it simply forwards the response to receiver.

The following describes how to use it:

    (http-get "google.com" "/"
              :accept-encoding "gzip"
              :receiver (http-gzip-receiver (http-string-receiver)))

### Utilities

Function http-compose-query path params :optional (encoding 'utf-8)

Composes query string.

If given path is #f then only composed query string is returned, otherwise this returns `_path_?_composed query_` form.

params must be a list of name & value list or null list.

Function http-compose-form-data params port :optional (encoding 'utf-8)

Composes multipart form data.

If port is #f then it returns composed string. if it's a port then the result is stored in the given port.

The params must be following form;

     <params> : (<params> ...)
     <param>  : (<name> <value>)
              | (<name> <key> <value> <key2> <value2> ...)
     <key>    : :value | :file | :content-type | :content-transfer-encoding
              | other keyword (used as a header name)

<value> is the content of <name> parameter. It can be any of Scheme object however it is converted to string representation except bytevector.

If :file keyword is used then it read the content of <value>.

Function url-server&path url

Decompose the given url and returns auth part of URL and path + query + fragment.

## (rfc http2) - HTTP/2 client

Library (rfc http2)

This library provides simple client HTTP/2 defined in RFC 7540.

The library does not support `Upgrade` header defined in HTTP/1.1. Thus users must know if the server supports HTTP/2 or not, ahead.

Following is the simple example to send GET method to a HTTP/2 server.

    (import (rfc http2))

    (define conn (make-http2-client-connection "twitter.com" "443" :secure? #t))
    (http2-get conn "/")
    ;; -> returns 2 values
    ;; header
    ;; body
    (close-http2-client-connection! conn)

Function http2-client-connection? obj

Returns #t if the given obj is an HTTP/2 client connection, otherwise #f.

Function make-http2-client-connection server port :key (secure? #f) user-agent

Creates an HTTP/2 client connection.

The server must be a string indicating an existing server name.

The post must be a string of either port number or service.

The keyword argument secure? specifies to use TLS or not.

The keyword argument user-agent specifies the value of `user-agent`header. The default value is `Sagittarius-` followed by version number.

NOTE: The connection does not guess if it should use secure connection or not by looking at port number or service name. Which means, even if you specify `"https"` or `"443"` however secure? keyword argument must be passed.

NOTE2: Created connections hold opened socket.

Function close-http2-client-connection! conn

Closes given HTTP/2 connection.

### High level APIs

Function http2-get conn uri :key receiver redirect-handler :allow-other-keys headers

Sends HTTP/2 GET request to given uri of HTTP/2 client connection conn and returns 2 values of the response, header and content.

The rest arguments headers must be a list of keyword and string. The procedure sends these pairs as extra headers.

If the keyword argument receiver is specified, then the procedure uses given receiver to receive data. The default value is `(make-gzip-receiver)`.

If the keyword argument redirect-handler is specified, then the procedure uses given redirect-handler to handle redirection.

Function http2-post conn uri data :key receiver redirect-handler :allow-other-keys headers

Sends HTTP/2 POST request to given uri of HTTP/2 client connection conn with given data and returns 2 values of the response, header and content. data must be a bytevector.

The rest arguments headers must be a list of keyword and string. The procedure sends these pairs as extra headers.

The keyword arguments receiver and redirect-handler are the same as `http2-get`.

Function http2-head conn uri :key receiver redirect-handler :allow-other-keys headers

Sends HTTP/2 HEAD request to given uri of HTTP/2 client connection conn and returns 2 values of the response, header and content.

The rest arguments headers must be a list of keyword and string. The procedure sends these pairs as extra headers.

The keyword arguments receiver and redirect-handler are the same as `http2-get`.

Macro http2-request conn method uri sender receiver :key redirect-handler

Sends an HTTP/2 request to given HTTP/2 client connection conn.

method must be a symbol.

sender must be a sender described below section.

receiver must be a receiver described below section.

redirect-handler is the same as `http2-get`.

The procedure returns a list of response header and content.

#### HTTP/2 sender

A sender is a procedure which accepts 2 arguments, internal HTTP/2 stream and flag. At this moment, the internal HTTP/2 stream is not exposed so users cannot create own sender.

Function http2-headers-sender header ...

Returns a sender which sends given header as HTTP/2 header.

Function http2-data-sender data

Returns a sender which sends given data as HTTP/2 data.

Function http2-composite-sender sender ...

Returns a composite sender.

#### HTTP/2 receiver

A receiver is a procedure which accepts 4 arguments, internal HTTP/2 stream, header, frame and flag. The same restriction as sender is applied, thus users cannot create own receiver, at this moment.

Function http2-data-receiver sink flusher

Returns a receiver which receives HTTP/2 data frame and put the value into sink. When the stream reaches to the end, then _flusher_is called with sink.

Function http2-binary-receiver

Returns a receives which receives HTTP/2 data frame as a bytevector.

Function http2-null-receiver

Returns a receives which receives HTTP/2 data frame and returns empty bytevector.

Function http2-gzip-receiver receiver

Returns a receives which receives HTTP/2 data frame. If the data frame is compressed to gzip, then the returning receiver expand the data and forward to the given receiver. If the data frame is not compressed, then it simply forward the data frame to the given receiver.

Function make-gzip-receiver

Convenient procedure whose definition is the following:

    (http2-gzip-receiver (http2-binary-receiver))

## (rfc http-connections) - HTTP client utilities

Library (rfc http)

This library provides common interfaces of `(rfc http)` and `(rfc http2)` library.

Function http-connection? obj

Returns #t if the given object is an HTTP connection.

Function http1-connection? obj

Returns #t if the given object is an HTTP/1.1 connection.

Function make-http1-connection server secure?

Creates an HTTP/1.1 connection with destination server server.

If the secure? is true value, then it uses TLS socket.

The HTTP/1.1 connection uses `http-request` defined in `(rfc http)`library to send an request.

Function http2-connection? obj

Returns #t if the given object is an HTTP/2 connection.

Function make-http2-connection server secure?

Creates an HTTP/2 connection with destination server server.

If the secure? is true value, then it uses TLS socket.

The HTTP/1.1 connection uses `http2-request` defined in `(rfc http2)`library to send an request.

Function http-connection-secure? http-connection

Returns #t if the given http-connection uses TLS socket to connect target server.

Function http-connection-server http-connection

Returns destination server of the http-connection as string.

Function http-connection-server&port http-connection

Returns destination server and port of the http-connection.

Function open-http-connection! http-connection

Opens given http-connection and returns it.

Function close-http-connection! http-connection

Closes given http-connection and returns it.

Function http-request http-connection method path . opt

Sends HTTP request to the path path of destination server of http-connection with HTTP method methos.

The rest value of opt is passed to underling request sending procedure.

The procedure returns 3 values, HTTP status, HTTP header and content as bytevector.

Generic http-null-receiver
Method http-null-receiver (conn http1-connection)
Method http-null-receiver (conn http2-connection)

Generic method of null http receiver.

The `http-null-receiver` forwards `http-null-receiver` defined in `(rfc http)` for `http1-connection` and `http2-null-receiver` defined in `(rfc http2)` for `http2-connection`

Generic http-oport-receiver
Method http-oport-receiver (conn http1-connection) sink flusher
Method http-oport-receiver (conn http2-connection) sink flusher

Generic method of output port http receiver.

The `http-oport-receiver` forwards `http-oport-receiver` defined in `(rfc http)` for `http1-connection` and `http2-data-receiver` defined in `(rfc http2)` for `http2-connection`

Generic http-blob-sender
Method http-blob-sender (conn http1-connection) blob
Method http-blob-sender (conn http2-connection) blob

Generic method of http blob sender.

The `http-blob-sender` forwards `http-blob-sender` defined in `(rfc http)` for `http1-connection` and `http2-data-sender` defined in `(rfc http2)` for `http2-connection`

Generic http-string-sender
Method http-string-sender (conn http1-connection) string
Method http-string-sender (conn http2-connection) string

Generic method of http string sender.

The `http-string-sender` forwards `http-string-sender` defined in `(rfc http)` for `http1-connection` and `http2-data-sender` defined in `(rfc http2)` with given string converted by `string->utf8` procedure defined for `http2-connection`

Generic http-null-sender
Method http-null-sender (conn http1-connection)
Method http-null-sender (conn http2-connection)

Generic method of http null sender.

The `http-null-sender` forwards `http-null-sender` defined in `(rfc http)` for `http1-connection` and does nothing for `http2-connection`.

## (rfc json-pointer) - JSON Pointer

Library (rfc json-pointer)

This library is re-exporting of `(text json pointer)`.

For more information, please see (text json pointer) - JSON Pointer

## (rfc jwe) - Json Web Encryption

Library (rfc jwe)

This library provides Json Web Encryption (JWE) APIs. JWE is defined in RFC 7516.

The library also supports ChaCha20-Poly1305 and XChaCha20-Poly1305 enhancement defined in the draft RFC

The following example shows how to exchange secret key.

    (import (rnrs)
            (rfc jwe)
            (rfc jwk))

    (define jwk-bob
      (json-string->jwk
       "{\"kty\":\"EC\",
         \"crv\":\"P-256\",
         \"x\":\"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ\",
         \"y\":\"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck\",
         \"d\":\"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw\"}"))

    (define jwe-header
      (jwe-header-builder
       (alg 'ECDH-ES+A128KW)
       (enc 'A128GCM)
       (apu "QWxpY2U")
       (apv "Qm9i")))

    ;; Alice wants to encrypt with Bob's public key
    (define alice-encryptor (make-ecdh-jwe-encryptor (jwk->public-key jwk-bob)))

    ;; Bob needs to decrypt Alice's message with his private key
    (define bob-decryptor (make-ecdh-jwe-decryptor jwk-bob))

    (define secret-key (string->utf8 "down the rabbit hole"))

    (let ((jwe-object (jwe:encrypt alice-encryptor jwe-header secret-key)))
      (jwe:serialize jwe-object) ;; -> compact JWE string
      (let ((secret-key (jwe:decrypt bob-decryptor jwe-object)))
        (utf8->string secret-key))) ;; -> "down the rabbit hole"

The above is just a taste of how to share a secret key without shared secret. In the real world application, you should implement your application more carefully.

### JWE Object

Record Type <jwe-object>

The record type of JWE objects. JWS object has 5 fields, `header`, `encrypted-key`, `iv`, `cipher-text` and `authentication-tag`.

Function jwe-object? obj

Returns #t if the given obj is a JWE object otherwise #f.

Function make-jws-object jwe-header encrypted-key iv cipher-text authentication-tag

Construct a newly allocated JWE object.

This constructor doesn't validate if the cipher-text can be decrypted by the encrypted-key as that's not possible.

NOTE: This constructor is not meant be used by users.

Function jwe-object-header jwe-object

Returns the value of `header` field of given jwe-object

Function jwe-object-encrypted-key jwe-object

Returns the value of `encrypted-key` field of given jwe-object

Function jwe-object-iv jwe-object

Returns the value of `iv` field of given jwe-object

Function jwe-object-cipher-text jwe-object

Returns the value of `cipher-text` field of given jwe-object

Function jwe-object-authentication-tag jwe-object

Returns the value of `authentication-tag` field of given jwe-object

### JWE Header

Record Type <jwe-header>

The record type of JWE header.

This record type has the below fields:

- `typ`: JWE type, must be a symbol

- `cty`: JWE content type

- `alg`: JWE algorithm, must be a symbol

- `enc`: JWE encryption algorithm, must be a symbol

- `jku`: JWK Set URL

- `jwk`: JWK, must be a JWK object

- `kid`: Key ID

- `x5u`: X.509 certificate URL

- `x5c`: X.509 certiticate chain, must be a list of X.509 certificate

- `x5t`: X.509 certificate SHA-1 Thumbprint, must be a bytevector

- `x5t-s256`: X.509 certificate SHA-256 Thumbprint, must be a bytevector

- `crit`: Critical header parameter, must be a list of string

- `zip`: Compression algorithm

- `p2s`: Salt, must be a bytevector

- `p2c`: Iteration count, must be an integer

- `iv`: Initial vector, must be a bytevector

- `tag`: Authentication tag, must be a bytevector

- `apu`: Agreement party uinfo, must be a bytevector

- `apv`: Agreement party vinfo, must be a bytevector

- `epk`: Ephemeral public key, must be either JSON or JWK object

- `custom-parameters`

The above fields have accessors prefixed jwe-header-. For example, to read `typ` field, you can use `jwe-header-typ` procedure.

Below are the supported encryption algorithms:

- `A128CBC-HS256`

- `A192CBC-HS384`

- `A256CBC-HS512`

- `A128GCM`

- `A192GCM`

- `A256GCM`

- `C20P` 0.9.13

- `XC20P` 0.9.13

Function jwe-header? obj

Returns #t if the given obj is a JWE header, otherwise #f.

Macro jwe-header-builder (field value) ...

A builder macro of JWE header. The macro is generated by `(record builder)`. see (record builder)for more details.

Function jwe-header->json jwe-header
Function write-jwe-header jwe-header
Function write-jwe-header jwe-header port
Function jwe-header->json-string jwe-header

Serialize the given json-header to a S-exp representaion, to port or string.

If first form of `write-jwe-header` is used, then it writes the serialized JWE header to current output port.

Function json->jwe-header obj
Function read-jwe-header
Function read-jwe-header :optional port
Function json-string->jwe-header string

Construct JWE header from S-exp JSON representation of obj, from input port port or a string string.

If the first form of `read-jwe-header` is used, then it reads from current input port.

### JWE Operations

Function jwe:parse string

Parse the given compact JWE of string and return JWE object.

If the format of the given string is invalid, then an error is signaled.

Function jwe:serialize jwe-object

Serialize the given jwe-object to compact JWE form.

Function jwe:encrypt jwe-encryptor jwe-header plain-text

Returns a JWE object whose `cipher-text` is the encrypted payload.

The jwe-encryptor must be one of the JWE encryptors described below section.

The jwe-header must be a JWE header object.

The plain-text must be a bytevector.

Function jwe:encrypt jwe-decryptor jwe-object
Function jwe:encrypt jwe-decryptor jwe-object critical-headers

Returns decrypted `cipher-text` as a bytevector.

The jwe-decryptor must be one of the JWE decryptors described below section.

The jwe-object must be a JWE object.

If the second form is used, then the `crit` paramteters of the `header` will be checked.

### JWE Encryptors

JWE encryptor is a procedure takes two arguments, JWE header and plain text.

Function make-ecdh-jwe-encryptor key
Function make-ecdh-es-jwe-encryptor key 0.9.13

key must be a EC JWK, OKP JWK, EcDSA public key, X25519 public key or X448 public key.

Creates a ECDH JWE encryptor.

Below are the supported algorithms:

- `ECDH-ES`

- `ECDH-ES+A128KW`

- `ECDH-ES+A198KW`

- `ECDH-ES+A256KW`

- `ECDH-ES+C20PKW` 0.9.13

- `ECDH-ES+XC20PKW` 0.9.13

Function make-rsa-jwe-encryptor key

key must be a RSA JWK or RSA public key.

Creates a RSA JWE encryptor.

Below are the supported algorithms:

- `RSA1_5`

- `RSA-OAEP`

- `RSA-OAEP-256`

Function make-aeskw-jwe-encryptor key

key must be a OCT JWK or AES secret key.

Creates a AESKW JWE encryptor.

Below are the supported algorithms:

- `A128KW`

- `A192KW`

- `A256KW`

- `A128GCMKW`

- `A192GCMKW`

- `A256GCMKW`

Function make-c20pkw-jwe-encryptor key 0.9.13

key must be a OCT JWK or a symmetric key of size 16 or 32 octet.

Creates a C20PKW or XC20PKW JWE encryptor.

Below are the supported algorithms:

- `C20PKW`

- `XC20PKW`

Function make-pbes2-jwe-encryptor password

password must be a string or a bytevector.

Creates a PBES2 JWE encryptor.

Below are the supported algorithms:

- `PBES2-HS256+A128KW`

- `PBES2-HS384+A192KW`

- `PBES2-HS512+A256KW`

Function make-direct-jwe-encryptor key

key must be an AES secret key.

Creates a direct JWE encryptor.

This encryptor uses given key as CEK.

### JWE Decryptors

JWE decryptor is a procedure takes 5 arguments, JWE header, encrypted key, IV, cipher text and authentication tag.

Function make-ecdh-jwe-decryptor key
Function make-ecdh-es-jwe-decryptor key 0.9.13

key must be a EC JWK, OKP JWK, EcDSA private key, X25519 private key or X448 private key.

Creates a ECDH JWE decryptor.

Below are the supported algorithms:

- `ECDH-ES`

- `ECDH-ES+A128KW`

- `ECDH-ES+A198KW`

- `ECDH-ES+A256KW`

- `ECDH-ES+C20PKW` 0.9.13

- `ECDH-ES+XC20PKW` 0.9.13

Function make-rsa-jwe-decryptor key

key must be a RSA JWK or RSA private key.

Creates a RSA JWE decryptor.

Below are the supported algorithms:

- `RSA1_5`

- `RSA-OAEP`

- `RSA-OAEP-256`

Function make-aeskw-jwe-decryptor key

key must be a OCT JWK or AES secret key.

Creates a AESKW JWE decryptor.

Below are the supported algorithms:

- `A128KW`

- `A192KW`

- `A256KW`

- `A128GCMKW`

- `A192GCMKW`

- `A256GCMKW`

Function make-c20pkw-jwe-decryptor key 0.9.13

key must be a OCT JWK or a secret key of size 16 or 32 octed.

Creates a C20PKW or XC20PKW JWE decryptor.

Below are the supported algorithms:

- `C20PKW`

- `XC20PKW`

Function make-pbes2-jwe-decryptor password

password must be a string or a bytevector.

Creates a PBES2 JWE decryptor.

Below are the supported algorithms:

- `PBES2-HS256+A128KW`

- `PBES2-HS384+A192KW`

- `PBES2-HS512+A256KW`

Function make-direct-jwe-decryptor key

key must be an AES secret key.

Creates a direct JWE decryptor.

This decryptor uses given key as CEK.

## (rfc jwk) - Json Web Key

Library (rfc jwk)

This library provides Json Web Key (JWK) APIs. JWS is defined in RFC 7517.

This library also supports OKP defined in RFC 8037.

This library also supports curve `secp256k1` RFC 8812, as well as the `P-256K` which is defined in the draft 00 of the RFC.

The following examples show how to interact with keys from `(sagittarius crypto keys)` library.

    ;; (sagittarius crypto keys) keys to JWK/JWKS
    (import (rnrs)
            (sagittarius crypto keys)
            (rfc jwk))

    (define keypair (generate-key-pair *key:ed25519*))

    (define private-key (key-pair-private keypair))

    (define jwk-config (jwk-config-builder (kid "my key id")))

    (let ((jwks (make-jwk-set (list (key->jwk private-key jwk-config)))))
      (jwk-set->json-string jwks) ;; -> {"keys":[{"kid":"my key id",...}]}
      (jwk-set:find-key jwks (jwk-matcher:kid "my key id")) ;; -> #<jwk>
      (jwk-set->public-jwk-set jwks)) ;; -> #<jwk-set> contains only public key

    ;; JWK/JWKS to (sagittarius crypto keys) key
    (import (rnrs)
            (sagittarius crypto keys)
            (rfc jwk))

    ;; JWKS with EC private key
    (define jwks-json
      #(("keys"
         #(("kty" . "EC")
           ("crv" . "P-256")
           ("x"   . "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4")
           ("y"   . "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM")
           ("d"   . "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE")
           ("use" . "enc")
           ("kid" . "1")))))
    (define jwks (json->jwk-set jwks-json))
    (define kid-matcher (jwk-matcher:kid "1"))

    (define jwk (jwk-set:find-key jwks kid-matcher))

    (jwk->public-key jwk)   ;; -> ECDSA public key
    (jwk->private-key jwk)  ;; -> ECDSA private key

### JWK Set

JWK Set (JWKS) is an object represents a set of JWKs.

Function jwk-set? obj

Returns #t if the given obj is a JWKS object otherwise #f.

Function make-jwk-set keys

Construct a newly allocated JWKS object whose keys are keys.

keys must be a list of JWK objects.

Function jwk-set-keys jwk-set

Retrieves a list of JWKs from the given jwk-set.

Function json->jwk-set obj
Function read-jwk-set
Function read-jwk-set port
Function json-string->jwk-set string

Construct JWKS from S-exp JSON representation of obj, from input port port or a string string.

If the first form of `read-jwk-set` is used, then it reads from current input port.

Function jwk-set->json jwk-set
Function write-jwk-set jwk-set
Function write-jwk-set jwk-set port
Function jwk-set->json-string jwk-set

Serialize the given jwk-set to a S-exp representaion, to port or string.

If first form of `write-jwk-set` is used, then it writes the serialized JWK set to current output port.

Function jwk-set:find-key jwk-set jwk-matcher

Finds a key which matches to jwk-matcher from given jwk-set.

### JWK Matcher

A JWK matcher is a procedure takes one argument, jwk, and returns the given jwk if it matches the condition otherwise returns #f.

The matchers provided by this library complies to the above so that users can compose matchers like this:

    (import (rnrs)
            (rfc jwk)
            (sagittarius combinators))

    (define kid/alg-matcher
     (compose (jwk-matcher:kid "kid") (jwk-matcher:alg 'EdDSA)))

Function jwk-matcher:kty obj
Function jwk-matcher:use obj
Function jwk-matcher:alg obj
Function jwk-matcher:kid obj
Function jwk-matcher:x5t obj
Function jwk-matcher:x5t-s256 obj
Function jwk-matcher:crv obj

Creates a JWK matcher which checks `kty`, `use`, `alg`, `kid`, `x5t`, `x5t-s256` or `crv` field of the target JWK is equal to obj, respectively.

Function jwk-matcher:key-ops obj

Creates a JWK matcher which checks `key-ops` field of the target JWK contains given obj.

Function jwk-matcher:rsa jwk
Function jwk-matcher:ec jwk
Function jwk-matcher:oct jwk
Function jwk-matcher:okp jwk

Convenient JWK matchers which check `kty` to be `RSA`, `EC`, `oct` or `OKP`, respectively.

### JWK

JWK is an object which contains key information. The object contains the following fields:

- `kty`: key type, symbol

- `use`: key usage, symbol, must be either `sig` or `enc`

- `key-ops`: key operation, a list of symbols

- `alg`: key algorithm, symbol

- `kid`: key ID

- `x5u`: URL of certificate

- `x5c`: Certificate chain, list of x509 certificate

- `x5t`: SHA-1 certificate finger print, bytevector

- `x5t-s256`: SHA-256 certificate finger print, bytevector

Function jwk? obj

Returns #t if the given obj is a JWK object otherwise #f.

Function jwk-kty jwk
Function jwk-use jwk
Function jwk-key-ops jwk
Function jwk-alg jwk
Function jwk-kid jwk
Function jwk-x5u jwk
Function jwk-x5c jwk
Function jwk-x5t jwk
Function jwk-x5t-s256 jwk

Retrieves the field value of jwk.

Function json->jwk obj
Function read-jwk
Function read-jwk :optional port
Function json-string->jwk string

Construct JWK from S-exp JSON representation of obj, from input port port or a string string.

If the first form of `read-jwk` is used, then it reads from current input port.

Function jwk->json jwk
Function write-jwk jwk
Function write-jwk jwk port
Function jwk->json-string jwk

Serialize the given jwk to a S-exp representaion, to port or string.

If first form of `write-jwk` is used, then it writes the serialized JWK to current output port.

#### From JWK Conversion

The below conversion procedures raise an error if the conversion is not possible. For example, key type `oct` can't be public key.

Function jwk->public-key jwk
Function jwk->private-key jwk

Convert given jwk to `(sagittarius crypto keys)` public key and private key, respectively.

Function jwk->octet-key jwk

Convert given jwk to octet key bytevector.

Function jwk->public-jwk jwk

Convert given jwk to JWK which only contains public key information.

#### To JWK Conversion

Function jwk:config? obj

Returns #t if the given obj is a JWK config object otherwise #f.

JWK may contain meta data, such as `kid`, to provide the information, users can use JWK config object. The object has the below fields:

- `use`: key usage, symbol, must be either `sig` or `enc`

- `kid`: key ID

- `key-ops`: key operation, a list of symbols

- `alg`: key algorithm, symbol

- `x5u`: URL of certificate

- `x5c`: Certificate chain, list of x509 certificate

- `e`: RSA public key exponent

`e` is provided due to the historical reason of not to have public exponent in non CRT RSA private key. By default, the value is 65537.

Macro jwk-config-builder

A builder macro of JWK config. The macro is generated by `(record builder)`. see (record builder)for more details.

Function jwk->jwk-config jwk

Construct JWK config from given jwk.

Function key->jwk key
Function key->jwk key jwk-config

Converts given key to JWK object.

If the second form is used, then the returning JWK contains the configured information.

The key must be one of public key, private key, or secret key of `(sagittarius crypto keys)`.

## (rfc jws) - Json Web Signature

Library (rfc jws)

This library provides Json Web Signature (JWS) APIs. JWS is defined in RFC 7515.

The library supports `ES256K` defined in RFC 8812section 3.1.

It also supports EdDSA of both Ed25519 and Ed448 defined in RFC 8037.

The following examples show how to sign and verify JWS token

    ;; Signing
    (import (rnrs)
            (rfc jws)
            (rfc jwk) ;; to convert key pair to JWK
            (sagittarius crypto keys))

    ;; Generate Ed25519 key pair
    (define keypair (generate-key-pair *key:ed25519*))

    ;; JWS header with crit
    (define jws-header
      (jws-header-builder
       (alg 'EdDSA)
       (crit '("sagittarius:iss" "sagittarius:sub"))
       (custom-parameters '(("sagittarius:iss" "Sagittarius Scheme")
                            ("sagittarius:sub" "JWS test")))))

    (define payload
      (string->utf8 "Payload can be anything as long as a bytevector"))

    ;; Get signer
    (define signer (private-key->jws-signer (key-pair-private keypair)))

    ;; The JWS object is not signed yet
    (define unsecure-jws-object (make-jws-object jws-header payload))

    (let ((jws-object (jws:sign unsecure-jws-object signer)))
      (jws:serialize jws-object)
      ;; -> eyJzYWdpdHRhcml1czpzdWIiOiJKV1MgdGVzdCIsInNhZ2l0dGFyaXVzOmlzcyI6IlNhZ2l0dGFyaXVzIFNjaGVtZSIsImFsZyI6IkVkRFNBIiwiY3JpdCI6WyJzYWdpdHRhcml1czppc3MiLCJzYWdpdHRhcml1czpzdWIiXX0.UGF5bG9hZCBjYW4gYmUgYW55dGhpbmcgYXMgbG9uZyBhcyBhIGJ5dGV2ZWN0b3I.5Aj_AJh4DW01kV80XtFbxRRMw2ktxIrQ5-UXoCwKVWI0Ke0q0t3vpcFnESL39zYDwi3Ps8eLxfmEb-TvhkQGBg
      (jwk->json-string (public-key->jwk (key-pair-public keypair)))
      ;; -> {"kty":"OKP","crv":"Ed25519","x":"o_t1R4fWf7obqTZWlXxrgPG09BMU-zuhqHvb9_ayOew"}
      )

    ;; Verify
    (import (rnrs)
            (rfc jws)
            (rfc jwk)) ;; to convert JWK to public key

    ;; JWS string
    (define jws-string
      "eyJzYWdpdHRhcml1czpzdWIiOiJKV1MgdGVzdCIsInNhZ2l0dGFyaXVzOmlzcyI6IlNhZ2l0dGFyaXVzIFNjaGVtZSIsImFsZyI6IkVkRFNBIiwiY3JpdCI6WyJzYWdpdHRhcml1czppc3MiLCJzYWdpdHRhcml1czpzdWIiXX0.UGF5bG9hZCBjYW4gYmUgYW55dGhpbmcgYXMgbG9uZyBhcyBhIGJ5dGV2ZWN0b3I.5Aj_AJh4DW01kV80XtFbxRRMw2ktxIrQ5-UXoCwKVWI0Ke0q0t3vpcFnESL39zYDwi3Ps8eLxfmEb-TvhkQGBg")

    ;; Ed25519 public key
    (define jwk
      (json-string->jwk
       "{\"kty\":\"OKP\",\"crv\":\"Ed25519\",\"x\":\"o_t1R4fWf7obqTZWlXxrgPG09BMU-zuhqHvb9_ayOew\"}"))

    ;; Parse the string
    (define jws-object (jws:parse jws-string))

    ;; Make a verifier from the JWK
    (define verifier (public-key->jws-verifier jwk))

    (when (jws:verify jws-object verifier '("sagittarius:iss" "sagittarius:sub"))
      (utf8->string (jws-object-payload jws-object))) ;; -> payload

The above examples only show the flavour of the APIs. In real world applications, the users of the library must consider a lot more to make the application secure.

### JWS Object

Record Type <jws-object>

The record type of JWS objects. JWS object has 2 fields, `header` and `payload`.

Function jws-object? obj

Returns #t if the given obj is a JWS object otherwise #f.

Function make-jws-object jws-header payload

Construct a newly allocated JWS object.

Jws-header must be a JWS header object.

payload must be a bytevector.

Function jws-object-header jws-object

Returns the value of `header` field of given jws-object.

Function jws-object-payload jws-object

Returns the value of `payload` field of given jws-object.

Record Type <jws-signed-object>

The record type of signed JWS objects.

Signed JWS object is a sub record of JWS object, which has `signature`field.

Function jws-signed-object? obj

Returns #t if the given obj is a signed JWS object otherwise #f.

This object can be obtained by `jws:sign` or `jws:parse`.

Function jws-signed-object-signature signed-jws-object

Returns the value of `signature` field of given signed-jws-object.

### JWS Header

Record Type <jws-header>

The record type of JWS header.

This record type has the below fields:

- `typ`: JWS type, must be a symbol

- `cty`: JWS content type

- `alg`: JWS algorithm, must be a symbol

- `jku`: JWK Set URL

- `jwk`: JWK, must be a JWK object

- `kid`: Key ID

- `x5u`: X.509 certificate URL

- `x5c`: X.509 certiticate chain, must be a list of X.509 certificate

- `x5t`: X.509 certificate SHA-1 Thumbprint, must be a bytevector

- `x5t-s256`: X.509 certificate SHA-256 Thumbprint, must be a bytevector

- `crit`: Critical header parameter, must be a list of string

- `custom-parameters`

The above fields have accessors prefixed jws-header-. For example, to read `typ` field, you can use `jws-header-typ` procedure.

Function jws-header? obj

Returns #t if the given obj is a JWS header, otherwise #f.

Macro jws-header-builder (field value) ...

A builder macro of JWS header. The macro is generated by `(record builder)`. see (record builder)for more details.

Function jws-header->json jws-header
Function write-jws-header jws-header
Function write-jws-header jws-header port
Function jws-header->json-string jws-header

Serialize the given json-header to a S-exp representaion, to port or string.

If first form of `write-jws-header` is used, then it writes the serialized JWS header to current output port.

Function json->jws-header obj
Function read-jws-header
Function read-jws-header :optional port
Function json-string->jws-header string

Construct JWS header from S-exp JSON representation of obj, from input port port or a string string.

If the first form of `read-jws-header` is used, then it reads from current input port.

### JWS Operations

Function jws:parse string

Parse the given compact JWS of string and return signed JWS object.

If the format of the given string is invalid, then an error is signaled.

Function jws:serialize jws-object
Function jws:serialize jws-object detach-payload?

Serialize the given jws-object to compact JWS form.

If the second form is used, then the payload is omitted. (Detached form)

Function jws:sign jws-object signer

Sign the given jws-object with the given signer and returns signed JWS object.

Function jws:verify jws-object verifier
Function jws:verify jws-object verifier critical-headers

Verify the given jws-object with the given verifier. If the verification is success, then it returns #t.

Otherwise, it may return #f or signals an error, depending on the underlying verifier.

If the second form of `jws:verify` is used, then it uses the given critical-headers list to check `crit` header value.

### JWS Verifiers

JWS verifier is a procedure takes 3 arguments, JWS header, signing content and signature.

This library doesn't support `none` algorithm verifier. It is obvious that if you want to support it, you just don't have to verify it.

Function make-mac-jws-verifier key

key must be a JWK:oct or a bytevector.

Creates a MAC JWS verifier.

Function make-rsa-jws-verifier key

key must be a JWK:RSA or a RSA public key.

Creates a RSA JWS verifier.

Function make-ecdsa-jws-verifier key

key must be a JWK:EC or a ECDSA public key.

Creates a ECDSA JWS verifier.

Function make-eddsa-jws-verifier key

key must be a JWK:OKP or a EdDSA public key.

Creates a EdDSA JWS verifier.

### JWS Signers

JWS signer is a procedure takes 2 arguments, JWS header, signing content.

This library doesn't support `none` algorithm signer. If you want to support it, you need to create a JWS object with `alg` header with value of `none`.

Function make-mac-jws-signer key

key must be a JWK:oct or a bytevector.

Creates a MAC JWS signer.

Function make-rsa-jws-signer key

key must be a JWK:RSA or a RSA private key.

Creates a RSA JWS signer.

Function make-ecdsa-jws-signer key

key must be a JWK:EC or a ECDSA private key.

Creates a ECDSA JWS signer.

Function make-eddsa-jws-signer key

key must be a JWK:OKP or a EdDSA private key.

Creates a EdDSA JWS signer.

## (rfc jwt) - Json Web Token

Library (rfc jwt)

This library provides Json Web Token (JWT) APIs. JWT is defined in RFC 7519.

The following example shows how to consume JWT

    (import (rnrs)
            (rfc jwt)
            (rfc jwk)
            (rfc jwe)
            (rfc jws)
            (rfc uuid)
            (srfi :19)
            (sagittarius crypto keys)
            (sagittarius combinators))

    (define keypair (generate-key-pair *key:ed25519*))
    (define alg 'EdDSA)
    ;; (define keypair (generate-key-pair *key:ecdsa* :ec-parameter *ec-parameter:p256*))
    ;; (define alg 'ES256)
    ;; (define keypair (generate-key-pair *key:rsa* :size 2048))
    ;; (define alg 'PS512)

    (define claims
      (jwt-claims-builder
       (iss "Sagittarius Scheme")
       (aud "All saints")
       (sub "Use Sagittarius")
       (iat (current-time))
       (nbf (add-duration (current-time) (make-time time-duration 0 -1)))
       (exp (add-duration (current-time) (make-time time-duration 0 600)))
       (jti (uuid->string (make-v4-uuid)))))

    (define jws-header
      (jws-header-builder
       (alg alg)))

    (define payload (string->utf8 (jwt-claims->json-string claims)))
    (define jws-object (make-jws-object jws-header payload))

    (define signer (private-key->jws-signer (key-pair-private keypair)))

    (define jwk
      (public-key->jwk (key-pair-public keypair)
                       (jwk-config-builder (kid "my key"))))
    (define jwks (make-jwk-set (list jwk)))

    (let ((jwt-object (jws:sign jws-object signer)))
      ;; Share the JWT to 3rd party
      ;; (jws:serialize jwt-object)
      ;; (jwk-set->json-string jwks)

      ;; Verify the JWT token with the public key
      (let* ((kid-matcher (jwk-matcher:kid "my key"))
             (verifier (public-key->jws-verifier
                        (jwk-set:find-key jwks kid-matcher)))
             (jwt-consumer (jwt-consumer-builder
                            (verifier verifier)
                            (claims-validator
                             ;; Validate claims
                             (compose jwt:iss-required-validator
                                      jwt:sub-required-validator
                                      jwt:aud-required-validator
                                      jwt:exp-required-validator
                                      jwt:nbf-required-validator
                                      jwt:iat-required-validator
                                      jwt:jti-required-validator
                                      (jwt:iss-value-validator "Sagittarius Scheme"
                                                               "Sagittarius")
                                      (jwt:sub-value-validator "Use Sagittarius")
                                      (jwt:aud-value-validator "All saints")
                                      (jwt:nbf-validator)
                                      (jwt:exp-validator)))))
             (claims (jwt:consume jwt-consumer jwt-object)))
        ;; use the user claim
        (jwt-claims-aud claims))) ;; retrieve 'aud' field

### JWT

By definition, JWT is either JWE or JWS. To create JWT, users need to use either `(rfc jwe)` or `(rfc jws)` library. For more details, please refer the respective section of the document.

Function jwt:consume jwt-consumer jwt-string/object

Returns JWT claims after decrypt and/or verify the given jwt-string/object.

jwt-consumer must be a JWT consumer object.

jwt-string/object must be either a string of valid JWT format or JWE/JWS object.

### JWT Consumer

JWT consumer is an object decrypts and/or verifies the JWT and validates the claims. JWT consumer contains the below fields:

- `decryptor`: JWE decryptor

- `verifier`: JWS verifier

- `claims-validator`: Claims validator, see below section for more details

Function jwt-consumer? obj

Returns #t if the given obj is a JWT consumer otherwise #f.

Macro jwt-consumer-builder

A builder macro of JWT consumer. The macro is generated by `(record builder)`. see (record builder)for more details.

JWT consumer execute validation if the `claims-validator` field is set. The field must hold claims validator, which is a procedure takes one argument, claims, and returns the given claims or raises an error if the validation failed.

Function jwt:iss-required-validator claims
Function jwt:sub-required-validator claims
Function jwt:aud-required-validator claims
Function jwt:exp-required-validator claims
Function jwt:nbf-required-validator claims
Function jwt:iat-required-validator claims
Function jwt:jti-required-validator claims

Claims validator to validate required field of the given claims.

Function jwt:iss-validator iss ...
Function jwt:aud-validator aud ...
Function jwt:sub-validator sub

Creates claims validator to validate `iss`, `aud` and `sub`, respectively.

The first 2 procedures may take multiple argument and checks if one of the value matches or not.

Function jwt:exp-validator
Function jwt:exp-validator clock-skew
Function jwt:exp-validator clock-skew future-bound-seconds

Creates claims validator to validate exp field is expired or nor.

clock-skew must be an integer represents seconds of clock skew.

future-bound-seconds must be an integer represents seconds of maximum boundary that `exp` can be. (e.g. `exp` can't be more than 10 mins of future)

Function jwt:nbf-validator
Function jwt:nbf-validator clock-skew

Creates claims validator to validate if the current time is earlier than nbf field.

clock-skew must be an integer represents seconds of clock skew.

Function jwt:iat-validator not-before not-after
Function jwt:iat-validator not-before not-after clock-skew

Creates claims validator to validate if the `iat` is in between not-before and not-after__not-before and not-after must be a time object.

clock-skew must be an integer represents seconds of clock skew.

### JWT Claims

JWT claims is an object which contains claims of the JWT.

Record Type <jwt-claims>

Record type of JWT claims object.

The object contains the following fields:

- `iss`: Issuer

- `sub`: Subject

- `aud`: Audience

- `exp`: Expiration time

- `nbf`: Not before

- `iat`: Issued at

- `jti`: JWT ID

- `custom-claims`: User defined claims, hashtable

Function jwt-claims? obj

Returns #t if the obj is JWT claims otherwise #f.

Macro jwt-claims-builder

A builder macro of JWT claims. The macro is generated by `(record builder)`. see (record builder)for more details.

Function jwt-claims-iss jwt-claims
Function jwt-claims-sub jwt-claims
Function jwt-claims-aud jwt-claims
Function jwt-claims-exp jwt-claims
Function jwt-claims-nbf jwt-claims
Function jwt-claims-iat jwt-claims
Function jwt-claims-jti jwt-claims
Function jwt-claims-custom-claims jwt-claims

Retrieves the field value of jwt-claims.

Function json->jwt-claims obj
Function read-jwt-claims
Function read-jwt-claims :optional port
Function json-string->jwt-claims string

Construct JWT claims from S-exp JSON representation of obj, from input port port or a string string.

If the first form of `read-jwt-claims` is used, then it reads from current input port.

Function jwt-claims->json jwt-claims
Function write-jwt-claims jwt-claims
Function write-jwt-claims jwt-claims port
Function jwt-claims->json-string jwt-claims

Serialize the given jwt-claims to a S-exp representaion, to port or string.

If first form of `write-jwt-claims` is used, then it writes the serialized JWT claims to current output port.

## (rfc pem) - PEM format library

Library (rfc pem)

This library provides PEM format file parser.

Currently only supports RFC 1421 format.

### Conditions

This library defines these conditions.

Condition Type &pem-error

Super condition of all PEM file process related conditions.

Condition Type &invalid-pem-format

This condition indicates, given PEM file contains invalid format.

Function invalid-pem-format? obj

Returns #t, if the given obj is `&invalid-pem-format`, otherwise #f.

Condition Type &pre-eb-as-boundary

This condition indicates, given PEM file contains Pre-Encapsulation Boundary as the end of Encapsulated Message without specifying `:multiple`.

Function pre-eb-as-boundary? obj

Returns #t, if the given obj is `&pre-eb-as-boundary`, otherwise #f.

### Operations

Function parse-pem in :key (multiple #f) (builder #f) (asn1 #f) decoder

in must be textual input port.

Parses given input port in and returns 2 values, parameter alist and decoded bytevector.

Keyword arguments

`multiple`

  When this keyword argument is #t, then the procedure returns a list which contains alist of parameter and content. This parameter is useful for the PEM files which contains multiple contents.

`builder`

  This keyword argument must take a procedure which accept one argument or #f. If builder is specified then the given procedure will be called to build then contents of the PEM. This argument is not correspond with asn1 keyword argument and has higher priority. So if both arguments are specified, then builder will be used.

`asn1`

  When this keyword argument is #t, then the procedure converts BASE64 bytevector to ASN.1 object defined in `(asn.1)` library.

`decorder`

  When this keyword argument is specified, it must be a procedure which accepts one argument, then the `parse-pem` uses the specified procedure to convert body of the PEM content. If it's not specified, the procedure uses BASE64 decoding.

The procedure may raise following conditions:

`&invalid-pem-format`

  When given in contains invalid PEM format.

`&pre-eb-as-boundary`

  When given in contains Pre-Encapsulation Boundary as the end of Encapsulated Message and `:multiple` is #f. For example:

      -----BEGIN FOO-----
      ... foo value ...
      -----BEGIN BAR-----
      ... bar value...
      -----END BAR-----

  parsing PEM like above must specify `:multiple` with true value. Otherwise, `&pre-eb-as-boundary` is signaled.

Function parse-pem-file file :rest options
Function parse-pem-string pem-string :rest options

Convenient procedures.

Parse given file and PEM string, respectively.

option will be passed to the `parse-pem`.

## (rfc hotp) - HMAC-based One-Time Password library

Library (rfc hotp)

Provides HMAC-based One-Time Password (HOTP) generating procedures. HOTP is defined in RFC 4226: RFC 4226.

Function generate-hmac-based-one-time-password K C digit
Function hotp K C digit

K must be a bytevector represents shared secret.

C must be an exact integer represents counter.

digit must be an exact integer.

Generates an HMAC-based one-time password.

`hotp` is an alias of `generate-hmac-based-one-time-password`.

## (rfc totp) - Time-based One-Time Password library

Library (rfc totp)

Provides Time-based One-Time Password (TOTP) generating procedures. TOTP is defined in RFC 6238: RFC 6238.

Function generate-time-based-one-time-password K digit :key time start-time step mode
Function totp K digit :key time start-time step mode

K must be a bytevector represents shared secret.

digit must be a positive exact integer.

The keyword argument time is given, then it must be a UTC time object of SRFI-19. The procedure computes returning one-time password according to the given time. The default value is `(current-time)`.

NOTE: time keyword should not be specified unless its testing purpose.

The keyword arguments described below are system parameters, means these parameters must be agreed between authenticator.

The keyword argument start-time is given, then it must be a UTC time object of SRFI-19. The procedure computes returning one-time password according to the given time. The defaule value is `(make-time time-utc 0 0)`.

The keyword argument step is given, then it must be a positive exact integer. The procedure computes returning one-time password according to the given time. The defaule value is `30`.

The keyword argument step is given, then it must be a positive exact integer. The procedure computes returning one-time password according to the given time. The defaule value is `30`.

The keyword argument mode is given, then it must be a hash algorithm name either builtin or custom. The procedure computes returning one-time password according to the given time. The defaule value is `SHA-1`.

Generates an Time-based one-time password.

`totp` is an alias of `generate-time-based-one-time-password`.

## (rfc quoted-printable) - Base 64 encode and decode library

Library (rfc quoted-printable)

This library provides quoted printable encoding and decoding procedures.

### Encoding procedures

Function quoted-printable-encode bv :key (line-width 76) (binary? #f)

bv must be a bytevector.

Encodes given bytevector to quoted printable encoded bytevector.

The keyword argument line-width specifies where the encode procedure should put linefeed. If this is less than 1 or #f, encoder does not put linefeed.

If the keyword argument binary? is not #f, then the procedure encodes #x0a and #x0b to `=0A` and `=0D` respectively.

Function quoted-printable-encode-string string :key (line-width 76) transcoder (binary? #f)

Convenient procedure for string.

Encodes given string to quoted printable encoded string.

The keyword argument transcoder is used to convert given string to bytevector. The converted bytevector will be passed to the `quoted-printable-encode` procedure. The default is utf-8 codec with NONE eol style.

### Decoding procedures

Function quoted-printable-decode bv

bv must be a bytevector.

Decode quoted printable encoded bytevector to original bytevector.

Function quoted-printable-decode-string string :key (transcoder (native-transcoder))

Convenient procedure.

Decode quoted printable encoded string to original string. The procedure is using `quoted-printable-decode`.

The keyword argument specifies how to convert the decoded bytevector to string. If this is #f, the procedure returns raw bytevector.

## (rfc sftp) - SFTP library

Library rfc sftp

This library provides SFTP programmatic operations.

Following example code describes how to use in high level.

    (import (rfc sftp) (pp) (srfi :26))

    (call-with-sftp-connection
      "localhost"    ;; hostname
      "23"           ;; port number
      (lambda (conn)
        ;; read directory
        (pp (sftp-readdir conn "."))
        ;; only short names
        (pp (sftp-readdir-as-filenames conn "."))
        ;; only long names (usually POSIX 'ls -l' format)
        (pp (sftp-readdir-as-longnames conn "."))

        ;; retrieve a file as a bytevector
        (print (utf8->string (sftp-read! conn "reading/file"
                                        (sftp-binary-receiver))))
        ;; store a file to local file directly
        (sftp-read conn "/a/file/path"
    	(sftp-file-receiver "where/to/store" :options (file-options no-fail)))

        ;; upload a file
        (let ((handle (sftp-open conn "boo"
                        (bitwise-ior +ssh-fxf-creat+ +ssh-fxf-write+))))
         (call-with-input-file "a/local/file" (cut sftp-write! conn handle <>)
                               :transcoder #f))

        ;; rename a file
        (sftp-rename! conn "boo" "foo")
        ;; remove a file
        (sftp-remove! conn "foo")
        ;; create a directory
        (sftp-mkdir! conn "boo")
        ;; remove a directory
        (sftp-rmdir! conn "boo")

        ;; create a symbolic link
        (pp (sftp-symlink! conn "/tmp" "tmp"))
        ;; get a actual path of symbolic link
        (pp (sftp-readlink conn "tmp"))
        ;; get a real path. (usually an absolute path)
        (pp (sftp-realpath conn "../")))
      :username "username" :password "password")

### High level APIs

Function call-with-sftp-connection server port proc . opts

server and port must be string, indicating hostname, port number/service name respectively. proc must accept one argument.

Creates a SFTP connection, executes given proc with the connection and closes it after the execution.

The opts will be passed to `make-client-sftp-connection`.

Function sftp-open conn filename pflags

conn must be a SFTP connection. filename must be a string. pflags must be an exact integer which value must be the result of inclusive or of following values;

Constant +ssh-fxf-read+

Open the given filename read mode.

Constant +ssh-fxf-write+

Open the given filename write mode.

Constant +ssh-fxf-append+

Open the given filename append mode.

Constant +ssh-fxf-creat+

Creates the given filename if it doesn't exist.

Constant +ssh-fxf-trunc+

Truncate the given filename if it exists. `+ssh-fxf-creat+` must be specified as well.

Constant +ssh-fxf-excl+

Raises and error filename if it exists. `+ssh-fxf-creat+` must be specified as well.

If filename opened successfully, the procedure will return a handle.

Function sftp-close conn handle

conn must be a SFTP connection.

Closes given handle created by `sftp-open`.

Function sftp-read conn handle/filename receiver :key (offset 0) buffer-size

conn must be a SFTP connection. handle/filename must be either a handle or string. receiver must be a procedure accepts 2 arguments, offset which is an integer and data which is a binary input port, respectively.

Reads the given handle/filename content from the server and call receiver with the returned value. When it reaches the end of file, then it will pass -1 as offset and eof value as data.

The keyword argument offset specifies starting where to read. It is useful to read only diff.

The keyword argument buffer-size specifies how many bytes it tries to read in one read call. The default value is 1048576 (1MB). This value is only an indication so that server can decide actual data length to send.

The return value of this procedure is the result value of receiver.

Receiver must return 2 values, one if processed octet count and the other one is result value. Following is the sftp-binary-receiver definition;

    (define (sftp-binary-receiver)
      (let-values (((out extract) (open-bytevector-output-port)))
        (lambda (offset data)
          (if (< offset 0)
              (values -1 (extract))
              (values (copy-binary-port out data) #f)))))

Function sftp-binary-receiver

Creates a in memory receiver for `sftp-read`.

Function sftp-file-receiver filename :key options

Creates a file receiver for `sftp-read`.

The keyword argument option must be created by `file-options`. By default no option.

Function sftp-oport-receiver output-port

output-port must be a binary output port.

Creates a output port receiver for `sftp-read`.

Function sftp-write! conn handle input-port :key (offset 0) buffer-size

conn must be a SFTP connection. handle must be a handle. input-port must be a binary input port.

Reads the content from given input-port and writes it to given handle.

The keyword argument offset specifies where to write. This is useful to write a file separately or simply append.

The keyword argument buffer-size specifies how many bytes of data the procedure sends in one packet. The default value is 131072 (128KB). The RFC defines the minimum value 32768 (3KB) so it is safe to use the value. However too small buffer size makes writing extremely slow so we use a bit larger value to make performance better. If you meet a problem with writing a file, consider to change this size.

Function sftp-exists? conn filename

conn must be a SFTP connection. filename must be a string indicating existing filename.

Checks if the given filename exists.

Function sftp-remove! conn filename

conn must be a SFTP connection. filename must be a string indicating existing filename.

Removes the given filename. It is an error if the file doesn't exist or user doesn't have proper permission to remove.

The result value is raw SFTP status object.

Function sftp-rename! conn oldpath newpath

conn must be a SFTP connection. oldpath and newpath must be strings indicating existing path.

Renames the given oldpath to newpath. It is an error if the file doesn't exist or user doesn't have proper permission to rename.

The result value is raw SFTP status object.

Function sftp-mkdir! conn path

conn must be a SFTP connection. path must be a string.

Creates the given path directory. It is an error if the directory exists or user doesn't have proper permission to create.

The result value is raw SFTP status object.

Function sftp-rmdir! conn path

conn must be a SFTP connection. path must be a string.

Removes the given path directory. It is an error if the directory doesn't exists, user doesn't have proper permission to create or the directory isn't empty.

The result value is raw SFTP status object.

Function sftp-opendir conn path

conn must be a SFTP connection. path must be a string indicating existing path.

Opens the given path directory and returns its handle.

Function sftp-readdir conn handle/path

conn must be a SFTP connection. handle/path must be either a handle opened by `sftp-opendir` or a string indicating existing path.

Reads the given handle/path and returns the list of contents. The content is an object of `<sftp-name>` which has `filename`, `longname`and `attribute` slots.

Function sftp-readdir-as-filenames conn handle/path
Function sftp-readdir-as-longnames conn handle/path

conn must be a SFTP connection. handle/path must be either a handle opened by `sftp-opendir` or a string indicating existing path.

Calls `sftp-readdir` and strips out the result object to string by calling `(slot-ref _c_ 'filename)` or `(slot-ref _c_ 'longname)` respectively.

### Mid level APIs

Mid level APIs are changed since 0.7.8. The changes are not backward compatible, so if you are using 0.7.7 API and move to 0.7.8, please be aware.

Function make-client-sftp-connection server port

Creates a SFTP connection object.

Function open-client-sftp-connection! sftp-connection :key (authenticate #f

## (rfc smtp) - SMTP client

Library (rfc smtp)

This library provides simple SMTP client defined in RFC 5321.

The library provides high level APIs to use SMTP.

Following is the simple example to send an email.

    (import (rnrs) (rfc client))

    ;; creates SMTP mail object
    (define mail
      (smtp:mail
       (smtp:from "Takashi Kato" "ktakashi@ymail.com")
       (smtp:subject "Subject")
       "Message"
       (smtp:cc "ktakashi@ymail.com")))

    ;; creates an SMTP connection
    (define smtp-conn (make-smtp-connection "your.smtp.server.com" "587"))

    ;; connect to the server
    (smtp-connect! smtp-conn) ;; returns SMTP connection

    ;; Authenticate if required.
    (when (smtp-authentication-required? smtp-conn)
      ;; NOTE: only AUTH PLAIN is supported for now
      (cond ((memq 'PLAIN (smtp-connection-authentication-methods smtp-conn))
             (smtp-authenticate! smtp-conn (smtp-plain-authentication
                                            "username"
                                            "password")))
            (else (smtp-disconnect! smtp-conn)
                  (error #f "authentication method not supported"
                         (smtp-connection-authentication-methods smtp-conn)))))

    ;; Send it
    (smtp-send! smtp-conn mail) ;; returns SMTP connection

    ;; Clean up
    (smtp-disconnect! smtp-conn)

The followings describe how to create SMTP mail object with attachment(s) or inlined image.

    ;; Messae with attachment
    (smtp:mail
     (smtp:from "Takashi Kato" "ktakashi@ymail.com")
     (smtp:subject "Message with attachment")
     "Message"
     (smtp:to "ktakashi@ymail.com")
     (smtp:attachment "application" "octet-stream"
                      (get-file-content) ;; file content suitable for this
                      "file.odt"))

    ;; HTML message with inlined image.
    (smtp:mail
     (smtp:from "Takashi Kato" "ktakashi@ymail.com")
     (smtp:subject "HTML message with inlined image")
     "<html><body><img src='cid:image' /></body></html>"
     (smtp:to "ktakashi@ymail.com")
     (smtp:attachment "image" "jpeg"
                      ;; port can also be used
                      ;; NB: if you call smtp-mail->string twice in this case
                      ;;     then this may break. So make sure you use this
                      ;;     mail object once (includeing smtp-send!)
                      (open-file-input-port "image/file.jpg")
                      "image.jpg"
                      ;; specifies content-disposition parameter
                      "inline"
                      ;; adding content-id of this attachment
                      '("content-id" "<image>"))
     ;; make this mail HTML
     (smtp:header "Content-Type" "text/html"))

Alternative message can be created like this:

    ;; Message with alternative
    ;; Content must not be specified otherwise raise an syntax error
    (smtp:mail
     (smtp:from "Takashi Kato" "ktakashi@ymail.com")
     (smtp:subject "Message with alternative")
     (smtp:to "ktakashi@ymail.com")
     (smtp:alternative
      ("text" "plain" "Plain text message")
      ("text" "html" "<html><body>HTML message</body><html>"))
     )

### High level APIs

Function smtp-connection? obj

Returns #t if the given obj is an SMTP connection object, Otherwise #f.

Function make-smtp-connection server port :optiona domain

Creates an SMTP connection object.

If optional argument domain is specified, then the value is used for `EHLO` or `HELO` command parameter. Otherwise the result of `machine-name` (defined in SRFI 112) is used.

Function smtp-connection-authentication-methods smtp-connection

Returns a symbol list of possible authentication methods.

This procedure returns a proper value only after `smtp-connect!` is called.

Function smtp-authentication-required? smtp-connection

Returns #t if the given SMTP connection requires authentication, otherwise #f.

This procedure returns a proper value only after `smtp-connect!` is called.

Function smtp-connect! smtp-connection

Establishes connection and return SMTP connection object.

Function smtp-authenticate! smtp-connection initial-response-generator :optional next-step

initial-response-generator must be a procedure accepts 0 argument and must return 2 values, authentication method and initial response value (credential).

Authenticates the given smtp-connection. If the response status is `354` and next-step is specified, then the _next-step_is called with smtp-connection, status and response string. The procedure must return 2 values, next command and next-next procedure or #f. The `smtp-authenticate!` procedure stops when next-next procedure is #f or returning response is `235`.

The following is a simple LOGIN next-step.

    (define (smtp-login-authentication)
      (define (prompt next?)
        (lambda (conn status resp)
          (or (and (= status 334)
                   ;; response is encoded to BASE 64 so decode it
                   (display (base64-decode-string resp))
                   (flush-output-port (current-output-port))
                   ;; next command (either username or password)
                   ;; must be encoded to BASE 64
                   (values (base64-encode-string (get-line (current-input-port)))
                           (and next? (prompt #f))))
              (values #f #f))))
      (values (lambda () (values "LOGIN" #f)) (prompt #t)))

Function smtp-send! smtp-connection smtp-mail

Sends the given smtp-mail and returns SMTP connection object.

The procedure internally calls `smtp-mail->string`. So if the smtp-mail object contains an attachment with input port, then the port position will be forwarded. Thus second call of the `smtp-mail->string` or `smtp-send!` doesn't create/send attachment message properly.

Function smtp-connect! smtp-connection

Disconnect the smtp-connection and returns SMTP connection.

The closed SMTP connection can be re-used.

Function smtp-plain-authentication username password

Returns a thunk that can be used `smtp-authenticate!` procedure for PLAIN authentication.

Function smtp-login-authentication :rest data

Returns a thunk that can be used `smtp-authenticate!` procedure for LOGIN authentication.

The rest argument date is given, all of the values must be string, then each authentication prompt uses the given data as if it's typed by user. If there is no data or sufficient date, then input prompt will be shown and let user type the authentication information.

Macro smtp:mail from message-elements ...
Auxiliary Syntax smtp:from
Auxiliary Syntax smtp:subject
Auxiliary Syntax smtp:to
Auxiliary Syntax smtp:cc
Auxiliary Syntax smtp:bcc
Auxiliary Syntax smtp:attachment
Auxiliary Syntax smtp:header

Constructs an SMTP mail object.

from must be one of the following forms:

    (smtp:from email)

    (smtp:from name email)

message-elements must be one of the following forms:

    (smtp:subject subject)

    (smtp:to email)

    (smtp:to name email)

    (smtp:cc email)

    (smtp:cc name email)

    (smtp:bcc email)

    (smtp:bcc name email)

    (smtp:attachment type subtype content)

    (smtp:attachment type subtype content filename)

    (smtp:attachment type subtype content filename disposition-parameter)

    (smtp:attachment type subtype content filename disposition-parameter headers ...)

    (smtp:alternative type subtype content)

    (smtp:alternative type subtype content headers ...)

    (smtp:header name value)

    string

The order of the appearance does not matter, except string which will be the content of the creating SMTP mail. Except the `smtp:subject` and `smtp:alternative`, all elements can be appear multiple times.

Function smtp-mail->string smtp-mail

Returns MIME string of given smtp-mail.

NOTE: the procedure consumes input port attachments if exists.

### Middle level APIs

Function make-smtp-mail from subject content :rest recipients

Creates an SMTP mail object.

Function smtp-mail? obj

Returns #t if the given obj is an SMTP mail object, otherwise #f.

Function make-smtp-from email
Function make-smtp-from name email

creates an SMTP from object.

Function smtp-from? obj

Returns #t if the given obj is an SMTP from object, otherwise #f.

Function smtp-recipient? obj

Returns #t if the given obj is an SMTP recipient object, otherwise #f.

SMTP recipient objects are one of the following objects:

- SMTP to object

- SMTP cc object

- SMTP bcc object

Function make-smtp-to email
Function make-smtp-to name email
Function make-smtp-cc email
Function make-smtp-cc name email
Function make-smtp-bcc email
Function make-smtp-bcc name email

Creates SMTP to, SMTP cc and SMTP bcc objects respectively.

Function smtp-to? obj
Function smtp-cc? obj
Function smtp-bcc? obj

Returns #t if given obj is SMTP to, SMTP cc or SMTP bcc, respectively. Otherwise #f.

Function make-smtp-attachment type subtype content :optional filename disposition-parameter headers ...

Creates a MIME object which represents SMTP attachment.

Together type and subtype represent MIME type. e.g. `text/plain` content can be string, bytevector, input-port.

Optional argument filename is specified, then `content-disposition`header will have `filename` parameter.

Optional argument disposition-parameter is specified, then `content-disposition` header will have specified parameter. Default values is `attachment`.

Rest argument headers is specified, then the created attachment has extra mime header. Each header must be a list which contains 2 elements, header name and value. The value part can also contain MIME parameters.

Function make-smtp-alternative-component type subtype content headers ...

Creates a component of alternative message. The returning component is a mere MIME object.

type and subtype are the same as `make-smtp-attachment`.

Function make-smtp-alternative alternatives ...

Creates an alternative message. The returning message is a mere MIME object.

NOTE: the returning message should be added by `smtp-mail-add-attachment!`and not content argument of `make-smtp-mail`. To make mail construction easier, use `smtp:mail` macro.

Function smtp-mail-add-recipent! smtp-mail recipient

Adds SMTP recipient recipient to smtp-mail and returns SMTP mail object.

Function smtp-mail-add-attachment! smtp-mail attachment

Adds SMTP attachment attachment to smtp-mail and returns SMTP mail object.

Function smtp-mail-add-header! smtp-mail name value

Adds header to smtp-mail and returns SMTP mail object.

If there is the same header insense of `string-ci=?`, then the old one is overwritten.

## (rfc tls) - TLS protocol library

Library (rfc tls)

This library provides TLS protocol socket APIs.

### Implementation notes:

The library is implemented different libraries per platform. Some platform may not support a particular TLS version(s).

On Windows

  The library is implemented atop SChannel (SSP). The supporting TLS versions varies depending on the version of Windows. For the detailed information please refer Microsoft's support page. e.g. Protocols in TLS/SSL (Schannel SSP)

  On POSIX / Linux

  The library is implemented atop OpenSSL. This library doesn't specify the version of OpenSSL, it detects during the build process. The library specifies to use the latest TLS version, however, it doesn't guarantee using the latest due to the variety of reasons, e.g. older version of OpenSSL.

If you require to use a specific version of TLS, however this library only can do its best effort.

Function make-client-tls-socket node service :key handshake certificates private-key certificate-verifier :allow-other-keys

node and service must be string.

Creates a client TLS socket. node, service and opt will be passed to `make-client-socket` described in (sagittarius socket).

The keyword argument prng specifies which pseudo random algorithm will be used for generating security parameters.

If the keyword argument handshake #f then the procedure won't do TLS handshake after the socket creation so users must do it manually with `tls-client-handshake` procedure described below.

The keyword argument certificates is for certificate request message. The value must be a list of x509 certificates. If the certificates argument is null, then the procedures send empty certificate list to the server as a response of certificate request message.

The keyword argument private-key specifies which private key is used. The value must be private key object described in "(sagittarius crypto keys)". This is needed if the target server only supports RSA key exchange protocol.

The keyword argument certificate-verifier must be either boolean or a procedure which accepts 3 arguments, certificate depth, previous error and certificate as a bytevector. The procedure should check the passed certificate is valid or not.

Function tls-client-handshake tls-socket

Do client side handshake and return a TLS socket. The procedure must NOT be called if the socket is created with handshake keyword argument #t.

CAUTION: This procedure needs to be called only once and calling more than once might cause infinite loop or raise an error.

Function make-server-tls-socket service certificates :key private-key authorities client-certificate-required? certificate-verifier :allow-other-keys

service must be string. certificates must be a list of x509 certificate.

Creates a server TLS socket. service and opt will be passed to `make-server-socket` described in (sagittarius socket).

The keyword arguments prng and version are the same meaning as `make-client-tls-socket`.

The keyword argument private-key is used the same as client socket. The difference is that it is used also for Deffie-Hellman key exchange. If this is not specified, then key exhange is done anonymously.
The private-key should be specified. This is optional due to the backward compatibility.

The keyword argument authorities must be a list of x509 certificate and if this is not empty list then the server socket will send certificate request message to the client.

CAUTION: the authorities keyword argument currently doesn't check the certificate signature but only issuer DN.

Function tls-socket-send tls-socket bytevector flags

tls-socket must be the socket created by the procedure `make-client-tls-socket`.

flags must be non negative exact integer.

Sends given bytevector to tls-socket. flags are described in the section (sagittarius socket). The packet will be encrypted by tls-socket.

Function tls-socket-recv tls-socket size flags

tls-socket must be the socket created by the procedure `make-client-tls-socket`.

size and flags must be non negative exact integer.

Receives decrypted packet from tls-socket. size indicates how many octets the procedure should receive, however it might return less octet. flags will be passed to `socket-recv`.

NOTE: tls-socket have its own buffer to return the value, so that the procedure can take size argument.

Function tls-socket-close tls-socket

tls-socket must be the socket created by the procedure `make-client-tls-socket`.

Sends close notify alert to the socket and close it.

Function tls-socket-closed? tls-socket

tls-socket must be the socket created by the procedure `make-client-tls-socket`.

Returns #t if the given socket is closed, otherwise #f.

NOTE: this procedure checks if session is closed. So the real socket might not be closed yet.

Function tls-socket-accept tls-socket :key (handshake `#t` ) ( raise-error `#t` )

tls-socket must be a server TLS socket created by `make-server-tls-socket`.

Wait for an incoming connection request and returns a fresh connected client socket.

If the keyword argument handshake is #f then the handshake must be done by manually with `tls-server-handshake` described blow.

The keyword argument raise-error will be passed to `tls-server-handshake`.

Function tls-server-handshake tls-socket :key ( raise-error `#t` )

Do server side TLS handshake and returns a TLS socket. The procedure must NOT be called if the socket is created with handshake keyword argument #t.

If the keyword argument raise-error is #f then it won't raise an error when something happens.

Function tls-socket-peer tls-socket

Return peer of given tls-socket or #f.

For more details, see (sagittarius socket).

Function tls-socket-peer tls-socket

Return peer of given tls-socket or #f. This procedure is TLS version of `socket-peer`.

For more details, see (sagittarius socket).

Function tls-socket-name tls-socket

Return peer of given tls-socket or #f. This procedure is TLS version of `socket-name`.

For more details, see (sagittarius socket).

Function tls-socket-info-values tls-socket

Return peer of given tls-socket or #f. This procedure is TLS version of `socket-info-values`.

For more details, see (sagittarius socket).

Constant *tls-version-1.2*

Constant value of `#x0303` for TLS 1.2

Constant *tls-version-1.1*

Constant value of `#x0302` for TLS 1.1

Constant *tls-version-1.0*

Constant value of `#x0301` for TLS 1.0

Function tls-socket-port tls-socket :optional ( close? `#t` )

tls-socket must be the socket created by the procedure `make-client-tls-socket`.

Returns input/output-port of given tls-socket.

If optional argument close? is #f then it won't close the socket when the port is closed or GCed.

Function tls-socket-input-port tls-socket
Function tls-socket-output-port tls-socket

Convert the given TLS socket to input and output port, respectively.

The given socket won't be closed when the port is closed or GCed. So it is the users responsibility to close.

### Integration methods

The methods listed below are convenience methods to use TLS socket and usual socket without changing code.

Method socket-close ( socket `<tls-socket>` )
Method socket-send ( socket `<tls-socket>` ) data :optional ( flags `0` )
Method socket-recv ( socket `<tls-socket>` ) size :optional ( flags `0` )
Method socket-accept ( socket `<tls-socket>` ) . opt
Method socket-accept ( socket `<tls-socket>` ) ( key `<keyword>` ) . dummy
Method call-with-socket ( socket `<tls-socket>` ) proc
Method socket-peer ( socket `<tls-socket>` )
Method socket-name ( socket `<tls-socket>` )
Method socket-info-values ( socket `<tls-socket>` )
Method socket-port ( socket `<tls-socket>` ) :optional ( close? `#t` )
Method socket-input-port ( socket `<tls-socket>` )
Method socket-output-port ( socket `<tls-socket>` )

## (rfc uri) - Parse and construct URIs

Library (rfc uri)

This library provides RFC3986 'URI Generic Syntax' procedures.

Function uri-parse uri

uri must be string.

Parses given uri and returns following 7 values;

- scheme

- user-info

- host

- port

- path

- query

- fragment

Following examples are from RFC3986 text;

       foo://example.com:8042/over/there?name=ferret#nose
       \_/   \______________/\_________/ \_________/ \__/
        |           |            |            |        |
     scheme     authority       path        query   fragment
        |   _____________________|__
       / \ /                        \
       urn:example:animal:ferret:nose

authority = [ user-info "@" ] host [ ":" port ]

If given uri does not contain the part described above, it will be #f. ex)

    (uri-parse "http://localhost")

(values http #f localhost #f #f #f #f)
Function uri-scheme&specific uri

uri must be string.

Parse given uri into scheme and rest. Returns the 2 values.

Function uri-decompose-hierarchical specific

specific must be string.

specific is a URI without scheme. For example, the specific of following URI 'http://localhost/foo.html' if '//localhost/foo.html'.

Parse given specific into 4 values authority, path, query and fragment.

If the specific does not contain the part, it will be #f.

Function uri-decompose-authority authority

authority must be string.

Parse given authority into 3 values, user-info, host and post.

If the authority does not contain the part, it will be #f.

Function uri-decode in out :key (cgi-decode #f)

in must be binary input port.

out must binary output port.

Reads and decodes given in and put the result into out.

If the keyword argument cgi-decode is #t, the procedure decodes `#x2b`('+') to `#x20`('#\space').

Function uri-decode-string string :key (encoding 'utf-8) (cgi-decode #f)

Decodes given string and returns decoded string.

Function uri-encode in out :key (noescape rfc3986-unreserved-char-set) (upper-case #t)

in must be binary input port.

out must binary output port.

Reads and encodes given in and put the result into out.

The keyword argument noescape specifies which character must be escaped.

The keyword argument upper-case specifies the result case of encoded value. If the value is true value then it encodes to upper case (default), otherwise lower case.

Function uri-encode-string string :key (encoding 'utf-8) :allow-other-keys

Encodes given string and returns encoded string.

Function uri-compose :key (scheme #f) (userinfo #f) (host #f) (port #f) (authority #f) _

_ (path #f) (path* #f) (query #f) (fragment #f) (specific #f)

Composes URI from given arguments.

If all keyword arguments are #f, the procedure returns empty string.

The procedure put priority on bigger chunk of URI part. For example, if keyword argument specific is specified, the procedure uses only scheme and specific. Following describes the priority hierarchy;

    _scheme__specific_  +- _authority_       +- _userinfo_       +- _host_       +- _port_  +- _path\*_       +- _path_       +- _query_       +- _fragment_

Function uri-merge base-uri relative-uri1 relative-uri2 ...

Merges given relative-uris to base-uri according to RFC 3986 section 5.

Variable *rfc3986-unreserved-char-set*
Variable *rfc2396-unreserved-char-set*

Charsets which contains no escape needed characters.

There is slight difference between RFC2396 and RFC3986. This library uses RFC3986 charset by default to encode.

## (rfc uri-template) - URI template

Library (rfc uri-template)

This library provides RFC6570 'URI Template' procedures.

Function parse-uri-template in

Parses the given URI template into S-expression.

The given in must be either a textual input port or a string.

The parsed form consists with the following rules:

- uri-template ::= `(template-unit)`

- template-unit ::= `string`

- template-unit ::= `(template)`

- template ::= `(operator varaible)`

- operator ::= `character`

- variable ::= `string`

- variable ::= `(string modifier)`

- modifier ::= `*`

- modifier ::= `positive exact integer`

operator must be a valid URI template operator

    (parse-uri-template "http://{domain*}/{/path}")

(http:// ((domain \*)) / (/ path))
Function expand-uri-template uri-template parameter

Expands the given uri-template and returns a string.

The parameter must be a vector of pair of string and value.

The value must be one of the followings:

- string

- list of string

- vector of pair of string

    (expand-uri-template '((#\? ("keys" *))) '#(("keys" . #(("semi" . ";") ("dot" . ".") ("comma" . ",")))))

?semi=%3B&dot=.&comma=%2C

## (rfc uuid) - UUID generate library

Library (rfc uuid)

This library provides RFC 9562 a Universally Unique IDentifier (UUID) URN Namespace procedures.

Class <uuid>

The class representing UUID.

### Predicates

Function uuid? obj

Returns #t if the obj is an instance of `<uuid>`, otherwise #f.

Function v1-uuid? obj
Function v3-uuid? obj
Function v4-uuid? obj
Function v5-uuid? obj
Function v6-uuid? obj 0.9.12
Function v7-uuid? obj 0.9.12

Returns `#t` if the obj is an instance `<uuid>` and the named version, otherwise `#f`.

Function uuid=? uuid1 uuid2

Compares given 2 uuids and return #t if both have the same values, otherwise #f.

### Constructors

Function make-null-uuid
Function make-nil-uuid 0.9.12

Creates a null (empty) uuid.

The returning object will be represented like this UUID;

`00000000-0000-0000-0000-000000000000`.

Function make-max-uuid 0.9.12

Creates a max uuid.

The returning object will be represented like this UUID;

`FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF`.

Function make-v1-uuid :optional timestamp
Function make-v3-uuid namespace name
Function make-v4-uuid :optional prng
Function make-v5-uuid namespace name
Function make-v6-uuid :optional timestamp 0.9.12
Function make-v7-uuid :optional timestamp prng 0.9.12

Creates version 1, 3, 4, 5, 6 and 7 UUIDs respectively.

For version 1 and 6, the procedures can take an optional argument timestamp which is a 60bit timestamp integer.

For version 3 and 5, the procedures need to take 2 arguments, _namespace_and name. namespace must be a UUID object, and name must be a string.

For version 4, it can take an optional argument prng which specifies pseudo random generator. The default value is `(*uuid-random-state*)`.

For version 7, it can take optional arguments timestamp and prng. The timestamp is 48bit unix time in milliseconds, The default value is current time. The prng is the same as version 4.

### Predefined namespaces and parameters

Constant +namespace-dns+
Constant +namespace-url+
Constant +namespace-oid+
Constant +namespace-x500+

Constant predefined namespace of UUIDs.

Parameter *uuid-random-state*

Pseudo random generator used by version 4 UUID.

Parameter *uuids-per-tick*

The number of allowed UUIDs in the same time. Used by version 1 UUID.

The default value is 1000.

Parameter *uuid-node* 0.9.12
Parameter *uuid-clock-seq* 0.9.12

Parameters for testing purpose. It should not be used in a usual occasion.

### Converters

Function uuid->bytevector uuid

Returns bytevector converted from given uuid.

    (uuid->bytevector (make-null-uuid))

#vu8(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
Function uuid->string uuid

Returns string represented uuid converted from given uuid.

    (uuid->string (make-null-uuid))

00000000-0000-0000-0000-000000000000
Function bytevector->uuid bv

Returns uuid object generated from bv.

Given bytevector must have length at least 16.

Function string->uuid string

Returns uuid object generated from string.

Given string must be proper format of UUID defined in RFC 4122.

Function uuid->urn-format uuid

Returns URN formatted string of given uuid.

## (rfc websocket) - WebSocket

Library (rfc websocket)

This library provides WebSocket APIs defined by RFC 6455.

Following is a simple example to use user level APIs.

    (import (rnrs) (rfc websocket))

    ;; Creates an WebSocket object
    (define websocket (make-websocket "wss://echo.websocket.org"))

    ;; Sets text message event handler
    (websocket-on-text-message websocket
      (lambda (ws text) (display text) (newline)))

    ;; Opens the WebSocket
    (websocket-open websocket)

    ;; Sends a message to endpoint
    (websocket-send websocket "Hello")

    ;; Closes the WebSocket
    (websocket-close websocket)

### User level APIs

Function make-websocket uri :key (protocols '()) (extensions '()) (engine 'http)

Creates an WebSocket object which communicate to given uri.

The URI reprented by uri must be a valid WebSocket URI. If it's not a valid URI, then `&websocket-engine` or its sub condition shall be raised.

The keyword argument protocols are a list of sub protocols of the creating WebSocket. If this is set, then handshake will send it with `Sec-WebSocket-Protocol` header or equivalent.

The keyword argument extensions are a list of extensions of the creating WebSocket. If this is set, then handshake will send it with `Sec-WebSocket-Extensions` header or equivalent.

The keyword argument engine is a type of handshake engine and must be a symbol. This determines which handshake protocol it should use. The default value is `http` which uses HTTP/1.1.

Function websocket? obj

Returns #t if given obj is an WebSocket object otherwise #f.

Function websocket-open websocket

Operating handshake on given WebSocket object websocket if it's not opened, yet. And returns websocket.

If handshake failed, then `&websocket-engine` or its sub condition shall be raised.

After successfull call of this procedure, the websocket has a message dispatcher thread.

Function websocket-close websocket :key (status #f) (message "") (timeout #f)

Closes the given websocket if it's open and returns the websocket. This procedure also finishes the underlying thread created by `websocket-open`.

The keyword argument status is specified, it must be a non negative integer which has less then or equal to 16 bits length, then the procedure sends it as a connection close code.

The keyword argument message is specified, must be a string, then the procedure sends it as a connection close message. This is sent only if the status is specified otherwise ignored.

The keyword argument timeout is used as a timeout period for waiting underlying dispatcher thread. If the thread didn't finish in the specified period, then it'd be terminated and `&websocket-close-timeout` is raised.

If the underlying thread raised an `&uncaught-exception`, then the procedure raises its reason.

Function websocket-send websocket data :optional start splitter

Sends given data to the websocket and returns websocket. This procedure runs in atomic so the data is sent in one fragmentation sequence.

The optional arguments are passed to underlying data transport procedures. If the data is a string, then `websocket-send-text` is used. If the data is a bytevector, then `websocket-send-binary` is used. If the data is not one of the aboves, then `&assertion` is raised.

Function websocket-ping websocket data :optional (timeout #f) (timeout-value #f)

Send ping control frame whose data is data to _websocket_and returns websocket.

The procedure waits until the endpoint returns pong control frame. If the pong frame doesn't contain the same data in its payload, then `&websocket-pong` is raised.

The optional argument timeout specifies how long the procedure waits the pong response.

The optional argument timeout-value is an alternative value when the endpoint didn't return pong in time.

CAUTION: this procedure depends on the endpoint's behaviour.

#### Event handling

The user level APIs are event driven like JavaScript's WebSocket API. Whenever an event is occured, then the configured event handler is invoked.

There are 2 types of error handler invocations. One is calling active procedures such as `websocket-send`. The other one is passive situation such as receiving frame from endpoint. The first case, all active procedures would catch `&websocket` and its sub conditions. If the condition is `&websocket-engine` or its sub condition, then the condition is re-raised. Other `&websocket` conditions are not re-raised by the APIs. Other conditions are simply re-raised without invcating event handler. On the second case, it's mostly the same, but when `&websocket-closed` is raised, then event handler won't be invoked.

Function websocket-on-text-message websocket event-handler
Function websocket-on-binary-message websocket event-handler

Sets event-handler for receiving text message and binary message to websocket, respectively.

The event-handler must be a procedure which accepts 2 arguments, WebSocket object and response data, string or bytevector.

If the event-handler raises an error, and it's not a `&websocket`, then the dispatcher thread opened by `websocket-open` stops running.

The procedure returns websocket.

Function websocket-on-open websocket event-handler
Function websocket-on-close websocket event-handler

Sets event-handler for open and close event to websocket, respectively.

The event-handler must be a procedure which accepts 1 argument, WebSocket object.

The procedure returns websocket.

Function websocket-on-error websocket event-handler

Sets event-handler for error situation to websocket.

The event-handler must be a procedure which accepts 2 arguments, WebSocket object and a captured error.

If the event-handler raises an error, then it would be propagated caller of the user level APIs.

The procedure returns websocket.

### Low level APIs

The low level APIs can be used when users want to implement WebSocket process in programatic way. The user level APIs are implemented on this APIs.

#### WebSocket Connection

Function make-websocket-connection uri :optional (engine 'http)

Creates WebSocket connection object. uri and engine are the same as make-websocket.

Function websocket-connection? obj

Returns #t if given obj is WebSocket connection object otherwise #f.

Function websocket-connection-handshake! connection :optional (protocols '()) (extensions '()) :rest

Processes handshake on given connection. All the optional arguments are passed to underlying handshake engine.

Function websocket-connection-close! connection

Closes given connection. This procedure simply closes socket connection.

Function websocket-connection-closed? connection

Returns #t if the connection is not connected otherwise #f.

Function websocket-connection-pong-queue connection

Returns a shared queue which stores pong data from the endpoint of the connection.

#### WebSocket Messages

Function websocket-send-text connection data :optional (start 0) split
Function websocket-send-binary connection data :optional (start 0) split

Sends text or binary frame of data to given connection.

If the first procedure is called, then data must be a string.

If the second procedure is called, then data must be a bytevector.

The optional argument start specifies from which point of data to send.

The optional argument split is specified, it must be an non negative integer or procedure which accepts 2 arguments, data and start, then the data is sent fragmented.

Function websocket-send-close connection :optional (data #vu8()) (wait? #t)

Sends close control frame to given connection.

If the optional argument data is specified, it must be a properly coded connection close status, the it's sent as a payload of close frame.

If the optional argument wait? is true value, then the procedure waits until the endpoint sends close frame back.

If wait? is #f, then it is users responsibility to receive the response close frame and closes the connection.

Function websocket-send-ping connection :optional (data #vu8())
Function websocket-send-pong connection :optional (data #vu8())

Sends ping and pong frame to given connection respectively.

The optional argument data is sent as its payload.

NB: the payload must be less than 125 bytes.

Function websocket-receive connection :key (push-pong? #f)

Receives a data frame and return 2 values, opcode and payload.

If the frame is text, then returning value is a string. Otherwise returning value is a bytevector.

If the keyword argument push-pong? is true value, then payload of pong control frame will be pushed in to the `pong-queue`of the connection.

This procedure doesn't return ping and pong control frame.

Function websocket-receive-fragments connection proc :key (push-pong? #f)

Receives a data fragments until its end and return the result of the last call of proc.

The proc must accept 3 values, finished?, opcode and data.

This procedure is useful to receive a huge frame without concising.

The `websocket-receive` is implemented on top of this procedure like this:

    (define (websocket-receive conn :key (push-pong? #f))
      (define (convert opcode data)
        (if (eqv? opcode +websocket-text-frame+)
    	(values opcode (utf8->string data))
    	(values opcode data)))
      (let-values (((out extract) (open-bytevector-output-port)))
        (websocket-receive-fragments conn
         (lambda (fin? opcode data)
           (put-bytevector out data)
           (if fin? (convert opcode (extract)) (values opcode #f)))
         :push-pong? push-pong?)))

Function websocket-compose-close-status status :optional message

status must be an non negative integer whose bit length must be less than or equal to 16 bits.

If optional argument message is specified, then it must be a string.

Composes a payload of close frame.

Function websocket-parse-close-status data

data must be a payload of close frame.

Returns 2 values, status and mesasge of the close frame payload.

Constants +websocket-text-frame+
Constants +websocket-binary-frame+

WebSocket frame type constants. It represents text frame and binary frame, respectively.

Constants +websocket-close-frame+
Constants +websocket-ping-frame+
Constants +websocket-pong-frame+

WebSocket control frame type constants. It represents cloe frame, ping frame, and pong frame, respectively.

### Conditions

`&websocket` is a base condition of the WebSocket library's condition. The hierarchy is the following:

    + &error
      + &websocket
        + &websocket-engine
          + &websocket-engine-not-found
             - engine
    	 - reason
          + &websocket-engine-scheme
             - scheme
          + &websocket-engine-connection
             - host
    	 - port
        + &websocket-closed
           - status
           - message
        + &websocket-pong
           - pong-data
        + &websocket-close-timeout

The condition types are not exported by the library.

Function websocket-error? obj

## (rfc x.509) - X.509 certificate utility library

This library does not support whole feature of X.509, it just parse and verify a message and signature. So it can not verify certificate itself.

If you need more functionality, check `(sagittarius crypto x509)` library.

Library (rfc x.509)

Exports X.509 utility procedures.

Generic make-x509-certificate (in )
Generic make-x509-certificate (sequence <asn.1-sequence>)

Creates an X.509 certificate object from given binary input port or ASN.1 sequence object (second form).

Function x509-certificate? o

Return #t if the o is X.509 certificate object, otherwise #f.

Function x509-certificate-get-version x509

Return version of given X.509 certificate object.

Function x509-certificate-get-serial-number x509

Return serial number of given X.509 certificate object.

Function x509-certificate-get-issuer-dn x509

Return issuer DN of given X.509 certificate object as X.509 principal.

Function x509-certificate-get-subject-dn x509

Return subject DN of given X.509 certificate object as X.509 principal.

NOTE: These Issuer DN and Subject DN getters return <x.509-principal> object, however I did not implement any utility for this class, so it's just useless for now.

Function x509-certificate-get-not-before x509

Return start date of given X.509 certificate object.

Function x509-certificate-get-not-after x509

Return end date of given X.509 certificate object.

Function x509-certificate-get-signature x509

Return signature of given X.509 certificate object.

NOTE: This signature is not for `verify` described below.

Function x509-certificate-get-signature-algorithm x509

Return signature algorithm of given X.509 certificate object as an OID string.

Function x509-certificate-get-public-key x509

Return public key of given X.509 certificate object. The return value is `<public-key>` described in the section Key library - (sagittarius crypto keys).

Function verify x509 message signature . ignore

message and signature must be bytevector.

Verify given message with signature and x509 certificate.

Function check-validity x509 :optional (date (current-date))

Validate if the given certificate is valid in given date. Return #t if it's valid, otherwise raises `&assertion`.

## (rfc zlib) - zlib compression library

Library (rfc zlib)

This library provides the binding for zlib compression library. For now, it only provides the highest level APIs.

Condition Type &zlib-error
Function zlib-error? obj
Function condition-zlib-stream zlib-error

Subcondition of `&error`.

This condition is raised when zlib process is finished unsuccessfully. You can obtain the cause z-stream with the `condition-zlib-stream` procedure and get the detail message with the `zlib-error-message` procedure. When error occurred, however, it is raised with `message-condition` and it has the error message with. So you can simply get it with `condition-message`procedure.

Function zlib-error-message z-stream

Z-stream must be z-stream object.

Retrieve error message from z-stream. If z-stream does not have any error message and this procedure is called, the behaviour is unspecified.

Function open-deflating-output-port sink :key compression-level buffer-size window-bits memory-level _

_ strategy dictionary owner?

Sink must be binary output port. Creates a custom binary output port. The port deflates its input and put the result to sink. With the optional keys, you can specify the following conditions:

compression-level

  You can specify an exact integer between 1 and 9 (inclusive) to compression-level. When it is omitted, a default compression level is used, which is usually 6. The following constants are defined to specify _compression-level_conveniently:

  Constant Z_NO_COMPRESSION
  Constant Z_BEST_SPEED
  Constant Z_BEST_COMPRESSION
  Constant Z_DEFAULT_COMPRESSION
buffer-size

  It specifies the buffer size of the port in bytes. The default is 4096.

window-bits

  It specifies the size of the window in exact integer. Typically the value should be between 8 and 15, inclusive, and it specifies the base two logarithm of the window size used in compression. Larger number yields better compression ratio, but more memory usage. The default value is 15.

memory-level

  It specifies how much memory should be allocated to keep the internal state during compression. 1 means smallest memory which causes slow and less compression. 9 means fastest and best compression with the largest amount of memory. The default value is 8.

strategy

  To fine tune compression algorithm, you can use the strategy argument. The following constants are defined as the valid value as strategy.

  Constant Z_DEFAULT_STRATEGY

  The default strategy, suitable for most ordinary data.

  Constant Z_FILTERED

  Suitable for data generated by filters (or predictors). Filtered data consists mostly of small values with a somewhat compress them better. The effect of this is to force more huffman coding and less string matching.

  Constant Z_HUFFMAN_ONLY

  Force to use huffman encoding only.

  Constant Z_RLE

  This is designed to be almost as fast as Z_HUFFMAN_ONLY, but gives better compression for PNG image data.

  Constant Z_FIXED

  This prevents the use of dynamic huffman codes, allowing for a simpler decoder for special applications. The choice of strategy only affects compression ratio and speed. Any choice produces correct and decompressable data.

dictionary

  You can give an initial dictionary to the dictionary argument to be used in compression. The compressor and decompressor must use exactly the same dictionary.

owner?

  If this argument is specified true value, the created port automatically closes the given output port sink when it is closed.

Function open-inflating-input-port source :key buffer-size window-bits dictionary owner?

Source must be a binary input port.

The `open-inflating-input-port` creates a custom binary input port, which reads compressed binary data from the given port source and decompresses the read data. When source port supports both `port-position` and `set-port-position!` then the procedure will set source position to offset of used bytes length when the created custom port is being closed. Thus if the source port contains mixture of deflated data and non deflated data then the custom port will only read deflated data and won't forward the original port position beyond it no matter how big the buffer-size is specified.

The meaning of buffer-size is the same as `open-deflating-output-port`.

The meaning of window-bits is almost the same, except if a value increased by 32 is given, the inflating port automatically detecs whether the source stream is zlib or gzip by its header.

If the input data is compressed with specified dictionary, the same dictionary must be given to dictionary argument. Otherwise &zlib-error condition is raised.

Function inflate-bytevector bv opts ...
Function deflate-bytevector bv opts ...

Inflate/deflate given bytevector bv respectively.

These are convenient procedures. It uses `open-inflating-input-port` or `open-deflating-output-port` to inflate/deflate.

The opts will be passed to underlying procedures.

Function crc32 bv :optional (checksum 0)
Function adler32 bv :optional (checksum 0)

Returns CSC32/Adler32 checksum of bytevector bv, respectively.

If optional checksum is given, then returned checksum is an update of checksum by bv.

## RPC support framework

RPC is basically separated in 2 parts. One is message marshalling and other one is transporting. Following sections and libraries provide some framework for generic use.

### Message framework

Library (rpc message)

This library provides generic functions for marshalling message.

Generic rpc-marshall-message
Generic rpc-unmarshall-message

These generic function will be used transport layer to marshall or unmarshall messages.

### Http transport

Currently there is no generic transport framework and support HTTP transport.

For future, we may provide more generic way to send/receive request and response.

Library (rpc transport http)

This library provides procedures and generic function of HTTP transport for RCP

.

Function rpc-http-request url message :key (unmarshall? #t) :allow-other-keys options

Send given message to url and returns 3 values, http status, header and response.

If the keyword argument unmarshall? is #f then the returning response value will not be unmarshalled.

options will be passed to `http-request` procedure.

#### Http transport hook

Method rpc-http-method request

Returns http method. Default implementation returns `POST`

.

Method rpc-http-content-type request

Returns content type. Default implementation returns `application/octet-stream`

.

Method rpc-http-sender request

Returns http sender. Default implementation returns `http-blob-sender` with marshalled request

.

Method rpc-http-receiver request

Returns http receiver. Default implementation returns `http-binary-receiver`

.

Method rpc-http-response-type request

Returns a marker type to be used `rpc-http-unmarshall-message`. Default implementation returns given request itself

.

Method rpc-http-unmarshall-message type header body

Unmarshall the given body according to the given type. Default implementation ignores header and passes type and body to `rpc-unmarshall-message`.

## (rpc json) - JSON RPC library

Library (rpc json)

This library provides procedures handling JSON RPC 2.0.

This library doesn't provide transport layer. To send request and receive response, use Http transport.

This library uses JSON parser library and its JSON representation.

Following piece of code describes how to use;

    (import (rnrs) (rpc json) (rpc transport http))

    (define (json-rpc-send&request url method param)
      (let ((request (make-json-request method :param param)))
        (let-values (((status header response) (rpc-http-request url request)))
          ;; rpc-http-request unmarshalls only when HTTP status starts with "2"
          ;; for this example we don't check it.
          (json-response-result response))))

    (json-rpc-send&request "http://localhost/json-rpc" "sample" "parameter")
    ;; -> result of method execution

Class <json-request>
Class <json-response>

These classes represents JSON RPC request and response respectively.

The class instance should be created by `make-json-request`, `json-string->json-request` or `json-string->json-response`. Users should not create an instance directly using `make`.

### Predicates

Function json-request? object
Function json-response? object

Returns #t if the given object is an instance of `<json-request>` and `<json-response>` respectively.

### Constructors

Function make-json-request method :key (params '()) id

Creates a JSON RPC request.

method must be a symbol or string represents method name to be invoked.

The keyword argument params is the `params` field of the JSON RPC protocol.

The keyword argument id is the `id` field of the JSON RPC protocol. If this is not specified then a value generated by UUID v4 will be used.

Function json-string->json-request json
Function json-string->json-response json

Creates JSON RPC request and response from given JSON string json.

### Accessors

Function json-request-method json-request
Function json-request-params json-request
Function json-request-id json-request

Retrieves JSON RPC request's method, params and id respectively from given json request object json-request.

Function json-response-result json-response
Function json-response-id json-response

Retrieves JSON RPC response's result and id respectively from given json response object json-response.

### Converters

Function json-request->json-string json-request
Function json-response->json-string json-response

Converts given json-request and json-response to JSON string.

### Implemented methods

Following methods are currently used only in `(rpc http transport)`. When we support other transport, this implementation may change.

#### Message methods

Method rpc-marshall-message (message )

Converts to given JSON RPC request object to UTF8 bytes.

Method rpc-unmarshall-message (type (eql 'json)) body

Converts to given UTF8 bytes to JSON RPC response object.

#### Transport methods

Method rpc-http-content-type (message )

Returns `application/json` content type header value

Method rpc-http-response-type (message )

Returns `json` symbol.

## (security keystore) - Generic Keystore Access

Library (security keystore)

This library provides generic access for variety of keystores.

The following example shows how to use this library:

    (import (rnrs) (security keystore))

    (define keystore (load-keystore 'jks "keystore.jks" "storepass"))

    (keystore-get-key keystore "key-name" "key-pass")
    ;; -> <private-key>

    (keystore-get-certificate keystore "cert-name")
    ;; -> <x509-certificate>

    ;; certs must be a list of certificates
    (keystore-set-key! keystore "key-name2" private-key "key-pass2" certs)

    (keystore-set-certificate! keystore "cert-name2" cert)

    (store-keystore-to-file keystore "keystore2.jks" "storepass2")

### Generic APIs

Class <keystore>

Base class of keystores.

Function keystore? obj

Returns #t if given obj is a keystore object. Otherwise #f.

Function load-keystore type input-port storepass
Function load-keystore-file type file storepass

Loads type keystore from input-port or file.

storepass must be a string and may or may not be used to decrypt keystore content.

`load-keystore` loads from given binary input port input-port.

`load-keystore-file` loads from given file file.

Function make-keystore type

Returns newly created type keystore object.

Currently `pkcs12`, `jks` and `jceks` are supported.

Generic keystore-get-key keystore alias keypass

The method shall return a private key associated with _alias_from keystore. If there is no key entry associated with alias then #f shall be returned.

alias shall be a string.

keypass shall be a string. It may or may not be used to decrypt the private key.

Generic keystore-get-certificate keystore alias

The method shall return an X509 certificate associated with _alias_from keystore. If there is no certificate entry associated with alias then #f shall be returned.

alias shall be a string.

Generic keystore-get-certificate-chain keystore alias

The method shall return a list of key certificates associated with alias from keystore. If there is no certificate entries associated with alias then #f shall be returned.

alias shall be a string.

Generic keystore-get-creation-date keystore alias

The method shall return a date object of alias associated entry. If there is no entry associated with alias then #f shall be returned.

alias shall be a string.

Generic keystore-contains-alias? keystore alias

The method shall return #t if keystore contains an entry associated with alias. Otherwise #f shall be returend.

Generic keystore-aliases keystore 0.9.12

The method shall return all aliases in the given keystore as a list.

Generic store-keystore keystore output-port storepass
Generic store-keystore-to-file keystore file storepass

The methods shall write keystore to output-port or file.

The `store-keystore` shall write to given binary output port output-port.

The `store-keystore-to-file` shall write to given file file.

storepass shall be a string and may or may not be used to encrypt whole contents.

Generic keystore-set-key! keystore alias private-key keypass certs

alias shall be a string represents the name of private-key in the keystore.

private-key shall be an RSA private key.

key-pass shall be a string and may or may not be used to encrypt given private-key.

certs shall be a list of X509 certificates which associated with private-key.

The method shall store given private-key to keystore.

Generic keystore-set-certificate! keystore alias cert

alias shall be a string represents the name of cert in the keystore.

cert shall be an X509 certificate.

The method shall store given cert to keystore.

Generic keystore-delete-entry! keystore alias

The method shall remove the entry associated with alias from keystore.

## (security password) - Password policy

Library (security password)

Strong password is a base component for strong security. This library provides a password policies, validator and generator.

This example shows how to validate if the given password is compliant to the given password policy.

    (import (rnrs)
            (security password))

    ;; Password requires
    ;; - at least length of 16 characters,
    ;; - at least one lower char (a-z)
    ;; - at least one upper char (A-Z)
    ;; - at least one digit char (0-9)
    ;; - at least one symbol char ($#!)
    (define policy (password-policies
                    (make-length-policy 16)
                    (make-lower-case-policy 1)
                    (make-upper-case-policy 1)
                    (make-digit-policy 1)
                    (make-symbol-policy 1)))

    (password-policy-compliant? policy "password")         ;; -> #f
    (password-policy-compliant? policy "password12345678") ;; -> #f
    (password-policy-compliant? policy "pa$$word12345678") ;; -> #f
    (password-policy-compliant? policy "Pa$$word12345678") ;; -> #t

And this example shows how to generate a password which is compliant to the given password policy.

    (import (rnrs)
            (security password))

    ;; Password requires
    ;; - at least length of 16 characters,
    ;; - at least one lower char (a-z)
    ;; - at least one upper char (A-Z)
    ;; - at least one digit char (0-9)
    ;; - at least one symbol char ($#!)
    (define policy (password-policies
                    (make-length-policy 16)
                    (make-lower-case-policy 1)
                    (make-upper-case-policy 1)
                    (make-digit-policy 1)
                    (make-symbol-policy 1)))

    (generate-password policy) ;; -> "1uI#tfUzL_]H-<$%" (as an example)

The password generation is based on a random seed, so the result may differ on every invocation.

### Password policy operations

Function password-policy? obj

Returns `#t` if the given obj is a password policy, otherwise `#f`.

Function password-policies ( policy `password-policy?` ) ...

Construct a composite password policy which contains policies.

Function password-policy-compliant? ( policy `password-policy?` ) ( password `string?` )

Returns `#t` if the given password is compliant to the given policy, otherwise `#f`.

Function length-policy? obj

Returns `#t` if the given obj is a length policy, otherwise `#f`.

Function make-length-policy n

Creates a length policy of length n.

Function password-policy-length policy

Returns length of the policy, iff policy is a length policy or a composite policy which contains length policy, otherwise `#f`.

Function character-policy? obj

Returns `#t` if the given obj is a character policy, otherwise `#f`.

Function make-character-policy ( cset `char-set?` ) at-least

Creates a character policy of from cset which requires at least at-least characters.

Function password-policy-char-set policy

Returns charset of the policy, iff policy is a character policy or a composite policy which contains character policy, otherwise `#f`.

If the policy contains multiple character policy, then the returning charset is a unioned charset.

Function make-lower-case-policy at-least

Creates a character policy of `[a-z]` requires at least at-least.

Function make-upper-case-policy at-least

Creates a character policy of `[A-Z]` requires at least at-least.

Function make-symbol-policy at-least

Creates a character policy of ASCII symbols requires at least at-least.

Function make-digit-policy at-least

Creates a character policy of `[0-9]` requires at least at-least.

Function generate-password policy :key prng

Generates a password which is compliant to policy.

If the keyword argument prng is specified, then it must be a `peudo-random-generator` defined in `(sagittarius crypto random)`.

NOTE: using weak PRNG is not recommended. By default, the procedure uses ChaCha20

The procedure uses below parameter if the given policy doesn't contain some policies.

Parameter *password-policy:default-length*

Default password length, if the policy doesn't contain length policy.

Parameter *password-policy:default-char-set*

Default password charset, if the policy doesn't contain character policy.

Function password-policy-entropy policy

Calculates password entropy of the given policy.

The calculation formula: `log(expt(cs, l) 2)` where `cs` is the number of possible characters of the policy, and `l` is the length of the password.

Function password-policy->predicate policy

A convenient procedure. Returns a predicate which accepts a string and check if the given string is a compliant password or not.

### Generator integration

Function password-policy->generator policy

Creates a generator which generates string. Generated strings are compliant to the given policy.

This procedure can be used with `(sagittarius generators)` library. Suppose, you want to generate 5 random password which are compliant to your password policy, then it can be written like this

    (import (rnrs)
            (security password))

    (define policy (password-policies
                    (make-length-policy 16)
                    (make-lower-case-policy 1)
                    (make-upper-case-policy 1)
                    (make-digit-policy 1)
                    (make-symbol-policy 1)))

    (let ((g (gtake (password-policy->generator policy) 5)))
      (generator->list g))
    ;; a list containing 5 elements, all of them are compliant to policy

## (text csv) - Comma separated values parser library

Library (text csv)

This library provides comma separated values parser and write procedures. The implementation conforms RFC 4180.

### High level APIs

The high level APIs are implemented as object oriented style. So we have CSV object and its accessors.

Function csv? object

Returns #t if object is csv object, otherwise #f.

Generic csv-header (csv )

Retrieves CSV header from given CSV object csv if it has, otherwise '().

Generic csv-records (csv )

Retrieves CSV records from given CSV object csv if it has, otherwise '().

Generic csv-read (port ) . option
Generic csv-read (string ) . option

Reads CSV data from given port and returns csv object.

If the second form is called, the procedure opens string input port from given string and passes it to the first form.

The option will be passed to `csv->list` described below.

Generic csv-write (csv ) :optional (out (current-output-port))

Writes given CSV object csv to the output port port.

### Middle level APIs

Function csv->list port :optional (first-line-is-header? #f)

Reads CSV data from given input port port and returns alist representing CSV data.

If optional argument first-line-is-header? is #t, then the procedure reads the first line as header line.

The returning alist is following format;

    alist  := (header{0,1} record*)
    header := (:header value*)
    record := (:record value*)
    value  := string

Note: the value returning from `csv-records` or `csv-header` do not have meta values `:record` and `:header`.

### Low level APIs

Class <csv>

The class representing CSV. If you need to create empty CSV object, you can do like following code;

    (make <csv>)

.

Make sure, you import `(clos user)` library.

Generic add-record! (csv ) (list )

Adds a CSV representing record list to given CSV object csv.

The record must have `:record` keyword in the first element of the list.

Generic set-header! (csv ) (list )
Generic set-header! (csv ) (string )

Sets a CSV header list to given CSV object csv.

If the second form is called, then first parse the string to CSV header and calls the first form with parsed CSV header.

The list must have `:header` keyword in the first element of the list.

Generic add-records! (csv ) (list )
Generic add-records! (csv ) (string )

Convenient procedures.

Adds given CSV records list to given CSV object csv.

If the second form is called, then first parse the given string to CSV representing list and call the first form.

## (text html-lite) - Simple HTML document builder library

Library (text html-lite)

This library provides simple HTML builder procedures based on HTML5.

Function html-escape :optional (in (current-input-port))
Function html-escape-string string

Escapes the unsafe characters in HTML and returns escaped string.

The `html-escape` reads the string from optional argument in which must be an textual input port and returns an escaped string.

The `html-escape-string` takes a string and returns an escaped string.

Function html-doctype :key (type :html-4.01-strict)

Returns a doctype declaration for an HTML document. type can be one of the followings;

`:html-5`

  HTML 5

`:html-4.01-strict :html-4.01, :strict, :html-strict`

  HTML 4.01 Strict DTD

`:html-4.01-transitional :html-transitional, :transitional`

  HTML 4.01 Transitional DTD

`:xhtml-1.0-strict :xhtml-1.0`

  XHTML 1.0 Strict DTD

`:xhtml-1.0-transitional`

  XHTML 1.0 Transitional DTD

`:xhtml-1.0-frameset`

  XHTML 1.0 Frameset DTD

`:xhtml-1.1`

  XHTML 1.1 DTD

Function html: element args ...

Construct an HTML element element. Currently following elements are provided.

       a       abbr    address  area       article  aside
       audio   b       base     bdi        bdo      blockquote
       body    br      button   canvas     caption  cite
       code    col     colgroup command    datalist dd
       del     details dfn      div        dl       dt
       em      embed   fieldset figcaption figure   footer
       form
       h1      h2      h3       h4         h5       h6
       head    header  hgroup   hr         html
       i       iframe  img      input      ins      kbd
       keygen  label   legend   li         link     map
       mark    menu    meta     meter      nav      noscript
       object  ol      optgroup option     output   p
       param   pre     progress q          rp       rt
       ruby    s       samp     script     section  select
       small   source  span     strong     style    sub
       summary sup     table    tbody      td       textarea
       tfoot   th      thead    time       title    tr
       track   u       ul       var        video    wbr

The result of these functions is a tree of text segments, which can be written out to a port by `write-tree` or can be converted to a string by `tree->string` (text tree) - Lightweight text generation.

You can specify attributes of the element by using a keyword-value notation before the actual content.

    (tree->string (html:a :href "http://example.com" "example"))

\<a href="http://example.com">example\</a>

The boolean value given to the attribute has special meaning. If #t is given, the attribute is rendered without a value. If #f is given, the attribute is not rendered.

    (tree->string (html:table :border #t))

\<table border>\</table>

    (tree->string (html:table :border #f))

\<table>\</table>

Special characters in attribute values are escaped by the function, but the ones in the content are not.

    (tree->string (html:div :foo "<>&\"" "<not escaped>"))

\<div foo="&lt;&gt;&amp;&quot;">\<not escaped>\</div>

## (text json) -- JSON parser

Library (text json)

This library provides JSON parser and writer.

Parameter *json-map-type*

Controls mapping of JSON map and array. The value must be either `'vector` or `'alist`. The first one is compatible with Chicken Scheme's json module, the latter one is compatible with Gauche's `rfc.json` module. By default, it's set to `vector` for backward compatibility.

Conversion rules for `vector`:

    JSON array   <-> list
    JSON map     <-> vector
    JSON boolean <-> boolean
    JSON null    <-> symbol `null`

Conversion rules for `alist`:

    JSON array   <-> vector
    JSON map     <-> alist
    JSON boolean <-> boolean
    JSON null    <-> symbol `null`

This parameter affects the read and write procedures.

Function json-read :optional ( port `(current-input-port)` )

Reads JSON from given port and returns representing S-expression.

Function json-write json :optional ( port `(current-output-port)` )

Writes the given S-expression JSON representing object to given port.

Function json-write/normalized json :optional ( port `(current-output-port)` )

Writes the given S-expression JSON representing object to given port.

The written JSON doesn't have excess space.

Function json-write/pretty json :optional ( port `(current-output-port)` ) 0.9.12

Writes the given S-expression JSON representing object to given port.

The written JSON is formatted to human readable.

Function json-read-error? obj
Function json-write-error? obj

Returns `#t` if the given obj is `&json-read` or `&json-write` respectively, otherwise `#f`.

## (text json object-builder) -- JSON object builder/serializer

Library (text json object-builder)

This library provides Scheme object -> JSON string and vice versa utilities.

### JSON object builder

JSON object builder is a Schem object which contains information to construct a Scheme object from JSON representation. Currently this can be created only via `json-object-builder` macro.

Function json:builder? obj

Returns #t if the given obj is a JSON object builder.

Macro json-object-builder ctr spec ...
Auxiliary syntax ?
Auxiliary syntax @

A DSL which constructs JSON object builder.

The spec must be one of the followings:

- `(@ ->array spec)`

- `(@ ->array)`

- `(ctr mapping ...)`

- `ctr/builder`

->array must be a procedure which accepts variable length of arguments, such as `list` or `vector`.

ctr must be a procedure which accepts the same number of the specified keys in the mapping and constucts object.

ctr/builder must be either object constructor described above or JSON object builder created by the `json-object-builder`.

If the first 2 form is used, then the created builder handles JSON array.

If the 3rd form is used, then the created builder handles JSON object (a.k.a map).

If the lsst form is used, then the created builder handles simple JSON values, such as JSON string and number.

The mapping must be one of the followings:

- `(? key default spec)`

- `(? key default)`

- `(key spec)`

- `key`

key must be a string represents the JSON object's key.

default must be a Scheme object which is used when the key is absent.

The first 2 forms represetns optional values. If the JSON object key key is not present, then default is mapped to the result Scheme object.

Here are some of examples:

    (json-object-builder
     (make-image-holder
      ("Image"
      (make-image
       "Width"
       "Height"
       "Title"
       ("Thumbnail"
        (make-thumbnail
         "Url"
         "Height"
         "Width"))
       "Animated"
       ("IDs" (  list))))))
    #|
    Above construct Scheme object from JSON like the following:
    {
      "Image": {
        "Width":  800,
        "Height": 600,
        "Title":  "View from 15th Floor",
        "Thumbnail": {
          "Url":    "http://www.example.com/image/481989943",
          "Height": 125,
          "Width":  100
      },
        "Animated" : false,
        "IDs": [116, 943, 234, 38793]
      }
    }
    |#

    (json-object-builder
     (  list
        (make-location
         "precision"
         "Latitude"
         "Longitude"
         (? "Address" #f)
         "City"
         "State"
         "Zip"
         "Country")))
    #|
    Above construct Scheme object from JSON like the following:
    [
      {
        "precision": "zip",
        "Latitude":  37.7668,
        "Longitude": -122.3959,
        "Address":   "",
        "City":      "SAN FRANCISCO",
        "State":     "CA",
        "Zip":       "94107",
        "Country":   "US"
      },
      {
        "precision": "zip",
        "Latitude":  37.371991,
        "Longitude": -122.026020,
        "City":      "SUNNYVALE",
        "State":     "CA",
        "Zip":       "94085",
        "Country":   "US"
      }
    ]
    |#

Function json->object json builder :optional missing-key-handler
Function json-string->object json-string builder :optional missing-key-handler
Function read-object-from-json builder :optional ( in-port `(current-input-port)` ) missing-key-handler

Constructs Scheme object from given json, _json-string_or in-port, according to the given builder.

If the first form is used, then json must be a vector type JSON representation specified by the `*json-map-type*` parameter.

    (let ((json-string "{\"bar\": {\"buz\": 1}}"))
      (define-record-type foo
        (fields bar))
      (define-record-type bar
        (fields buz))
      (define bar-builder (json-object-builder (make-bar "buz")))
      (define builder (json-object-builder (make-foo ("bar" bar-builder))))

      (json-string->object json-string builder))

foo

If missing-key-handler is given, then it must be a procedure accepts 2 arguments. This procedure is called when the conversion procedure met keys which is not defined in builder. The default behaviour is raising an error.

Parameter *post-json-object-build*
Parameter *post-json-array-build*

These parameters hold a procedure which is called when an object is constructed from JSON object (map) or JSON array, respectively.

### JSON object serializer

JSON object serializer is a Schem object which contains information to construct a JSON representaion from Scheme object. Currently this can be created only via `json-object-serializer` macro.

Function json:serializer? obj

Returns #t if the given obj is a JSON object serializer.

Macro json-object-serializer ctr spec ...
Auxiliary syntax ?
Auxiliary syntax @
Auxiliary syntax ->

A DSL which constructs JSON object serializer.

The spec must be one of the followings:

- `(-> car cdr null? spec)`

- `(-> car cdr null?)`

- `(-> spec)`

- `(->)`

- `(@ ref length spec)`

- `(@ ref length)`

- `(@ spec)`

- `(@)`

- `(mapping mapping* ...)`

- `converter/serializer`

`->` indicates that the given object is a listlike object which can be accessed sequentially. car, cdr and null? specifies how to retrieve the car part and cdr part, and how to check if the object is empty or not, respectively. If these are not given then the macro uses `car`, `cdr` and `null?`.

`@` indicates that the given object is a vectorlike object which can be accessed randomly. ref and length specifies how to access the element of the object, and how to retrieve the length of the object, respectively. If these are not given then the macro uses `vector-ref`, and `vector-length`.

If both of the form don't have `spec`, then the macro uses the given value.

`mapping` must be one of the followings:

- `(? name absent ref spec)`

- `(? name absent ref)`

- `(name ref spec)`

- `(name ref)`

`?` indicates that referencing object might be absent.

name must be a string which represents JSON object's key.

absent must be an object indicating absent value. If the converting object is equal to this value in sense of `equal?`, then the constructed JSON representaion don't have name.

ref must be a accessor which is a procedure accepts one argument.

converter/serializer must be either a JSON object serializer or a procedure which accepts one argument and returns JSON representaion.

    (json-object-serializer
      (-> (("precision" location-precision)
           ("Latitude" location-latitude)
           ("Longitude" location-longitude)
           (? "Address" #f location-address)
           ("City" location-city)
           ("State" location-state)
           ("Zip" location-zip)
           ("Country" location-country))))

    ;; Above constructs JSON representaion from the following record type.
    (define-record-type location
      (fields precision latitude longitude address city state zip country))

    (json-object-serializer
     (("Image" image-holder-image
       (("Width" image-width)
        ("Height" image-height)
        ("Title" image-title)
        ("Thumbnail" image-thumbnail
    	(("Url" thumbnail-url)
    	 ("Height" thumbnail-height)
    	 ("Width" thumbnail-width)))
        ("Animated" image-animated)
        ("IDs" image-ids (->))))))

    ;; Above constructs JSON representaion from the following record type.
    (define-record-type image-holder
      (fields image))
    (define-record-type image
      (fields width height title thumbnail animated ids))
    (define-record-type thumbnail
      (fields url height width))

Function object->json obj serializer

Converts Scheme object to JSON representaion.

The converted JSON representaion is the same as `'vector` representaion.

Function object->json-string obj serializer

Converts Scheme object to JSON string.

Function write-object-as-json obj serializer :optional ( out-port `(current-output-port)` )

Writes JSON string converted from obj to out-port.

## (text json jmespath) - JMESPath

Library (text json jmespath)

This library provides JMESPath procedures. JMESPath is defined on JMESPath.

The following example shows how to use the library:

    (import (rnrs) (text json jmespath))

    ((jmespath "a") '#(("a" . "foo") ("b" . "bar") ("c" . "baz")))

foo

### Scheme APIs

Function jmespath path

Returns a procedure takes one argument, which must be a vector representad JSON.

The given path must be a string which is a valid JMESPath, otherwise raises `&jmespath`.

#### Conditions

This section describes conditions might be raised by the `jmespath`procedure or the procedure returned by the `jmespath` procedure.

The library doesn't export the condition type itself. (e.g. `&jmespath`isn't exported from the library). However for the comprehensivity, we also describe the hierarchy of the conditions here:

    + &error (standard R6RS error)
      + &jmespath
        + &jmespath:parse
        + &jmespath:expression
            - expression
            - argument
          + &jmespath:compile
          + &jmespath:runtime

The `&jmespath` is the root condition. This condition itself won't be raised.

The `&jmespath:parse` is the condition raised by the parser. This means either the given expression is lexically incorrect or grammartically incorrect.

The `&jmespath:expression` is the base condition of both `&jmespath:compile` and `&jmespath:runtime`. This condition itself won't be raised.

The `&jmespath:compile` is the condition raised by the compiler. This means the parsed expression is syntatically incorrect.

The `&jmespath:runtime` is the condition raised by the returned procedure. This means evaluation error. For example, a string is passed to the `avg`function.

Function jmespath-error? obj

Returns #t if the given obj is an instance of `&jmespath`, otherwise #f.

Function jmespath-parse-error? obj

Returns #t if the given obj is an instance of `&jmespath:parse`, otherwise #f.

The `&jmespath:parse` is a sub condition of `&jmespath`.

Function jmespath-error-expression jmespath-error

Returns `expression` field of the given jmespath-error.

The the given jmespath-error must be a sub condition of `&jmespath:expression`.

Function jmespath-error-arguments jmespath-error

Returns `arguments` field of the given jmespath-error.

The the given jmespath-error must be a sub condition of `&jmespath:expression`.

Function jmespath-compile-error? obj

Returns #t if the given obj is an instance of `&jmespath:compile`, otherwise #f.

The `&jmespath:compile` is a sub condition of `&jmespath:expression`.

Function jmespath-runtime-error? obj

Returns #t if the given obj is an instance of `&jmespath:runtime`, otherwise #f.

The `&jmespath:runtime` is a sub condition of `&jmespath:expression`.

### Extra functions

This library provides extra functions for usability.

JMESPath Function parent node

Returns parent node of the given node. This function can be used like this:

    ((jmespath "*.bar.parent(@)") '#(("foo" . #(("bar" . 1)))))

'(#((bar . 1)))

A literal doesn't have a parent so returns `null`.

    ((jmespath "parent(`{}`)") '#(("foo" . #(("bar" . 1)))))

'null

JMESPath Function unique array

Returns unique elements of the given array. This function can be used like this:

    ((jmespath "unique(@)") '(1 2 1 2 3))

'(1 2 3)

It raises a `&jmespath:runtime` if the give array is not an array.

JMESPath Function is_odd number

Returns #t if the given number is an odd number. This function can be used like this:

    ((jmespath "is_odd(@)") '5)

#t

It raises a `&jmespath:runtime` if the give number is not a number.

JMESPath Function is_even number

Returns #t if the given number is an even number. This function can be used like this:

    ((jmespath "is_even(@)") '5)

#t

It raises a `&jmespath:runtime` if the give number is not a number.

JMESPath Function remove array/object expr

Removes element from the given array/object if the _expr_returns true value.

The array/object must be an array or object.

The expr must be an expression reference.

The expr is executed in the context of the elements of array/object. Means if the `@` is passed to the expr, then the receiving value is one of the elements of the array/object.

This function can be used like this:

    ((jmespath "remove(@, &odd(@))") '(1 2 3 4 5))

'(1 3 5)

It raises a `&jmespath:runtime` if the give array/object is not either an array or object, or if the given expr is not a function reference.

JMESPath Function remove_entry object array/expr

Removes entries from the given object either if array/expr is an array of string and it contains the key of the entry or if array/expr is a function expression and returns true value.

The object must be an object.

This function can be used like this:

    ((jmespath "remove_entry(@, `[\"key2\"]`)") '#(("key" . 1)))

'#((key . 1))

    ((jmespath "remove_entry(@, &contains(`[\"key2\"]`, @))")
     '#(("key" . 1) ("key2" . 2)))

'#((key . 1))

It raises a `&jmespath:runtime` if the give object is not an object, or if the given array/expr is not an array of string or function reference.

JMESPath Function array_of any ...

Returns array of given arguments any.

    ((jmespath "array_of(`1`, `2`, `3`)") 'null)

'(1 2 3)

## (text json mutable) - Mutable JSON

Library (text json mutable)

This library provides an mutable JSON representation.

The following example shows how to use:

    (import (rnrs)
            (text json mutable))

    (define json '#(("key" . "value")))
    (define mutable-json (json->mutable-json json))

    (mutable-json-object-set! mutable-json "key" '#(("value" . "as object")))

    (mutable-json->json mutable-json)
    ;; -> #(("key" . #(("value" . "as object"))))

Function json->mutable-json json

Converts the given json to a mutable JSON.

Function mutable-json->json mutable-json

Converts the given mutable-json to a JSON.

Function mutable-json? obj

Returns `#t` if the given obj is a mutable JSON, otherwise `#f`.

Mutable JSON object consists with 2 containers

- Mutable JSON object

- Mutable JSON array

### Mutable JSON object

Mutable JSON object is a JSON object. The difference is a mutable JSON object doesn't allow to have multiple identical keys while JSON object allows it.

Function mutable-json-object? obj

Returns `#t` if the given obj is a mutable JSON object, otherwise `#f`.

Function mutable-json-object-set! mutable-json-object key value

Associates the given key and value to the mutable-json.

Function mutable-json-object-merge! mutable-json-object mutable-json-object1 ... mutable-json-object*

Merges the mutable-json-object1 and mutable-json-object* into mutable-json-object.

Function mutable-json-object-delete! mutable-json-object key

Remves the given key from the mutable-json-object.

Function mutable-json-object-contains? mutable-json-object key

Returns `#t` if the given key exists in the mutable-json-object, otherwise `#f`.

Function mutable-json-object-ref mutable-json-object key

Returns the value associated with the given key in the mutable-json-object, otherwise returns `mutable JSON not found`object.

Function mutable-json-not-found? obj

Returns `#t` if the given obj is a mutable JSON not found, otherwise `#f`.

### Mutable JSON array

Mutable JSON array is a JSON array with capability of expansion or shrinking.

Function mutable-json-array? obj

Returns `#t` if the given obj is a mutable JSON array otherwise `#f`.

Function mutable-json-array-set! mutable-json-array index value

Sets the given value value to the _mutable-json-array_on position of index.

Function mutable-json-array-insert! mutable-json-array index value

Insets the given value value to the _mutable-json-array_on position of index.

Function mutable-json-array-delete! mutable-json-array index

Deletes the value of given _mutable-json-array_on position of index and shrink it.

Function mutable-json-array-ref mutable-json-array index

Retrieves the value of mutable-json-array on position of index.

Function mutable-json-array-size mutable-json-array

Returns the size of the given mutable-json-array.

## (text json pointer) - JSON Pointer

Library (text json pointer)

This library provides JSON Pointer procedures.

The specification of JSON Pointer is defined by the RFC 6901.

The following example shows simple usage of the library:

This is an input file named `example.json`.

    {
      "id": 1234,
      "data": {
        "datum0": [0, 1, 2],
        "datum1": [3, 4]
      }
    }

(import (rnrs) (rfc json-pointer) (text json))

(define id-pointer (json-pointer "/id"))

(let ((json (call-with-input-file "example.json" json-read))) (id-pointer json)) ```

    1234

    (import (rnrs) (rfc json-pointer) (text json))

    (define data-pointer (json-pointer "/data"))

    #|
    example.json
    |#
    (let ((json (call-with-input-file "example.json" json-read)))
      ;; Retrievs /data/datum0
      ((json-pointer "/datum0" data-pointer) json))

'(0 1 2)

Function json-pointer pointer: optional parent

Returns a procedure takes one which must be a list or vector representing JSON object. The given poinster must be a string or textual input port which start with `/`.

The optional argument parent is passed, then it must be a procedure returned by the `json-pointer` and is called before the current pointer is processed.

0.9.12 The returning procedure is called with second argument, then it will be the default value of not-found. This is useful when you are writing something below:

    (define (wrap p)
      (lambda (json default)
        (let ((r (p json)))
          (if (json-pointer-not-found? r)
              default
              r))))
    (define pointer (wrap (json-pointer "/foo")))
    (pointer json #f)

The above can simply be like this:

    (define pointer (json-pointer "/foo"))
    (pointer json #f)

## (text json patch) - JSON Patch

Library (text json pointer)

This library provides JSON Patch procedures.

The specification of JSON Patch is defined by the RFC 6902.

The following example shows simple usage of the library:

This is an input file named `example.json`.

    {
      "id": 1234,
      "data": {
        "datum0": [0, 1, 2],
        "datum1": [3, 4]
      }
    }

    (import (rnrs) (text json patch) (text json))

    (define data-patcher
     (json-patcher
      '(#(("op" . "replace") ("path" . "/data/datum0") ("value" . "ok"))
        #(("op" . "remove") ("path" . "/data/datum1")))))

    (let ((json (call-with-input-file "example.json" json-read)))
      (data-patcher json))

#((id . 1234) (data . #((datum0 . ok))))

Function json-patcher patch

Returns a procedure takes one argument which must be a list or vector representing JSON object. The given patch must be a list of vector which represents JSON patch.

Function json-patch-error? obj

Returns #t if the given obj is an instance of `&json-patch`condition.

`&json-patch` is the base condition of this library. The hierarchy is the following:

    &json-patch
     + &json-patch:runtime (path)
       + &json-patch-path-not-found
       + &json-patch-illegal-type
     + &json-patch:compile (patch)

Function json-patch-compile-error? obj

Returns #t if the given obj is an instance of `&json-patch:compile` condition.

Function json-patch-error? obj

Returns #t if the given obj is an instance of `&json-patch:runtime` condition.

Function json-patch-path-not-found-error? obj

Returns #t if the given obj is an instance of `&json-patch-path-not-found` condition.

Function json-patch-path-illegal-type-error? obj

Returns #t if the given obj is an instance of `&json-patch-illegal-type` condition.

Function json-patch-error-path json-patch-error

Returns the `path` field of the given json-patch-error if the condition is type of `&json-patch-runtime`.

Function json-patch-error-patch json-patch-error

Returns the `patch` field of the given json-patch-error if the condition is type of `&json-patch-compile`.

Parameter *json-patcher:ignore-no-such-path*

Flag to supress no such path error. The value must be either a symbol or a list of symbol of the name of the patch command. If the value is matched with the patch command, then the runtime doesn't raise a condition.

Function json-diff json0 json1

Creates JSON patch from given json0 and json1.
The returning patch is json1 to json1 format.

## (text json schema) - JSON Schema

Library (text json schema)

This library provides JSON Schema procedures.

Currently, it supports the below drafts of JSON Schema

- Draft 7

- Draft 2019-09

- Draft 2029-12

### JSON Schema validator

The following example shows how to use the JSON Schema validator.

The following JSON Schema defines the structure of product catalogue. It's saved in the file `product.schema.json`

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "http://example.com/product.schema.json",
      "title": "Product",
      "description": "A product from Acme's catalog",
      "type": "object",
      "properties": {
        "productId": {
          "description": "The unique identifier for a product",
          "type": "integer"
        },
        "productName": {
          "description": "Name of the product",
          "type": "string"
        },
        "price": {
          "description": "The price of the product",
          "type": "number",
          "exclusiveMinimum": 0
        }
      },
      "required": [ "productId", "productName", "price" ]
    }

We want to validate the following 2 JSON files whose content are the below:

- `valid-product.json`

- `invalid-product.json`

    {
      "productId": 1,
      "productName": "A green door",
      "price": 12.50,
      "tags": [ "home", "green" ]
    }

    {
      "productId": "This must be an integer",
      "productName": 1234,
      "price": -1
    }

For the simple validation, you can write the following code:

    (import (rnrs)
            (text json)
            (text json schema)
            (text json validator))

    (define product-catalogue-schema
      (json-schema->json-validator
       (call-with-input-file "product.schema.json" json-read)))

    (define valid-catalogue
      (call-with-input-file "valid-product.json" json-read))

    (define invalid-catalogue
      (call-with-input-file "invalid-product.json" json-read))

    (values (validate-json product-catalogue-schema valid-catalogue)
            (validate-json product-catalogue-schema invalid-catalogue))

(values #t #f)

If you want to see the first invalid property, then you can write like this:

    (import (rnrs)
            (text json)
            (text json schema)
            (text json validator)
            (srfi :39 parameters))

    (define product-catalogue-schema
      (json-schema->json-validator
       (call-with-input-file "product.schema.json" json-read)))

    (define valid-catalogue
      (call-with-input-file "valid-product.json" json-read))

    (define invalid-catalogue
      (call-with-input-file "invalid-product.json" json-read))

    (parameterize ((*json-schema:validator-error-reporter*
                    simple-json-schema-error-reporter))
      (validate-json product-catalogue-schema valid-catalogue)
      (validate-json product-catalogue-schema invalid-catalogue))
    ;; Prints the following
    #|
    /productId
                 object: "This must be an integer"
            schema path: #/$defs/product/properties/productId/type
    |#

(values #t #f)

If you want to run as a lint mode, which goes through entire JSON, you can write like this:

    (import (rnrs)
            (text json)
            (text json schema)
            (text json validator)
            (srfi :39 parameters))

    (define product-catalogue-schema
      (json-schema->json-validator
       (call-with-input-file "product.schema.json" json-read)))

    (define valid-catalogue
      (call-with-input-file "valid-product.json" json-read))

    (define invalid-catalogue
      (call-with-input-file "invalid-product.json" json-read))

    (parameterize ((*json-schema:validator-error-reporter*
                    simple-json-schema-error-reporter)
                   (*json-schema:lint-mode?* #t))
      (validate-json product-catalogue-schema valid-catalogue)
      (validate-json product-catalogue-schema invalid-catalogue))
    ;; Prints the following
    #|
    /productId
                 object: "This must be an integer"
            schema path: #/$defs/product/properties/productId/type
    /productName
                 object: 1234
            schema path: #/$defs/product/properties/productName/type
    /price
                 object: -1
            schema path: #/$defs/product/properties/price/exclusiveMinimum
    |#

(values #t #t)

NOTE: On the lint mode, the validation result will always be `#t`.

Function json-schema->json-validator schema dependencies ...

Creates JSON validator object of the given JSON Schema schema.

The JSON Schema must be a vector represented S-expression JSON (see JSON parser).

JSON validator is described in JSON validator.

The optional arguments dependencies must be JSON Schema or JSON Schema validators, if it's given, then the procedure uses them as external dependency. This is useful if the `*json-schema:resolve-external-schema*` parameter is `#f` or, you don't want to make any socket connection.

Parameter *json-schema:resolve-external-schema?*

Specifying if the validator creation procedure to resolve external reference of schema. e.g. `"$ref": "http://json-schema.org/schema#"`.

The default value is `#f`.

Parameter *json-schema:external-schema-resolver*

Specifying the procedure to retrieve extrenal resource. This parameter supersedes the `*json-schema:resolve-external-schema?*` parameter.

The provided procedure must accept one argument, which is a string representation of external URL, and return Sexp JSON Schema.

Parameter *json-schema:validate-format?*

Specifying if the validator validates `"format"` keywords.

The default value is `#t`.

Parameter *json-schema:validator-error-reporter*

Specifying error reporter. The error reporter must be a procedure which accepts one argument.

Parameter *json-schema:report-port*

Specifying the port to be used to report error.

The default value is `(current-error-port)`

Parameter *json-schema:lint-mode?*

Specifying if the validator should act as if it's a linter.

To make this parameter effected, then `*json-schema:validator-error-reporter*` must also be specified.

The default value is `#f`.

Function simple-json-schema-error-reporter reports

The pre-defined error repoter for JSON schema validator. This error reporter doesn't show duplicated path, so if a JSON value contains multiple errors, then only one will be shown.

#### Custom error reporter

You can specify error reporting procedure by `*json-schema:validator-error-reporter*` parameter. The argument is a list of validation error report. Below procedures provide the accessor of the error report.

Function validation-report-object report

Returns erronous object.

Function validation-report-path report

Returns the JSON pointer (path) of the erronous object.

Function validation-report-schema-path report

Returns the JSON Schema path where the definition is defined.

## (text json validator) - JSON validator

Library (text json validator)

This library provides abstraction layer of JSON validation.

Record Type <json-validator>

Base class of JSON validators.

The record have `validator` field.

Function json-validator? obj

Return `#t` if the given obj is a JSON validator, otherwise `#f`.

Function make-json-validator validator

Creates a JSON validator.

The validator must be a procedure accepts one argument.

Function json-validator-validator json-validator

Returns the `validator` field value of the given json-validator.

Function validate-json json-validator json

Calls value of `validator` field of given JSON validator with parameter of json.

## (text sxml html-parser) - Flxible HTML parser

Library (text sxml html-parser)

This library provides HTML parser and printer procedures.

The provided procedures are compatible with HTMLPrag.

### High level APIs

Function html->sxml-0nf in
Function html->sxml-1nf in
Function html->sxml-2nf in
Function html->sxml in
Function html->shtml in

Parse given input port to SHTML. The in must be a textual input port.

The `html->sxml-2nf` procedure normalizes attributes if it doesn't have value. Others don't. Normalization in this context means adding attribute name as its value.

Function write-shtml-as-html shtml :optional out error-filter

Writes given shtml to out.

If optional argument out is given, it must be a textual output port, then the procedure writes to given output port. Otherwise `current-output-port` is used.

Optional argument error-filter is used when unexpected SHTML entity is met. It must be a procedure takes 2 arguments, unexpected entity and boolean flag indicates if the entity is attribute or not. By default, it raises an error.

Function shtml->html shtml

Converts shtml to string represented HTML.

### Low level APIs

Variable shtml-comment-symbol
Variable shtml-decl-symbol
Variable shtml-empty-symbol
Variable shtml-end-symbol
Variable shtml-entity-symbol
Variable shtml-pi-symbol
Variable shtml-start-symbol
Variable shtml-text-symbol
Variable shtml-top-symbol

SXML entity symbols: `*COMMENT*`, `*DECL*`, `*EMPTY*`, `*END*`, `*ENTITY*`, `*PI*`, `*START*`, `*TEXT*` and `*TOP*` respectively.

Variable shtml-named-char-id
Variable shtml-numeric-char-id

These variables are used in `*ENTITY*` as public identifier.

Function make-shtml-entity value

Makes SHTML character entity. The value must be a symbol, string or integer.

    (make-shtml-entity 151)

(& 151)
Function shtml-entity-value

Retrieve SHTML entity value.

## (text markdown) -- Markdown parser and converter

Library (text markdown)

This library provides markdown parser.

The library consists with 3 parts, first one is the parser, second one is the converter which converts markdown node to HTML. And the last one is the extensions and its APIs.

A simple example of how to generate HTML snippet from Markdown document

    (import (rnrs)
            (text markdown)
            (text sxml serializer))

    (define markdown-doc "
    Hello markdown
    ==============

    - list
    - list2
    ")

    (srl:sxml->html-noindent
      (convert-markdown
        (parse-markdown markdown-parser (open-string-input-port markdown-doc))
    	default-markdown-converter 'html))

"<h1>Hello markdown</h1>\n<ul>\n<li>list</li>\n<li>list2</li>\n</ul>\n"

### Markdown parser APIs

Function markdown-parser? obj

Returns `#t` if the given obj is a Markdown parser, otherwise `#f`.

Function markdown-node? obj

Returns `#t` if the given obj is a Markdown node, otherwise `#f`.

Function parse-markdown parser
Function parse-markdown parser input-port

parser must be a Markdown parser.
If the second form is used, then input-port must be a textual input port. If the first form is used, then `(current-input-port)` will be used.
Parse Markdown document retrieved from the given textual port and returns Markdown node.

Function markdown-parser:parse parser
Function markdown-parser:parse parser input-port

Alias of the `parse-markdown` for better naming matching.

Variable markdown-parser

Sagittarius default Markdown parser, this parser supports the following Markdown syntax:

- Commonmark 0.30

- GFM table syntax

- Strikethrough

- Task list item

- Definition lists: see Supported syntax

- Footnote: see Supported syntax

Variable commonmark-parser

Strictly complying commonmark specification parser. This parser only supports Commonmark syntax.

#### Supported syntax

For those well-known syntax, please refer the appropriate links listed on the `markdown-parser`.

##### Definition lists

Definition lists can be written like this:

    definition
    : description
      can also be multiple lines

    definition2
    : description of definition2

##### Footnotes

Footnote can be written like this:

    Lorem ipsum[^lorem]

    ^[lorem]: dolor sit amet

### Markdown converter APIs

Function markdown-converter? obj

Returns `#t` if the given obj is a Markdown converter, otherwise `#f`.

Variable default-markdown-converter

A default converter. This converter supports the below converters and most of the extensions.

Variable markdown->html-converter

A markdown converter which converts Markdown node to HTML (SXML).
The result SXML can be converted to string by using `srl:sxml->html-noindent`
defined in `(text sxml serializer)` library.

NOTE: this converter only supports commonmark nodes. So if you want to use GFM or other extensions, use `default-markdown-converter` or create a custom converter.

Variable markdown->sxml-converter

A markdown converter which converts Markdown node to XML (SXML).
The result XML is mostly complies the commonmark DTD.

Function convert-markdown node converter type
Function convert-markdown node converter type options

Converts given node to type by using given converter.
If the second form is used then options must be a Markdown conversion options object.

Function markdown-converter:convert converter type node
Function markdown-converter:convert converter type node options

Alias of the `convert-markdown` with different argument order for better name match.

Function markdown-converter:merge converter0 converter1 ...

Merge given converters to one newly allocated converter.

Function markdown-conversion-options? obj

Returns `#t` if the given obj is a Markdown conversion options, otherwise `#f`.

Macro markdown-conversion-options-builder

A record builder macro. The field can be specified on this macro is below

`unknown-node-handler`

  A procedure must accept one argument, which is a markdown node.
  This is called when the converter doesn't know how to handle the given node.

`context-date`

  A context data for the converter. The value depends on the type of converter.

### Markdown extensions

Markdown parser and converter can be extended by using extensions. The below example creates a parser which supports only Commonmark syntax and strikethrough.

    (define (rnrs)
            (text markdown parser)
            (text markdown extensions gfm))
    (define strikethrough-parser
      (markdown-parser-builder:build
       (markdown-parser-builder (externsions (list gfm-strikethrough-extension)))))

Library (text markdown parser)

Markdown parser library which provides parser builder and other utility procedures.

Function markdown-parser-builder? obj

Returns `#t` if the given obj is a Markdown parser builder, otherwise `#f`.
A Markdown parser builder has the following fields

`block-parsers`

  A list of thunks to provide supporting block parsers.

`inline-parser-producer`

  A thunk to provide inline content parser.

`post-processors`

  A list of post processors

`extensions`

  A list of extensions

Macro markdown-parser-builder

A macro to build a Markdown parser builder generated by `(record builder)`.

Function markdown-parser-builder:build builder

Builder must be a Markdown parser builder.
Creates a Markdown parser from the given builder.

#### Supporting extensions

Here is the list of extension libraries and supporting extensions.

##### `(text markdown extensions gfm)`

Partial support of GFM extensions.

`gfm-strikethrough-extension`

  GFM strikethough extension. GFM strikethrough can be written like this:

      ~~example~~

`gfm-table-extension`

  GFM table extension. The below is an example of GFM table:

      | head1 | head2 |
      | ----- | ----- |
      | col1  | col2  |

`gfm-task-list-extension`

  GFM task list extension. The below is an example of GFM task list:

      - [] to be done
      - [ ] the same as above
      - [X] done
      - [x] also done

`gfm-extensions`

  This extension provides all the supporting GFM extensions described above.

##### `(text markdown extensions footnotes)`

Footnotes extension. This extension is still an experimental state, as there's no HTML footnotes tag.

`footnotes-extension`

  Footnotes extension. A footnote can be written like this:

      This is a paragraph[^note]

      ^[note]: this is a footnote

##### `(text markdown extensions definition-lists)`

Definition lists extension. This extension provides definition lists syntax.

`definition-lists-extension`

  Definition lists extension. A definition list can be written like this:

      define
      : description

##### `(text markdown extensions heading-anchor)`

Heading anchor extension. This extension provides auto heading anchor and named heading anchor. The auto heading anchor will generates an anchor from the heading text. And named heading anchor reads the special syntax as a heading anchor.
This extension is not in the default parser, if you need this, you need to create a custom parser.

`heading-anchor-extension`

  Heading anchor extension. A named heading anchor can be written like this:

      # Heading anchor example {#head1}

### Deprecated APIs

This section will be removed in the future release.

Below APIs are supported for backward compatibility. New application shouldn't use these APIs.

Function markdown-read in :key (as 'sxml) :allow-other-keys opt

Reads markdown from given input port in.

The keyword argument as specifies the return value. Following 3 are supported:

`sxml`

  Returns SHTML. The procedure uses `markdown-sexp->sxml` to convert raw markdown S-expression.

`html`

  Returns HTML string. The procedure uses `markdown-sexp->string` to convert raw markdown S-expression.

`sexp`

  Returns S-expression representation of markdown.

Parsing markdown is done by `parse-markdown`. The rest argument _opt_is passed to both `parse-markdown` and underlying conversion procedure. So if you want to read a markdown document as an HTML string without indentation, then the procedure should be called like the following:

    (markdown-read in :as 'html :no-indent #t)

Function string->markdown string :rest opt

Reads markdown from given string.

This procedure is thin wrapper of `markdown-read`. It opens string input port of string and call the `markdown-read`.

The rest argument opt is passed to `markdown-read`.

Function markdown-sexp->sxml sexp :key (no-reference #t) (no-notes #f) :allow-other-keys

Converts given markdown S-expression sexp to SXML.

The keyword arguments no-reference and no-notes control the result SXML to have reference section and note section. If the values are true values, then returning SXML doesn't have reference or note section.

Function markdown-sexp->string sexp :key (no-indent #f) :allow-other-keys opts

Converts given markdown S-expression sexp to HTML string.

The procedure first calls `markdown-sexp->sxml` passing sexp and opts then converts the returned value to HTML string.

The keyword argument no-indent controls if the returning string has indentation or not. If the value is true value, then returning string doesn't have indentation.

Function markdown-parser-error? obj

Returns #t if the given object is a markdown parser error condition, otherwise #f.

Function markdown-parser-position condition
Function markdown-parser-expected condition

Returns `position` and `expexted` slot of the given markdown parser error condition, respectively.

Function parse-markdown in :allow-other-keys

Parses given input port in and returns markdown S-expression.

The returning value is S-expression represented AST of markdown. The structure is not specified in this document yet, thus it might be changed in future.

## (text sxml object-builder) - SXML to Scheme object builder

Library (text sxml object-builder)

This library provides APIs to build Scheme object from SXML.

### High level APIs

Function sxml->object sxml builder :optional unknown-tag-handler

Builds a Scheme object from given SXML sxml. The _builder_must be a object-builder described below.

If optional argument unknown-tag-handler is given, then it must be a procedure accepts 2 arguments, builder and sxml. The procedure is called when the process met a tag which can't be handled by given builder. Users can return an object if needed. The default behaviour of the handler is raising an error.

Macro sxml-object-builder spec ...
Auxiliary syntax *namespace*
Auxiliary syntax <!>
Auxiliary syntax ?
Auxiliary syntax ??

A DSL which constructs object-builder.

The spec must be one of the followings:

- `(*namespace* ((ns uri) ...) spec ...)`

- `(* spec ...)`

- `(+ spec ...)`

- `(/ spec ...)`

- `(? spec ...)`

- `(<!> _tag_ builder)`

- `spec spec* ...`

- `(_tag_ _ctr_)`

- `(_tag_ _ctr_ _next_)`

tag can be either a symbol or the following clause:

- `(?? pred)`

pred must be a predicate of SXML tag.

ctr must be a procedure which takes 3 arguments, name, attributes and contents. These are SXML's tagname, list of attributes and SXML contents, respectively.

The first form of the spec specifies aliases of namespaces. Users can write qualified name with prefixed instead of unprefixed qualified name.

The second to forth form of spec specify the amount of nested spec ... existence. The `*` means 0 or more. The `+` means 1 or more. And the `?` means 0 or 1.

The fifth form of spec means cyclic structure.

The sixth form of spec means set of spec spec ....

The following shows how to use this DSL macro

    (define builder
      (sxml-object-builder
        (*namespace* ((ns "urn:foo")))
        (ns:bar list
          (ns:buz list)
          (foo list))))

The above definition can build an object from the following SXML

    (*TOP*
      (urn:foo:bar
        (urn:foo:buz "buz")
        (foo "foo")))

A generic SXML builder can be written like this:

    (define-record-type xml-object
      (fields name attributes contents))

    (define xml-object-builder
      (sxml-object-builder
       (<!> (?? values) make-xml-object)))

#### XML object

This section describes convenience record type and procedures.

Record Type xml-object
Function xml-object? obj
Function make-xml-object name attributes contents
Function xml-object-name xml-object
Function xml-object-attributes xml-object
Function xml-object-contents xml-object

A very simple XML object type. An instance of this record type holds tag name (name), attribute as alist (attributes) and contents which must be a valid SXML or other XML objects (contents).

Function sxml->xml-object sxml :optional handler

Builds XML object described above from given sxml.

## (text tree) - Lightweight text generation

Library (text tree)

Defines simple but commonly used functions for a text construction.

This library is ported from Gauche.

Generic write-tree tree :optional out

Write out an tree as a tree of text, to the output port out. If the out is omitted, then current output port is used.

Function tree->string tree

Just calls the `write-tree` method for _tree] using an output string port, and returns the result string. _

## (text yaml) -- YAML parser

Library (text yaml)

This library provides YAML parser and writer.

Function yaml-read in

Reads YAML documents from the given textual input port in and returns a list of S-expression represented YAML documents.

The returning YAML documents are the compatible with vector JSON format described in (text json).

    (yaml-read (open-string-input-port "
    %YAML 1.2
    ---
    foo: bar
    boo:
    - 1
    - 2
    - 3
    - 4"))

'(#((foo . bar) (boo 1 2 3 4)))

Function yaml-write yaml
Function yaml-write yaml out

Writes the given list of S-expression represented YAML documents yaml to the out.

If the first form is used, then it writes to `(current-output-port)`.

    (yaml-write '(#(("foo" . "bar") ("boo" 1 2 3 4))))
    ;; Prints the following
    #|
    %YAML 1.2
    ---
    foo: bar
    boo:
    - 1
    - 2
    - 3
    - 4
    ...
    |#

## (util timer) - Timer

Library (util timer)

This library provides timer functionality.

Timer is the mechanism to trigger an event on specified time.

The following describes how to use;

    (import (util timer))

    (let ((timer (make-timer)))
      (timer-start! timer) ;; start timer
      ;; execute given thunk starting after 1000ms and each 1000ms
      (timer-schedule! timer (lambda () (display "timer!") (newline)) 1000 1000)
      ;; do something
      (timer-cancel! timer))

A timer is kind of task queue running on a timer thread. Once it's started, then it waits until its queue is not empty or the first task reaches the configured time. The tasks are executed sequentially however its order is not reliable if there are multiple tasks queued on the same time.

Function timer? obj

Returns #t if obj is a timer object, otherwise #f.

Function make-timer :key error-handler

Creates a timer object.

If keyword argument error-handler is specified, then it must be a procedure accepts one argument. The error-handler is called when timer procedure raises an error. If this is not specified, then timer stops when one of the tasks raised an error.

Function timer-state timer

Returns the state of given timer. The possible states are the followings:

created

  The timer is created and not executed yet.

running

  The timer is running.

stopped

  The timer is stopped (can be resumed).

cancelled

  The timer is cancelled (cannot be resumed).

Function timer-start! timer

Starts the given `created` state timer.

If the given timer's state is `stopped`, then this procedure resumes the given timer.

If the timer state is not `created` or `stopped`, then `&assertion` is raised.

Function timer-stop! timer

Stops the given time.

Function timer-cancel! timer

Cancel the given time. If one of the tasks raised an error and no error handler is specified, then this procedure will re-raise the error.

Once the timer is cancelled, then this timer is completely destroyed.

Function timer-schedule! timer thunk first :optional (period 0)

Schedules a timer task.

first can be time object or exact integer. If this is time object, then the timer executes the thunk with given time (absolute time). If this is an exact integer, then the timer executes the thunk after the given number milliseconds from current time.

Optional argument period specifies if the thunk is periodically executed or not. 0 is not periodical task.

The returning value is an ID of scheduled task. This is needed for `timer-remove!` and `timer-exists?` procedures.

Function timer-reschedule! timer timer-id first :optional (period 0)

Reschedules the timer task associated with timer-id and returns _timer-id_The first and period are the same as `timer-schedule!`.

Function timer-remove! timer id

Removes given id task from the timer.

Function timer-exists? timer id

Returns #t if given id task exists in the timer, otherwise #f.

## (tlv) - TLV library

Library (tlv)

This library provides TLV (tag length value) data operation procedures.

### High level APIs

Function make-emv-tlv-parser :key (object-builder tlv-builder)

Creates EMV type TLV parser.

This procedure returns a procedure which accepts a binary port as its argument.

The keyword argument `object-builder` specifies how to construct a TLV object. The default value is `tlv-builder`.

Function tlv-object? o

Returns #t if the given object is TLV object otherwise #f.

Function tlv-tag tlv

Returns TLV tag of given TLV object tlv.

Function tlv-data tlv

Returns TLV binary data if the given TLV object tlv is not constructed, otherwise #f.

Function tlv-components tlv

Returns TLV components of given TLV object tlv. If the _tlv_is not constructed, this returns `()`.

Function tlv->bytevector tlv

Converts given TLV object tlv to bytevector.

Function write-tlv tlv :optional (out (current-output-port))

out must be binary output port.

Writes given TLV object tlv to out as TLV data.

Function dump-tlv :optional (out (current-output-port))

Dump given TLV object tlv as human readable form.

### Custom object builder

Sometimes default TLV object is not convenient to use. Then users can create own object from TLV data passing own object builder to the `make-emv-tlv-parser` procedure.

Function tlv-builder first-byte tag data constructed?

Default TLV object builder. User should not use this procedure directly.

first-byte is the first byte of the leading TLV object.

tag is the read tag of the TLV object.

data is either a list of TLV object or bytevector. User can check it with constructed? argument.

constructed? indicates if the TLV object is constructed or not. If this is #t then data is a list of TLV objects.

## (util treemap) - Treemap

Library (util treemap)

This library provides treemap data structure and operations.

This section uses the following name convention;

tm - treemap

### Predicate and constructurs

Function treemap? object

Returns #t when given object is a treemap.

Function make-rb-treemap compare

compare must be a procedure which accepts 2 arguments and returns integer indicating the order of given 2 arguments.

Creates red black treemap.

### Basic operations

Function treemap-ref tm key :optional (fallback #f)

Returns a value associated with key in tm. If it doesn't exist, then fallback will be returned.

Function treemap-contains? tm key

Returns #t if there is an entry associated to the given key, otherwise #f.

Function treemap-set! tm key value

Associate the value to key in tm and returns unspecified value.

Function treemap-update! tm key proc default

proc must be a procedure accepts one argument.

Updates the entry value associated to key with the returned value of proc. If the entry doesn't exist then default will be passed to the proc.

Function treemap-delete! tm key

Deletes entry of key in tm and returns unspecified value.

Function treemap-clear! tm

Removes all entries and returns unspecified value.

Function treemap-copy tm

Returns the copy of given tm.

Function treemap-size tm

Returns the number of entry in the given tm.

### Conversions

Function treemap->alist tm

Returns an alist of key and value in tm.

Function alist->treemap alist compare

alist must be an alist. compare must be a procedure which accepts 2 arguments.

Converts alist to a treemap. The car part of an element of _alist_is a key, then cdr part of an element of alist is a value.

### Keys and values

Function treemap-keys tm
Function treemap-keys-list tm

Returns a vector or a list of keys in tm, respectively.

Function treemap-values tm
Function treemap-values-list tm

Returns a vector or a list of entry values in tm, respectively.

Function treemap-entries tm
Function treemap-entries-list tm

Returns vectors or lists of entry key and values in tm, respectively. This procedure returns 2 values.

### Iterations

Function treemap-fold kons tm knil

kons must be a procedure which accepts 3 arguments.

Iterates all keys and values in the given tm and passes them and the result of kons to kons respectively. The first iteration of the third argument is knil. The procedure returns the result of all iterations.

Analogous to `fold`.

Function treemap-map proc tm
Function treemap-for-each proc tm

proc must be a procedure which accepts 2 arguments.

Iterates all keys and values in the given tm and passes them to proc respectively.

The `treemap-for-each` returns unspecified value. The `treemap-map` returns a list of the proc result.

These procedures are analogous to `for-each` and `map` respectively.

## (util vector) - Extra vector utility library

Library (util vector)

This library provides extra vector utility procedures which is not provided neither `(srfi :43 vectors)` nor `(srfi :133 vectors)`.

Function vector-filter pred vec
Function vector-remove pred vec

Returns newly allocated vector which contains the elements from the given vec satisfied the given pref.

The `vector-filter` uses the elements which pred returns true value.

The `vector-remove` removes the elements which pred returns true value.

Function vector-find pred vec

Returns the element of the given vec satisfies the _pred_or #f.

# Ported libraries

In this world, there are a lot of useful Scheme programs including SRFIs. It is better if you can use it, instead of writing the same functionality from scrach. For this purpose, I have ported some libraries which I though useful.

In this section, I describe these libraries. However most of the documentations are from its manual or comments. I hava just derived from their source, manuals, or documents.

## (match) -- Pattern matching

The `match` is originally from Alex Shin's `portable hygineic pattern matcher' The documents below are derived from his source code.

Library (match)

This is a full superset of the popularmatchpackage by Andrew Wright, written in fully portable `syntax-rules`and thus preserving hygiene.

The most notable extensions are the ability to use _non-linear_patterns - patterns in which the same identifier occurs multiple times, tail patterns after ellipsis, and the experimental tree patterns.

### Patterns

Patterns are written to look like the printed representation of the objects they match. The basic usage is

    (match expr (pat body ...) ...)

where the result of expr is matched against each pattern in turn, and the corresponding body is evaluated for the first to succeed. Thus, a list of three elements matches a list of three elements.

    (let ((ls (list 1 2 3))) (match ls ((1 2 3) #t)))

If no patterns match an error is signalled.

Identifiers will match anything, and make the corresponding binding available in the body.

    (match (list 1 2 3) ((a b c) b))

If the same identifier occurs multiple times, the first instance will match anything, but subsequent instances must match a value which is `equal?` to the first.

    (match (list 1 2 1) ((a a b) 1) ((a b a) 2))

The special identifier `_` matches anything, no matter how many times it is used, and does not bind the result in the body.

    (match (list 1 2 1) ((_ _ b) 1) ((a b a) 2))

To match a literal identifier (or list or any other literal), use `quote`.

    (match 'a ('b 1) ('a 2))

Analogous to its normal usage in scheme, `quasiquote` can be used to quote a mostly literally matching object with selected parts unquoted.

    (match (list 1 2 3) (`(1 ,b ,c) (list b c)))

Often you want to match any number of a repeated pattern. Inside a list pattern you can append `...` after an element to match zero or more of that pattern (like a regexp Kleene star).

    (match (list 1 2) ((1 2 3 ...) #t))

    (match (list 1 2 3) ((1 2 3 ...) #t))

    (match (list 1 2 3 3 3) ((1 2 3 ...) #t))

Pattern variables matched inside the repeated pattern are bound to a list of each matching instance in the body.

    (match (list 1 2) ((a b c ...) c))

    (match (list 1 2 3) ((a b c ...) c))

    (match (list 1 2 3 4 5) ((a b c ...) c))

More than one `...` may not be used in the same list, since this would require exponential backtracking in the general case. However, `...` need not be the final element in the list, and may be succeeded by a fixed number of patterns.

    (match (list 1 2 3 4) ((a b c ... d e) c))

    (match (list 1 2 3 4 5) ((a b c ... d e) c))

    (match (list 1 2 3 4 5 6 7) ((a b c ... d e) c))

`___` is provided as an alias for `...` when it is inconvenient to use the ellipsis (as in a `syntax-rules` template).

The `..1` syntax is exactly like the `...` except that it matches one or more repetitions (like a regexp "+").

    (match (list 1 2) ((a b c ..1) c))

    (match (list 1 2 3) ((a b c ..1) c))

The boolean operators `and`, `or` and `not`can be used to group and negate patterns analogously to their Scheme counterparts.

The `and` operator ensures that all subpatterns match. This operator is often used with the idiom `(and x pat)` to bind x to the entire value that matches pat(c.f. "as-patterns" in ML or Haskell). Another common use is in conjunction with `not` patterns to match a general case with certain exceptions.

    (match 1 ((and) #t))

    (match 1 ((and x) x))

    (match 1 ((and x 1) x))

The `or` operator ensures that at least one subpattern matches. If the same identifier occurs in different subpatterns, it is matched independently. All identifiers from all subpatterns are bound if the `or` operator matches, but the binding is only defined for identifiers from the subpattern which matched.

    (match 1 ((or) #t) (else #f))

    (match 1 ((or x) x))

    (match 1 ((or x 2) x))

The `not` operator succeeds if the given pattern doesn't match. None of the identifiers used are available in the body.

    (match 1 ((not 2) #t))

The more general operator `?` can be used to provide a predicate. The usage is `(? predicate pat ...)` where predicate is a Scheme expression evaluating to a predicate called on the value to match, and any optional patterns after the predicate are then matched as in an `and` pattern.

    (match 1 ((? odd? x) x))

The field operator `=` is used to extract an arbitrary field and match against it. It is useful for more complex or conditional destructuring that can't be more directly expressed in the pattern syntax. The usage is `(= field pat)`, where field can be any expression, and should result in a procedure of one argument, which is applied to the value to match to generate a new value to match against pat.

Thus the pattern `(and (= car x) (= cdr y))` is equivalent to `(x . y)`, except it will result in an immediate error if the value isn't a pair.

    (match '(1 . 2) ((= car x) x))

    (match 4 ((= sqrt x) x))

The record operator `$` is used as a concise way to match records defined by SRFI-9 (or SRFI-99). The usage is `($ rtd field ...)`, where rtd should be the record type descriptor specified as the first argument to `define-record-type`, and each field is a subpattern matched against the fields of the record in order. Not all fields must be present.

    (let ()
      (define-record-type employee
        (make-employee name title)
        employee?
        (name get-name)
        (title get-title))
      (match (make-employee "Bob" "Doctor")
        (($ employee n t) (list t n))))

The `set!` and `get!` operators are used to bind an identifier to the setter and getter of a field, respectively. The setter is a procedure of one argument, which mutates the field to that argument. The getter is a procedure of no arguments which returns the current value of the field.

    (let ((x (cons 1 2))) (match x ((1 . (set! s)) (s 3) x)))

    (match '(1 . 2) ((1 . (get! g)) (g)))

The new operator `***` can be used to search a tree for subpatterns. A pattern of the form `(x *** y)` represents the subpattern y located somewhere in a tree where the path from the current object to y can be seen as a list of the form `(x ...)`. y can immediately match the current object in which case the path is the empty list. In a sense it's a 2-dimensional version of the `...` pattern.

As a common case the pattern `(_ *** y)` can be used to search for y anywhere in a tree, regardless of the path used.

    (match '(a (a (a b))) ((x *** 'b) x))

    (match '(a (b) (c (d e) (f g))) ((x *** 'g) x))

### Syntax

Macro match expr (pattern . body) ...
Macro match expr (pattern (=> failure) . body) ...

turn, according to the pattern rules described in the previous section, until the the first pattern matches. When a match is found, the corresponding _body_s are evaluated in order, and the result of the last expression is returned as the result of the entire `match`. If a failure is provided, then it is bound to a procedure of no arguments which continues, processing at the next pattern. If no pattern matches, an error is signalled.

Macro match-lambda clause ...

Shortcut for `lambda` + `match`. Creates a procedure of one argument, and matches that argument against each clause.

Macro match-lambda* clause ...

Similar to `match-lambda`. Creates a procedure of any number of arguments, and matches the argument list against each clause.

Macro match-let ((pat expr) ... ) body-expr ...
Macro match-let name ((pat expr) ... ) body-expr ...

Matches each var to the corresponding expression, and evaluates the body with all match variables in scope. Raises an error if any of the expressions fail to match. Syntax analogous to named let can also be used for recursive functions which match on their arguments as in `match-lambda*`.

Macro match-letrec ((pat expr) ... ) body-expr ...

Similar to `match-let`, but analogously to `letrec`matches and binds the variables with all match variables in scope.

Macro match-let* ((pat expr) ... ) body-expr ...

Similar to `match-let`, but analogously to `let*`matches and binds the variables in sequence, with preceding match variables in scope.

## (text parse) - Parsing input stream

Library (text parse)

The `(text parse)` library is inspired and compatible with Oleg Kiselyov's input parsing library. You can use this library in place of his `'input-parse.scm'` and `'look-for-str.scm'`.

Function find-string-from-port? str in-port :optional max-no-char

Looks for a string str from the input port in-port. The optional argument max-no-char limits the maxmum number of characters to be read from the port; the search span is until EOF.

If str is found, the function returns the number of characters it has read from the port, and the port is set to read the first char after that (that is, after the str). If str is not found, the function returns #f.

Note: Although this procedure has ``?'` in its name, it may return non-boolean value, contrary to the Scheme convention.

In the following functions, char-list refers to one of the following.

- A character set which defined in SRFI-14.

- A list of characters, character sets and/or symbol `*eof*`.

That denotes a set of characters. If a symbol `*eof*` is included, the EOF condition is also included. Without `*eof*`, the EOF condition is regarded as an error.

Function assert-curr-char char-list string :optional port

Reads a character from the port and looks it up in the char-list of expected characters. If the read character was found among the expected, it is returned. Otherwise, the procedure writes a nasty message using string as a comment, and quits.

Function skip-until char-list/number :optional port

Char-list/number must be either char-list or number.

If it is a number; skips the specified number of characters from the port and returns #f.

If it is a char-list; reads and skips characters from the port until one of the break characters is encountered. This break character is returned. The break characters are specified as the char-list. This list may include EOF, which is to be coded as a symbol `*eof*`.

Function skip-while char-list :optional port

Advances the port to the first character that is not a member of the char-list -- or till the EOF, whichever occurs sooner. This character or the EOF object is returned. This character is left on the stream.

Function peek-next-char :optional port

Advances to the next character in the port and peeks at it. This function is useful when parsing LR(1)-type languages.

Function next-token prefix-char-list break-char-list :optional comment port

Skips any number of characters in prefix-char-list, then collects the characters until it sees break-char-list. The collected characters are returned as a string. The break character remains in the port.

If the function encounters EOF and `*eof*` is not included in break-char-list, an error is signalled with comment is included in the message.

Function next-token-of char-list/pred :optional port

Reads and collects the characters as far as it belongs to char-list/pred, then returns them as a string. The first character that doesn't belong to char-list/pred remains on the port.

Char-list/pred may be a char-list or a predicate that takes a character. If it is a predicate, each character is passed to it, and the character is regarded to ``belong to'' char-list/pred when it returns a true value.

Function read-string n :optional port

Reads up to n characters, collects them into a string, and returns it. If the input stream contains less characters, the returns string contains as many characters available.

This function is similar with `get-string-n`.

## (text sxml ssax) - Functional XML parser

Library (text sxml ssax)

`(text sxml *)` libraries are the adaptation of Oleg Kiselyov's SXML framework SSAX, which is based on S-expression representation of XML structure.

SSAX is a parser part of SXML framework.

This is a quote from SSAX webpage:

> The framework consists of a DOM/SXML parser, a SAX parser, and a supporting library of lexing and parsing procedures. The procedures in the package can be used separately to tokenize or parse various pieces of XML documents. The framework supports XML Namespaces, character, internal and external parsed entities, xml:space, attribute value normalization, processing instructions and CDATA sections. The package includes a semi-validating SXML parser: a DOM-mode parser that is an instantiation of a SAX parser (called SSAX). The parsing framework offers support for XML validation, to the full or any user-specified degree. Framework's procedures by themselves detect great many validation errors and almost all well-formedness errors. Furthermore, a user is given a chance to set his own handlers to capture the rest of the errors. Content is validated given user-specified constraints, which the user can derive from a DTD, from an XML schema, or from other competing doctype specification formats. SSAX is a full-featured, algorithmically optimal, pure-functional parser, which can act as a stream processor. SSAX is an efficient SAX parser that is easy to use. SSAX minimizes the amount of application-specific state that has to be shared among user-supplied event handlers. SSAX makes the maintenance of an application-specific element stack unnecessary, which eliminates several classes of common bugs. SSAX is written in a pure-functional subset of Scheme. Therefore, the event handlers are referentially transparent, which makes them easier for a programmer to write and to reason about. The more expressive, reliable and easier to use application interface for the event-driven XML parsing is the outcome of implementing the parsing engine as an enhanced tree fold combinator, which fully captures the control pattern of the depth-first tree traversal.

Sagittarius supports the latest version of SSAX 5.1.

All procedures and macros are described bottom up. So you might be interested only in user level APIs. If so, see Highest-level parsers: XML to SXML.

### Introduction

I derived the content of this part of the manual from SSAX source code, just by converting its comments into this manual format. The original text is by Oleg Kiselyov.

This is a package of low-to-high level lexing and parsing procedures that can be combined to yield a SAX, a DOM, a validating parsers, or a parser intended for a particular document type. The procedures in the package can be used separately to tokenize or parse various pieces of XML documents. The package supports XML Namespaces, internal and external parsed entities, user-controlled handling of whitespace, and validation. This module therefore is intended to be a framework, a set of "Lego blocks" you can use to build a parser following any discipline and performing validation to any degree. As an example of the parser construction, this file includes a semi-validating SXML parser.

The present XML framework has a "sequential" feel of SAX yet a "functional style" of DOM. Like a SAX parser, the framework scans the document only once and permits incremental processing. An application that handles document elements in order can run as efficiently as possible. Unlike a SAX parser, the framework does not require an application register stateful callbacks and surrender control to the parser. Rather, it is the application that can drive the framework -- calling its functions to get the current lexical or syntax element. These functions do not maintain or mutate any state save the input port. Therefore, the framework permits parsing of XML in a pure functional style, with the input port being a monad (or a linear, read-once parameter).

Besides the PORT, there is another monad -- SEED. Most of the middle- and high-level parsers are single-threaded through the seed. The functions of this framework do not process or affect the SEED in any way: they simply pass it around as an instance of an opaque datatype. User functions, on the other hand, can use the seed to maintain user's state, to accumulate parsing results, etc. A user can freely mix his own functions with those of the framework. On the other hand, the user may wish to instantiate a high-level parser: ssax:make-elem-parser or ssax:make-parser. In the latter case, the user must provide functions of specific signatures, which are called at predictable moments during the parsing: to handle character data, element data, or processing instructions (PI). The functions are always given the SEED, among other parameters, and must return the new SEED.

From a functional point of view, XML parsing is a combined pre-post-order traversal of a "tree" that is the XML document itself. This down-and-up traversal tells the user about an element when its start tag is encountered. The user is notified about the element once more, after all element's children have been handled. The process of XML parsing therefore is a fold over the raw XML document. Unlike a fold over trees defined in [1], the parser is necessarily single-threaded -- obviously as elements in a text XML document are laid down sequentially. The parser therefore is a tree fold that has been transformed to accept an accumulating parameter [1,2].

Formally, the denotational semantics of the parser can be expressed as

    parser:: (Start-tag -> Seed -> Seed) ->
    	 (Start-tag -> Seed -> Seed -> Seed) ->
    	 (Char-Data -> Seed -> Seed) ->
    	 XML-text-fragment -> Seed -> Seed

    parser fdown fup fchar "<elem attrs> content </elem>" seed
     = fup "<elem attrs>" seed
    	(parser fdown fup fchar "content" (fdown "<elem attrs>" seed))

    parser fdown fup fchar "char-data content" seed
     = parser fdown fup fchar "content" (fchar "char-data" seed)

    parser fdown fup fchar "elem-content content" seed
     = parser fdown fup fchar "content" (
    	parser fdown fup fchar "elem-content" seed)

Compare the last two equations with the left fold fold-left kons elem:list seed = fold-left kons list (kons elem seed)

The real parser created my ssax:make-parser is slightly more complicated, to account for processing instructions, entity references, namespaces, processing of document type declaration, etc.

The XML standard document referred to in this module is http://www.w3.org/TR/1998/REC-xml-19980210.htmlThe present file also defines a procedure that parses the text of an XML document or of a separate element into SXML, an S-expression-based model of an XML Information Set. SXML is also an Abstract Syntax Tree of an XML document. SXML is similar but not identical to DOM; SXML is particularly suitable for Scheme-based XML/HTML authoring, SXPath queries, and tree transformations. See SXML.html for more details. SXML is a term implementation of evaluation of the XML document [3]. The other implementation is context-passing.

The present frameworks fully supports the XML Namespaces Recommendation: http://www.w3.org/TR/REC-xml-names/Other links:

[1] Jeremy Gibbons, Geraint Jones, "The Under-appreciated Unfold," Proc. ICFP'98, 1998, pp. 273-279.

[2] Richard S. Bird, The promotion and accumulation strategies in transformational programming, ACM Trans. Progr. Lang. Systems, 6(4):487-504, October 1984.

[3] Ralf Hinze, "Deriving Backtracking Monad Transformers," Functional Pearl. Proc ICFP'00, pp. 186-197.

### Data Types

TAG-KIND

  a symbol `START`, `END`, `PI`, `DECL`, `COMMENT`, `CDSECT` or `ENTITY-REF` that identifies a markup token

UNRES-NAME

  a name (called GI in the XML Recommendation) as given in an xml document for a markup token: start-tag, PI target, attribute name. If a GI is an NCName, UNRES-NAME is this NCName converted into a Scheme symbol. If a GI is a QName, UNRES-NAME is a pair of symbols: (PREFIX . LOCALPART)

RES-NAME

  An expanded name, a resolved version of an UNRES-NAME. For an element or an attribute name with a non-empty namespace URI, RES-NAME is a pair of symbols, (URI-SYMB . LOCALPART). Otherwise, it's a single symbol.

ELEM-CONTENT-MODEL

  A symbol: ANY

  anything goes, expect an END tag. EMPTY-TAG

  no content, and no END-tag is coming EMPTY

  no content, expect the END-tag as the next token PCDATA

  expect character data only, and no children elements MIXED

  ELEM-CONTENT

URI-SYMB

  A symbol representing a namespace URI -- or other symbol chosen by the user to represent URI. In the former case, URI-SYMB is created by %-quoting of bad URI characters and converting the resulting string into a symbol.

NAMESPACES

  A list representing namespaces in effect. An element of the list has one of the following forms:

  (PREFIX URI-SYMB . URI-SYMB)(PREFIX USER-PREFIX . URI-SYMB) USER-PREFIX is a symbol chosen by the user to represent the URI.

  (#f USER-PREFIX . URI-SYMB)

  Specification of the user-chosen prefix and a URI-SYMBOL. (*DEFAULT* USER-PREFIX . URI-SYMB)

  Declaration of the default namespace (*DEFAULT* #f . #f)

  Un-declaration of the default namespace. This notation represents overriding of the previous declaration A NAMESPACES list may contain several elements for the same PREFIX. The one closest to the beginning of the list takes effect.

ATTLIST

  An ordered collection of (NAME . VALUE) pairs, where NAME is a RES-NAME or an UNRES-NAME. The collection is an ADT

STR-HANDLER

  A procedure of three arguments: STRING1 STRING2 SEED returning a new SEED The procedure is supposed to handle a chunk of character data STRING1 followed by a chunk of character data STRING2. STRING2 is a short string, often "\n" and even ""

ENTITIES

  An assoc list of pairs:

      (named-entity-name . named-entity-body)

  where named-entity-name is a symbol under which the entity was declared, named-entity-body is either a string, or (for an external entity) a thunk that will return an input port (from which the entity can be read). named-entity-body may also be #f. This is an indication that a named-entity-name is currently being expanded. A reference to this named-entity-name will be an error: violation of the WFC nonrecursion.
XML-TOKEN

  a record This record represents a markup, which is, according to the XML Recommendation, "takes the form of start-tags, end-tags, empty-element tags, entity references, character references, comments, CDATA section delimiters, document type declarations, and processing instructions." kind

  a TAG-KIND head

  an UNRES-NAME. For xml-tokens of kinds 'COMMENT and 'CDSECT, the head is #f For example,

      	<P>  => kind='START, head='P
      	</P> => kind='END, head='P
      	<BR/> => kind='EMPTY-EL, head='BR
      	<!DOCTYPE OMF ...> => kind='DECL, head='DOCTYPE
      	<?xml version="1.0"?> => kind='PI, head='xml
      	&my-ent; => kind = 'ENTITY-REF, head='my-ent

  Character references are not represented by xml-tokens as these references are transparently resolved into the corresponding characters.

XML-DECL

  a record The record represents a datatype of an XML document: the list of declared elements and their attributes, declared notations, list of replacement strings or loading procedures for parsed general entities, etc. Normally an xml-decl record is created from a DTD or an XML Schema, although it can be created and filled in in many other ways (e.g., loaded from a file). elems

  an (assoc) list of decl-elem or #f. The latter instructs the parser to do no validation of elements and attributes. decl-elem

  declaration of one element:

      (_elem-name_ _elem-content_ _decl-attrs_)

  elem-name is an UNRES-NAME for the element. elem-content is an ELEM-CONTENT-MODEL. decl-attrs is an ATTLIST, of (ATTR-NAME . VALUE) associations !!!This element can declare a user procedure to handle parsing of an element (e.g., to do a custom validation, or to build a hash of IDs as they're encountered). decl-attr

  an element of an ATTLIST, declaration of one attribute

      (_attr-name_ _content-type_ _use-type_ _default-value_)

  attr-name is an UNRES-NAME for the declared attribute content-type is a symbol: CDATA, NMTOKEN, NMTOKENS, ... or a list of strings for the enumerated type. use-type is a symbol: REQUIRED, IMPLIED, FIXED default-value is a string for the default value, or #f if not given.

Function make-xml-token kind head
Function xml-token? kind head

A constructor and a predicate for a XML-TOKEN record.

Macro xml-token-kind xml-token
Macro xml-token-head xml-token

Accessor macros of a XML-TOKEN record.

### Lower-level parsers and scanners

They deal with primitive lexical units (Names, whitespaces, tags) and with pieces of more generic productions. Most of these parsers must be called in appropriate context. For example, ssax:complete-start-tag must be called only when the start-tag has been detected and its GI has been read.

#### Low-level parsing code

Function ssax:skip-S port

Skip the S (whitespace) production as defined by

    [3] S ::= (#x20 | #x9 | #xD | #xA)

The procedure returns the first not-whitespace character it encounters while scanning the port. This character is left on the input stream.

Function ssax:ncname-starting-char? a-char

Read a Name lexem and return it as string

    [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | ':'
                     | CombiningChar | Extender
    [5] Name ::= (Letter | '_' | ':') (NameChar)*

This code supports the XML Namespace Recommendation REC-xml-names, which modifies the above productions as follows:

    [4] NCNameChar ::= Letter | Digit | '.' | '-' | '_'
                          | CombiningChar | Extender
    [5] NCName ::= (Letter | '_') (NCNameChar)*

As the Rec-xml-names says, "An XML document conforms to this specification if all other tokens [other than element types and attribute names] in the document which are required, for XML conformance, to match the XML production for Name, match this specification's production for NCName." Element types and attribute names must match the production QName, defined below.

Function ssax:read-NCName port

Read a NCName starting from the current position in the port and preturn it as a symbol.

Function ssax:read-QName port

Read a (namespace-) Qualified Name, QName, from the current position in the port.

    From REC-xml-names:
    	[6] QName ::= (Prefix ':')? LocalPart
    	[7] Prefix ::= NCName
    	[8] LocalPart ::= NCName

Return: an UNRES-NAME

Variable ssax:Prefix-XML

The prefix of the pre-defined XML namespace

Function name-compare name1 name2

Compare one RES-NAME or an UNRES-NAME with the other. Return a symbol '<, '>, or '= depending on the result of the comparison. Names without PREFIX are always smaller than those with the PREFIX.

Variable ssax:largest-unres-name

An UNRES-NAME that is postulated to be larger than anything that can occur in a well-formed XML document. name-compare enforces this postulate.

Function ssax:read-markup-token port

This procedure starts parsing of a markup token. The current position in the stream must be #\<. This procedure scans enough of the input stream to figure out what kind of a markup token it is seeing. The procedure returns an xml-token structure describing the token. Note, generally reading of the current markup is not finished! In particular, no attributes of the start-tag token are scanned.

Here's a detailed break out of the return values and the position in the _port_when that particular value is returned:

PI-token

  only PI-target is read. To finish the Processing Instruction and disregard it, call ssax:skip-pi. ssax:read-attributes may be useful as well (for PIs whose content is attribute-value pairs)

END-token

  The end tag is read completely; the current position is right after the terminating #\> character.

COMMENT

  is read and skipped completely. The current position is right after "-->" that terminates the comment.

CDSECT

  The current position is right after "<!CDATA[" Use ssax:read-cdata-body to read the rest.

DECL

  We have read the keyword (the one that follows "<!") identifying this declaration markup. The current position is after the keyword (usually a whitespace character)

START-token

  We have read the keyword (GI) of this start tag. No attributes are scanned yet. We don't know if this tag has an empty content either. Use ssax:complete-start-tag to finish parsing of the token.

Function ssax:skip-pi port

The current position is inside a PI. Skip till the rest of the PI

Function ssax:read-pi-body-as-string port

The current position is right after reading the PITarget. We read the body of PI and return is as a string. The port will point to the character right after '?>' combination that terminates PI.

    [16] PI ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'

Function ssax:skip-internal-dtd port

The current pos in the port is inside an internal DTD subset (e.g., after reading #\[ that begins an internal DTD subset) Skip until the "]>" combination that terminates this DTD

Function ssax:read-cdata-body port str-handler seed

This procedure must be called after we have read a string "<![CDATA[" that begins a CDATA section. The current position must be the first position of the CDATA body. This function reads lines of the CDATA body and passes them to a STR-HANDLER, a character data consumer.

The str-handler is a STR-HANDLER, a procedure STRING1 STRING2 SEED. The first STRING1 argument to STR-HANDLER never contains a newline. The second STRING2 argument often will. On the first invocation of the STR-HANDLER, the seed is the one passed to `ssax:read-cdata-body`as the third argument. The result of this first invocation will be passed as the seed argument to the second invocation of the line consumer, and so on. The result of the last invocation of the STR-HANDLER is returned by the ssax:read-cdata-body. Note a similarity to the fundamental 'fold' iterator.

Within a CDATA section all characters are taken at their face value, with only three exceptions:

- CR, LF, and CRLF are treated as line delimiters, and passed

- as a single #\newline to the STR-HANDLER

- "]]>" combination is the end of the CDATA section.

- > is treated as an embedded #\> character

Note, < and & are not specially recognized (and are not expanded)!

Function ssax:read-char-ref port

    [66]  CharRef ::=  '&#' [0-9]+ ';'
                     | '&#x' [0-9a-fA-F]+ ';'

This procedure must be called after we we have read "&#" that introduces a char reference. The procedure reads this reference and returns the corresponding char The current position in port will be after ";" that terminates the char reference Faults detected:

WFC

  XML-Spec.html#wf-Legalchar

According to Section "4.1 Character and Entity References" of the XML Recommendation:

> "[Definition: A character reference refers to a specific character in the ISO/IEC 10646 character set, for example one not directly accessible from available input devices.]"

Therefore, we use a ucscode->char function to convert a character code into the character -- *regardless* of the current character encoding of the input stream.

Function ssax:handle-parsed-entity port name entities comment-handler str-handler seed

Expand and handle a parsed-entity reference

port - a PORT

name - the name of the parsed entity to expand, a symbol

entities - see ENTITIES

content-handler -- procedure PORT ENTITIES SEED that is supposed to return a SEED

str-handler - a STR-HANDLER. It is called if the entity in question turns out to be a pre-declared entity

The result is the one returned by CONTENT-HANDLER or STR-HANDLER Faults detected:

WFC

  XML-Spec.html#wf-entdeclared

WFC

  XML-Spec.html#norecursion

Function make-empty-attlist
Function attlist-add attlist name-value
Function attlist-null? attlist
Function attlist-remove-top attlist
Function attlist->alist attlist
Function attlist-fold kons knil attlst

Utility procedures to deal with attribute list, which keeps name-value association.

Function ssax:read-attributes port entities

This procedure reads and parses a production Attribute*

    [41] Attribute ::= Name Eq AttValue
    [10] AttValue ::=  '"' ([^<&"] | Reference)* '"'
                    | "'" ([^<&'] | Reference)* "'"
    [25] Eq ::= S? '=' S?

The procedure returns an ATTLIST, of Name (as UNRES-NAME), Value (as string) pairs. The current character on the PORT is a non-whitespace character that is not an ncname-starting character.

Note the following rules to keep in mind when reading an 'AttValue' "Before the value of an attribute is passed to the application or checked for validity, the XML processor must normalize it as follows:

- a character reference is processed by appending the referenced character to the attribute value

- an entity reference is processed by recursively processing the replacement text of the entity [see ENTITIES] [named entities amp lt gt quot apos are assumed pre-declared]

- a whitespace character (#x20, #xD, #xA, #x9) is processed by appending #x20 to the normalized value, except that only a single #x20 is appended for a "#xD#xA" sequence that is part of an external parsed entity or the literal entity value of an internal parsed entity

- other characters are processed by appending them to the normalized value

"

Faults detected:

WFC

  XML-Spec.html#CleanAttrVals

WFC

  XML-Spec.html#uniqattspec

Function ssax:resolve-name port ures-name namespace apply-default-us?

Convert an UNRES-NAME to a RES-NAME given the appropriate NAMESPACES declarations. the last parameter apply-default-ns? determines if the default namespace applies (for instance, it does not for attribute names)

Per REC-xml-names/#nsc-NSDeclared, "xml" prefix is considered pre-declared and bound to the namespace name "http://www.w3.org/XML/1998/namespace".

This procedure tests for the namespace constraints: http://www.w3.org/TR/REC-xml-names/#nsc-NSDeclared

Function ssax:uri-string->symbol uri-str

Convert a URI-STR to an appropriate symbol

Function ssax:complete-start-tag tag port elems entities namespaces

This procedure is to complete parsing of a start-tag markup. The procedure must be called after the start tag token has been read. TAG is an UNRES-NAME. ELEMS is an instance of xml-decl::elems; it can be #f to tell the function to do no validation of elements and their attributes.

This procedure returns several values:

ELEM-GI

  a RES-NAME.

ATTRIBUTES

  element's attributes, an ATTLIST of (RES-NAME . STRING) pairs. The list does NOT include xmlns attributes.

NAMESPACES

  the input list of namespaces amended with namespace (re-)declarations contained within the start-tag under parsing

ELEM-CONTENT-MODEL

On exit, the current position in PORT will be the first character after #\> that terminates the start-tag markup.

Faults detected:

VC

  XML-Spec.html#enum

VC

  XML-Spec.html#RequiredAttr

VC

  XML-Spec.html#FixedAttr

VC

  XML-Spec.html#ValueType

WFC

  XML-Spec.html#uniqattspec (after namespaces prefixes are resolved)

VC

  XML-Spec.html#elementvalid

WFC

  REC-xml-names/#dt-NSName

Note, although XML Recommendation does not explicitly say it, xmlns and xmlns: attributes don't have to be declared (although they can be declared, to specify their default value)

Function ssax:read-external-id port

This procedure parses an ExternalID production:

    [75] ExternalID ::= 'SYSTEM' S SystemLiteral
    		| 'PUBLIC' S PubidLiteral S SystemLiteral
    [11] SystemLiteral ::= ('"' [^"]* '"') | ("'" [^']* "'")
    [12] PubidLiteral ::=  '"' PubidChar* '"' | "'" (PubidChar - "'")* "'"
    [13] PubidChar ::=  #x20 | #xD | #xA | [a-zA-Z0-9]
                             | [-'()+,./:=?;!*#@$_%]

This procedure is supposed to be called when an ExternalID is expected; that is, the current character must be either #\S or #\P that start correspondingly a SYSTEM or PUBLIC token. This procedure returns the SystemLiteral as a string. A PubidLiteral is disregarded if present.

#### Higher-level parsers and scanners

They parse productions corresponding to the whole (document) entity or its higher-level pieces (prolog, root element, etc).

Function ssax:scan-Misc port

Scan the Misc production in the context

    [1]  document ::=  prolog element Misc*
    [22] prolog ::= XMLDecl? Misc* (doctypedec l Misc*)?
    [27] Misc ::= Comment | PI |  S

The following function should be called in the prolog or epilog contexts. In these contexts, whitespaces are completely ignored. The return value from ssax:scan-Misc is either a PI-token, a DECL-token, a START token, or EOF. Comments are ignored and not reported.

Function ssax:read-char-data port expected-eof? str-handler seed

This procedure is to read the character content of an XML document or an XML element.

    [43] content ::=
    	(element | CharData | Reference | CDSect | PI
    	| Comment)*

To be more precise, the procedure reads CharData, expands CDSect and character entities, and skips comments. The procedure stops at a named reference, EOF, at the beginning of a PI or a start/end tag.

port

  a PORT to read

expect-eof?

  a boolean indicating if EOF is normal, i.e., the character data may be terminated by the EOF. EOF is normal while processing a parsed entity.

str-handler

  a STR-HANDLER

seed

  an argument passed to the first invocation of STR-HANDLER.

The procedure returns two results: SEED and TOKEN. The SEED is the result of the last invocation of STR-HANDLER, or the original seed if STR-HANDLER was never called.

TOKEN can be either an eof-object (this can happen only if expect-eof? was #t), or:

- an xml-token describing a START tag or an END-tag; For a start token, the caller has to finish reading it.

- an xml-token describing the beginning of a PI. It's up to an application to read or skip through the rest of this PI;

- an xml-token describing a named entity reference.

CDATA sections and character references are expanded inline and never returned. Comments are silently disregarded.

As the XML Recommendation requires, all whitespace in character data must be preserved. However, a CR character (#xD) must be disregarded if it appears before a LF character (#xA), or replaced by a #xA character otherwise. See Secs. 2.10 and 2.11 of the XML Recommendation. See also the canonical XML Recommendation.

Function ssax:assert-token token kind gi

Make sure that TOKEN is of anticipated KIND and has anticipated GI Note GI argument may actually be a pair of two symbols, Namespace URI or the prefix, and of the localname. If the assertion fails, error-cont is evaluated by passing it three arguments: token kind gi. The result of error-cont is returned.

### Highest-level parsers: XML to SXML

These parsers are a set of syntactic forms to instantiate a SSAX parser. A user can instantiate the parser to do the full validation, or no validation, or any particular validation. The user specifies which PI he wants to be notified about. The user tells what to do with the parsed character and element data. The latter handlers determine if the parsing follows a SAX or a DOM model.

Macro ssax:make-pi-parser my-pi-handlers

Create a parser to parse and process one Processing Element (PI).

my-pi-handlers

  An assoc list of pairs (PI-TAG . PI-HANDLER) where PI-TAG is an NCName symbol, the PI target, and PI-HANDLER is a procedure PORT PI-TAG SEED where PORT points to the first symbol after the PI target. The handler should read the rest of the PI up to and including the combination '?>' that terminates the PI. The handler should return a new seed. One of the PI-TAGs may be the symbol *DEFAULT*. The corresponding handler will handle PIs that no other handler will. If the *DEFAULT* PI-TAG is not specified, ssax:make-pi-parser will assume the default handler that skips the body of the PI

The output of the `ssax:make-pi-parser` is a

    ``procedure _PORT_ _PI-TAG_ _SEED_``

that will parse the current PI according to the user-specified handlers.

Macro ssax:make-elem-parser my-new-level-seed my-finish-element my-char-data-handler my-pi-handlers

Create a parser to parse and process one element, including its character content or children elements. The parser is typically applied to the root element of a document.

my-new-level-seed

  procedure ELEM-GI ATTRIBUTES NAMESPACES EXPECTED-CONTENT SEED where ELEM-GI is a RES-NAME of the element about to be processed. This procedure is to generate the seed to be passed to handlers that process the content of the element. This is the function identified as 'fdown' in the denotational semantics of the XML parser given in the title comments to this file.

my-finish-element

  procedure ELEM-GI ATTRIBUTES NAMESPACES PARENT-SEED SEED This procedure is called when parsing of ELEM-GI is finished. The SEED is the result from the last content parser (or from my-new-level-seed if the element has the empty content). PARENT-SEED is the same seed as was passed to my-new-level-seed. The procedure is to generate a seed that will be the result of the element parser. This is the function identified as 'fup' in the denotational semantics of the XML parser given in the title comments to this file.

my-char-data-handler

  A STR-HANDLER

my-pi-handlers

  See ssax:make-pi-handler above

The generated parser is a

    procedure _START-TAG-HEAD_ _PORT_ _ELEMS_ _ENTITIES_	 _NAMESPACES_ _PRESERVE-WS?_ _SEED_

The procedure must be called after the start tag token has been read. START-TAG-HEAD is an UNRES-NAME from the start-element tag. ELEMS is an instance of xml-decl::elems. See `ssax:complete-start-tag::preserve-ws?`Faults detected:

VC

  XML-Spec.html#elementvalid

WFC

  XML-Spec.html#GIMatch

Macro ssax:make-parser user-handler-tag user-handler-proc ...

Create an XML parser, an instance of the XML parsing framework. This will be a SAX, a DOM, or a specialized parser depending on the supplied user-handlers.

user-handler-tag is a symbol that identifies a procedural expression that follows the tag. Given below are tags and signatures of the corresponding procedures. Not all tags have to be specified. If some are omitted, reasonable defaults will apply.

tag: DOCTYPE
handler-procedure: PORT DOCNAME SYSTEMID INTERNAL-SUBSET? SEED

  If internal-subset? is #t, the current position in the port is right after we have read #\[ that begins the internal DTD subset. We must finish reading of this subset before we return (or must call skip-internal-subset if we aren't interested in reading it). The port at exit must be at the first symbol after the whole DOCTYPE declaration. The handler-procedure must generate four values: ELEMS ENTITIES NAMESPACES SEED See xml-decl::elems for ELEMS. It may be #f to switch off the validation. NAMESPACES will typically contain USER-PREFIXes for selected URI-SYMBs. The default handler-procedure skips the internal subset, if any, and returns (values #f '() '() seed)

tag: UNDECL-ROOT
handler-procedure ELEM-GI SEED

  where ELEM-GI is an UNRES-NAME of the root element. This procedure is called when an XML document under parsing contains no DOCTYPE declaration. The handler-procedure, as a DOCTYPE handler procedure above, must generate four values: ELEMS ENTITIES NAMESPACES SEED The default handler-procedure returns (values #f '() '() seed)

tag: DECL-ROOT
handler-procedure ELEM-GI SEED

  where ELEM-GI is an UNRES-NAME of the root element. This procedure is called when an XML document under parsing does contains the DOCTYPE declaration. The handler-procedure must generate a new SEED (and verify that the name of the root element matches the doctype, if the handler so wishes). The default handler-procedure is the identity function.

tag: NEW-LEVEL-SEED
handler-procedure

  see `ssax:make-elem-parser`, my-new-level-seed

tag: FINISH-ELEMENT
handler-procedure

  see `ssax:make-elem-parser`, my-finish-element

tag: CHAR-DATA-HANDLER
handler-procedure

  see `ssax:make-elem-parser`, my-char-data-handler

tag: PI
handler-procedure

  see `ssax:make-pi-parser`The default value is '() The generated parser is a procedure PORT SEED This procedure parses the document prolog and then exits to an element parser (created by `ssax:make-elem-parser`) to handle the rest.

    [1]  document ::=  prolog element Misc*
    [22] prolog ::= XMLDecl? Misc* (doctypedec | Misc*)?
    [27] Misc ::= Comment | PI |  S

    [28] doctypedecl ::=  '<!DOCTYPE' S Name (S ExternalID)? S?
    			('[' (markupdecl | PEReference | S)* ']' S?)? '>'
    [29] markupdecl ::= elementdecl | AttlistDecl
                         | EntityDecl
                         | NotationDecl | PI
                         | Comment

### Highest-level parsers: XML to SXML

First, a few utility procedures that turned out useful

Function ssax:reverse-collect-str list-of-frags

given the list of fragments (some of which are text strings) reverse the list and concatenate adjacent text strings. We can prove from the general case below that if LIST-OF-FRAGS has zero or one element, the result of the procedure is equal? to its argument. This fact justifies the shortcut evaluation below.

Function ssax:reverse-collect-str-drop-ws list-of-frags

given the list of fragments (some of which are text strings) reverse the list and concatenate adjacent text strings. We also drop "unsignificant" whitespace, that is, whitespace in front, behind and between elements. The whitespace that is included in character data is not affected. We use this procedure to "intelligently" drop "insignificant" whitespace in the parsed SXML. If the strict compliance with the XML Recommendation regarding the whitespace is desired, please use the `ssax:reverse-collect-str` procedure instead.

Function ssax:xml->sxml port namespaces

This is an instance of a SSAX parser above that returns an SXML representation of the XML document to be read from PORT. NAMESPACE-PREFIX-ASSIG is a list of (USER-PREFIX . URI-STRING) that assigns USER-PREFIXes to certain namespaces identified by particular URI-STRINGs. It may be an empty list. The procedure returns an SXML tree. The port points out to the first character after the root element.

## (text sxml sxpath) - Functional XML parser

Library (text sxml sxpath)

This library is ported from Kirill Lisovsky's SXPath which is based on Oleg Kiselyov's SXPath. The documents are from the original file.

SXPath is a query language for SXML, an instance of XML Information set (Infoset) in the form of s-expressions. See SSAX.scm for the definition of SXML and more details. SXPath is also a translation into Scheme of an XML Path Language, XPath:

> http://www.w3.org/TR/xpath

XPath and SXPath describe means of selecting a set of Infoset's items or their properties.

To facilitate queries, XPath maps the XML Infoset into an explicit tree, and introduces important notions of a location path and a current, context node. A location path denotes a selection of a set of nodes relative to a context node. Any XPath tree has a distinguished, root node -- which serves as the context node for absolute location paths. Location path is recursively defined as a location step joined with a location path. A location step is a simple query of the database relative to a context node. A step may include expressions that further filter the selected set. Each node in the resulting set is used as a context node for the adjoining location path. The result of the step is a union of the sets returned by the latter location paths.

The SXML representation of the XML Infoset (see SSAX.scm) is rather suitable for querying as it is. Bowing to the XPath specification, we will refer to SXML information items as 'Nodes':

    	<Node> ::= <Element> | <attributes-coll> | <attrib>
    		   | "text string" | <PI>

This production can also be described as

    	<Node> ::= (name . <Nodelist>) | "text string"

An (ordered) set of nodes is just a list of the constituent nodes:

    	<Nodelist> ::= (<Node> ...)

Nodelists, and Nodes other than text strings are both lists. A <Nodelist> however is either an empty list, or a list whose head is not a symbol. A symbol at the head of a node is either an XML name (in which case it's a tag of an XML element), or an administrative name such as '@'. This uniform list representation makes processing rather simple and elegant, while avoiding confusion. The multi-branch tree structure formed by the mutually-recursive datatypes <Node> and <Nodelist> lends itself well to processing by functional languages.

A location path is in fact a composite query over an XPath tree or its branch. A singe step is a combination of a projection, selection or a transitive closure. Multiple steps are combined via join and union operations. This insight allows us to elegantly implement XPath as a sequence of projection and filtering primitives -- converters -- joined by combinators. Each converter takes a node and returns a nodelist which is the result of the corresponding query relative to that node. A converter can also be called on a set of nodes. In that case it returns a union of the corresponding queries over each node in the set. The union is easily implemented as a list append operation as all nodes in a SXML tree are considered distinct, by XPath conventions. We also preserve the order of the members in the union. Query combinators are high-order functions: they take converter(s) (which is a Node|Nodelist -> Nodelist function) and compose or otherwise combine them. We will be concerned with only relative location paths [XPath]: an absolute location path is a relative path applied to the root node.

Similarly to XPath, SXPath defines full and abbreviated notations for location paths. In both cases, the abbreviated notation can be mechanically expanded into the full form by simple rewriting rules. In case of SXPath the corresponding rules are given as comments to a sxpath function, below. The regression test suite at the end of this file shows a representative sample of SXPaths in both notations, juxtaposed with the corresponding XPath expressions. Most of the samples are borrowed literally from the XPath specification, while the others are adjusted for our running example, tree1.

### Basic converters and applicators

A converter is a function

    	type Converter = Node|Nodelist -> Nodelist

A converter can also play a role of a predicate: in that case, if a converter, applied to a node or a nodelist, yields a non-empty nodelist, the converter-predicate is deemed satisfied. Throughout this file a nil nodelist is equivalent to #f in denoting a failure.

Function nodeset? x

Returns #t if given object is a nodelist

Function as-nodeset x

If x is a nodelist - returns it as is, otherwise wrap it in a list.

Function sxml:element? x

Predicate which returns #t if <obj> is SXML element, otherwise returns #f.

Function ntype-names?? crit

The function ntype-names?? takes a list of acceptable node names as a criterion and returns a function, which, when applied to a node, will return #t if the node name is present in criterion list and #f otherwise.

    	ntype-names?? :: ListOfNames -> Node -> Boolean

Function ntype-names?? crit

The function ntype?? takes a type criterion and returns a function, which, when applied to a node, will tell if the node satisfies the test.

    	ntype?? :: Crit -> Node -> Boolean

The criterion 'crit' is one of the following symbols:

id

  tests if the Node has the right name (id)

@

  tests if the Node is an <attributes-list>

*

  tests if the Node is an <Element>

*text*

  tests if the Node is a text node

*data*

  tests if the Node is a data node (text, number, boolean, etc., but not pair)

*PI*

  tests if the Node is a PI node

*COMMENT*

  tests if the Node is a COMMENT node

*ENTITY*

  tests if the Node is a ENTITY node

*any*

  #t for any type of Node

Function ntype-namespace-id?? ns-id

This function takes a namespace-id, and returns a predicate Node -> Boolean, which is #t for nodes with this very namespace-id. ns-id is a string

`(ntype-namespace-id?? #f)` will be #t for nodes with non-qualified names.

Function sxml:complement pred

This function takes a predicate and returns it complemented That is if the given predicate yelds #f or '() the complemented one
yields the given node (#t) and vice versa.

Function node-eq? other
Function node-equal? other

Curried equivalence converter-predicates

Function mode-pos n

node-pos:: N -> Nodelist -> Nodelist, or

node-pos:: N -> Converter

Select the N'th element of a Nodelist and return as a singular Nodelist; Return an empty nodelist if the Nth element does not exist.

((node-pos 1) Nodelist) selects the node at the head of the Nodelist, if exists; ((node-pos 2) Nodelist) selects the Node after that, if exists.

N can also be a negative number: in that case the node is picked from the tail of the list.

((node-pos -1) Nodelist) selects the last node of a non-empty nodelist; ((node-pos -2) Nodelist) selects the last but one node, if exists.

Function sxml:filter pred?

filter:: Converter -> Converter

A filter applicator, which introduces a filtering context. The argument converter is considered a predicate, with either #f or nil result meaning failure.

Function take-until pred?

take-until:: Converter -> Converter, or

take-until:: Pred -> Node|Nodelist -> Nodelist

Given a converter-predicate and a nodelist, apply the predicate to each element of the nodelist, until the predicate yields anything but #f or nil. Return the elements of the input nodelist that have been processed till that moment (that is, which fail the predicate).

take-until is a variation of the filter above: take-until passes elements of an ordered input set till (but not including) the first element that satisfies the predicate.

The nodelist returned by ((take-until (not pred)) nset) is a subset -- to be more precise, a prefix -- of the nodelist returned by ((filter pred) nset)

Function take-after pred?

take-after:: Converter -> Converter, or

take-after:: Pred -> Node|Nodelist -> Nodelist

Given a converter-predicate and a nodelist, apply the predicate to each element of the nodelist, until the predicate yields anything but #f or nil. Return the elements of the input nodelist that have not been processed: that is, return the elements of the input nodelist that follow the first element that satisfied the predicate.

take-after along with take-until partition an input nodelist into three parts: the first element that satisfies a predicate, all preceding elements and all following elements.

Function map-union proc lst

Apply proc to each element of lst and return the list of results. if proc returns a nodelist, splice it into the result

From another point of view, map-union is a function Converter->Converter, which places an argument-converter in a joining context.

Function node-reverse node-or-nodelist

node-reverse :: Converter, or

node-reverse:: Node|Nodelist -> Nodelist

Reverses the order of nodes in the nodelist This basic converter is needed to implement a reverse document order (see the XPath Recommendation).

Function node-trace title

node-trace:: String -> Converter

(node-trace title) is an identity converter. In addition it prints out a node or nodelist it is applied to, prefixed with the 'title'. This converter is very useful for debugging.

### Converter combinators

Combinators are higher-order functions that transmogrify a converter or glue a sequence of converters into a single, non-trivial converter. The goal is to arrive at converters that correspond to XPath location paths.

From a different point of view, a combinator is a fixed, named pattern of applying converters. Given below is a complete set of such patterns that together implement XPath location path specification. As it turns out, all these combinators can be built from a small number of basic blocks: regular functional composition, map-union and filter applicators, and the nodelist union.

Function select-kids test-pred?

select-kids:: Pred -> Node -> Nodelist

Given a Node, return an (ordered) subset its children that satisfy the Pred (a converter, actually)

select-kids:: Pred -> Nodelist -> Nodelist

The same as above, but select among children of all the nodes in the Nodelist

More succinctly, the signature of this function is select-kids:: Converter -> Converter

Function node-self pred?

node-self:: Pred -> Node -> Nodelist, or

node-self:: Converter -> Converter

Similar to select-kids but apply to the Node itself rather than to its children. The resulting Nodelist will contain either one component, or will be empty (if the Node failed the Pred).

Function node-join selectors ...

node-join:: [LocPath] -> Node|Nodelist -> Nodelist, or

node-join:: [Converter] -> Converter

join the sequence of location steps or paths as described in the title comments above.

Function node-reduce converters ...

node-reduce:: [LocPath] -> Node|Nodelist -> Nodelist, or

node-reduce:: [Converter] -> Converter

A regular functional composition of converters. From a different point of view,

    ((apply node-reduce converters) nodelist)

is equivalent to

    (foldl apply nodelist converters)

i.e., folding, or reducing, a list of converters with the nodelist as a seed.

Function node-or converters ...

node-or:: [Converter] -> Converter

This combinator applies all converters to a given node and produces the union of their results.

This combinator corresponds to a union, '|' operation for XPath location paths.

Function node-closure test-pred

node-closure:: Converter -> Converter

Select all descendants of a node that satisfy a converter-predicate. This combinator is similar to select-kids but applies to grand... children as well. This combinator implements the "descendant::" XPath axis Conceptually, this combinator can be expressed as

    (define (node-closure f)
         (node-or
           (select-kids f)
    	 (node-reduce (select-kids (ntype?? '*)) (node-closure f))))

This definition, as written, looks somewhat like a fixpoint, and it will run forever. It is obvious however that sooner or later (select-kids (ntype?? '*)) will return an empty nodelist. At this point further iterations will no longer affect the result and can be stopped.

### Extensions

Function sxml:node? node

According to XPath specification 2.3, this test is true for any XPath node.

For SXML auxiliary lists and lists of attributes has to be excluded.

Function sxml:attr-list obj

Returns the list of attributes for a given SXML node Empty list is returned if the given node os not an element, or if it has no list of attributes

Function sxml:attribute test-pred?

Attribute axis

Function sxml:child test-pred?

Child axis

This function is similar to 'select-kids', but it returns an empty child-list for PI, Comment and Entity nodes

Function sxml:parent test-pred?

Parent axis Given a predicate, it returns a function

RootNode -> Converter

which which yields a

node -> parent

converter then applied to a rootnode. Thus, such a converter may be constructed using

    ((sxml:parent test-pred) rootnode)

and returns a parent of a node it is applied to. If applied to a nodelist, it returns the list of parents of nodes in the nodelist. The rootnode does not have to be the root node of the whole SXML tree -- it may be a root node of a branch of interest. The parent:: axis can be used with any SXML node.

#### Popular short cuts

Function sxml:child-nodes test-pred?

    (sxml:child sxml:node?)

Function sxml:child-elements test-pred?

    (select-kids sxml:element)

### Abbreviated SXPath

Function sxpath path :optional ns-binding

Evaluate an abbreviated SXPath

    	sxpath:: AbbrPath -> Converter, or
    	sxpath:: AbbrPath -> Node|Nodeset -> Nodeset

AbbrPath is a list. It is translated to the full SXPath according to the following rewriting rules

    (sxpath '()) -> (node-join)
    (sxpath '(path-component ...)) ->
    		(node-join (sxpath1 path-component) (sxpath '(...)))
    (sxpath1 '//) -> (sxml:descendant-or-self sxml:node?)
    (sxpath1 '(equal? x)) -> (select-kids (node-equal? x))
    (sxpath1 '(eq? x))    -> (select-kids (node-eq? x))
    (sxpath1 '(*or* ...))  -> (select-kids (ntype-names??
                                             (cdr '(*or* ...))))
    (sxpath1 '(*not* ...)) -> (select-kids (sxml:complement
                                            (ntype-names??
                                             (cdr '(*not* ...)))))
    (sxpath1 '(ns-id:* x)) -> (select-kids
                                         (ntype-namespace-id?? x))
    (sxpath1 ?symbol)     -> (select-kids (ntype?? ?symbol))
    (sxpath1 ?string)     -> (txpath ?string)
    (sxpath1 procedure)   -> procedure
    (sxpath1 '(?symbol ...)) -> (sxpath1 '((?symbol) ...))
    (sxpath1 '(path reducer ...)) ->
    		(node-reduce (sxpath path) (sxpathr reducer) ...)
    (sxpathr number)      -> (node-pos number)
    (sxpathr path-filter) -> (filter (sxpath path-filter))

#### Wrappers

Function if-sxpath path

sxpath always returns a list, which is #t in Scheme if-sxpath returns #f instead of empty list

Function if-car-sxpath path

Returns first node found, if any. Otherwise returns #f.

Function car-sxpath path

Returns first node found, if any. Otherwise returns empty list.

### lookup by a value of ID type attribute

Function sxml:id-alist node paths ...

Built an index as a list of (ID_value . element) pairs for given node. lpaths are location paths for attributes of type ID.

### SXML counterparts to W3C XPath Core Functions

Function sxml:string object

The counterpart to XPath 'string' function (section 4.2 XPath Rec.) Converts a given object to a string

> NOTE:

> 1. When converting a nodeset - a document order is not preserved

> 2. number->string function returns the result in a form which is slightly

different from XPath Rec. specification

Function sxml:boolean object

The counterpart to XPath 'boolean' function (section 4.3 XPath Rec.) Converts its argument to a boolean

Function sxml:number object

The counterpart to XPath 'number' function (section 4.4 XPath Rec.) Converts its argument to a number

> NOTE:

> 1. The argument is not optional (yet?)

> 2. string->number conversion is not IEEE 754 round-to-nearest

> 3. NaN is represented as 0

Function sxml:string-value object

Returns a string value for a given node in accordance to XPath Rec. 5.1 - 5.7

Function sxml:id object

Select SXML element by its unique IDs XPath Rec. 4.1

> object - a nodeset or a datatype which can be converted to a string by means

of a 'string' function

> id-index = ( (id-value . element) (id-value . element) ... )

This index is used for selection of an element by its unique ID. The result is a nodeset

### Comparators for XPath objects

#### Equality comparison

Function sxml:equality-cmp bool-op number-op string-op

A helper for XPath equality operations: = , != 'bool-op', 'number-op' and 'string-op' are comparison operations for a pair of booleans, numbers and strings respectively

Function sxml:equal? obj1 obj2

(sxml:equality-cmp eq? = string=?)

Compares given obj1 and obj2.

Function sxml:not-equal? obj1 obj2

    (sxml:equality-cmp
       (lambda (bool1 bool2) (not (eq? bool1 bool2)))
       (lambda (num1 num2) (not (= num1 num2)))
       (lambda (str1 str2) (not (string=? str1 str2))))

Counterparts of `sxml:equal?`.

#### Relational comparison

Function sxml:relational-cmp op

Relational operation ( < , > , <= , >= ) for two XPath objects op is comparison procedure: < , > , <= or >=

### XPath axes. An order in resulting nodeset is preserved

Function sxml:ancestor test-pred?

Ancestor axis

Function sxml:ancestor-or-self test-pred?

Ancestor-or-self axis

Function sxml:descendant test-pred?

Descendant axis

It's similar to original 'node-closure' a resulting nodeset is in depth-first order rather than breadth-first Fix: din't descend in non-element nodes!

Function sxml:descendant-or-self test-pred?

Descendant-or-self axis

Function sxml:following test-pred?

Following axis

Function sxml:following-sibling test-pred?

Following-sibling axis

Function sxml:namespace test-pred?

Namespace axis

Function sxml:preceding test-pred?

Preceding axis

Function sxml:preceding-sibling test-pred?

Preceding-sibling axis

## (packrat) -- Packrat parser library

Library (packrat)

This library is ported from Chicken Scheme packrat. The documentation is from the PDF file located on the website and formatted Sagittarius document format.

Packrat parsing is a memorizing, backtracking recursive-descent parsing technique that runs in time and space linear in the size of the input test. The technique was originally discovered by Alexander Birman in 1970 [1], and Bryan Ford took up the idea for his master's thesis in 2002 [4, 3, 2]. For detailed information on the technique, please see Bryan Ford's web pate at

"http://pdos.csail.mit.edu/~baford/packrat/"This document describes an R5RS Scheme library of parsing combinators implemented using the packrat parsing algorithm. The main interfaces are the `packrat-parse` macro and the combinators into into which it expands, the `base-generator->results` function, and the accessors for `parse-result` records.

### Data Structures

This section describes the data structures that make up the core of the packrat parsing algorithm, and some of the low-level procedures that operate on them.

#### parse-result

A parse-result record describes the results of an attempt at a parse at a particular position in the input stream. It can either record a successful parse, in which case it contains an associated semantic-value, or a failed parse, in which case it contains a parse-error structure.

Function parse-result? object

This is a predicate which answers #t if and only if its argument is a parse-result record.

Function parse-result-successful? parse-result

This predicate returns #t if its argument represents a successful parse, or #f if it represents a failed parse.

Function parse-result-semantic-value parse-result

If the argument represents a successful parse, this function returns the associated semantic-value; otherwise, it will return #f.

Function parse-result-next parse-result

If the argument represents a successful parse, this function returns a parse-results record representing the parsed input stream starting immediately after the parse this parse-results represents. For instance, given an input stream [a, b, c, d, e], if the parse-result given to `parse-result-next`had completed successfully, consuming the [a, b, c] prefix of the input stream and producing some semantic value, then the parse-result returned from `parse-result-next` would represent all possible parses starting from the [d, e] suffix of the input stream.

Function parse-result-error parse-result

If the argument represents a failed parse, this function returns a parse-error structure; otherwise, it may return a parse-error structure for internal implementation reasons (to do with propagating errors upwards for improved error-reporting), or it may return #f

Function make-result semantic-value next-parse-results

This function constructs an instance of parse-result representing a successful parse. The first argument is used as the semantic value to include with the new parse-result, and the second argument should be a parse-results structure representing the location in the input stream from which continue parsing.

Function make-expected-result parse-position object

This function constructs an instance of parse-result representing a failed parse. The parse-position in the first argument and the value in the second argument are used to construct a variant of a parse-error record for inclusion in the parse-result that reports that a particular kind of value was expected at the given parse-position.

Function make-message-result parse-position string

This function constructs an instance of parse-result representing a failed parse. The parse-position in the first argument and the string in the second argument are used to construct a variant of a parse-error record for inclusion in the parse-result that reports a general error message at the given parse position.

Function merge-result-errors parse-result parse-error

This function propagates error information through a particular parse result. The parse-error contained in the first argument is combined with the parse-error from the second argument, and the resulting parse-result structure is returned embedded in the error field of a copy of the first argument.

#### parse-results

A parse-results record notionally describes all possible parses that can be attempted from a particular point in an input stream, and the results of those parses. It contains a parse-position record, which corresponds to the position in the input stream that this parse-results represents, and a map associating "key objects" with instance of parse-result.

Atomic input objects (known as "base values"; usually either characters or token / semantic-value pairs) are represented specially in the parse-results data structure, as an optimisation: the two fields `base` and code{next} represent the implicit successful parse of a base value at the current position. The `base` field contains a pair of a toke-class-identifier and a semantic value unless the parse-results data structure as a whole is representing the of the input stream, in which case it will contain #f.

Function parse-results? object

This is a predicate which answer #t if and only if its argument is a parse-results record.

Function parse-results-position parse-results

Returns the parse-position corresponding to the argument. An unknown position is represented by #f.

Function parse-results-base parse-results

If the argument corresponds to the end of the input stream, this function returns #f; otherwise, it returns a pair, where the car is to be interpreted as a base lexical token class identifier (for instance, "symbol", "string", "number") and the cdr is to be interpreted as the semantic value of the data.

Function parse-results-token-kind parse-results

This function returns the car (the token class identifier) of the result of `parse-results-base`, if that result is a pair; otherwise it returns #f.

Function parse-results-token-kind parse-results

This function returns the car (the token class identifier) of the result of `parse-results-base`, if that result is a pair; otherwise it returns #f.

Function parse-results-token-value parse-results

This function returns the cdr (the token value) of the result of `parse-results-base`, if that result is a pair; otherwise it returns #f.

Function parse-results-next parse-results

This function returns the parse-results record representing the position in the input stream immediately after the argument's base token. For instance, if the base tokens used represented characters, then this function would return the parse-results representing the next character position; or, if the base tokens represented lexemes, then this function would return a representation of the results obtainable starting from the next lexeme position. The value #f is returned if there is no next position (that is, if the argument represents the final possible position before the end-of-stream).

Function base-generator->results generator-function

This function is used to set up an initial input stream of base tokens. The argument is to be nullary function returning multiple-values, the first of which is to be a parse-position record or #f, and the second of which is to be a base token, that is a pair of a token class identifier and a semantic value. The argument is called every time the parser needs to read a fresh base token from the input stream.

Function prepend-base parse-position base-value parse-results

This function effectively prepends a base token to particular parse-results. This can be useful when implementing extensible parsers: using this function in a suitable loop, it is possible to splice together two streams of input.

For instance, if `r` is a parse-results representing parse over the input token stream `'((b . 2) (c . 3))`, then the result of the call

    (prepend-base #f '(a . 1) r)

is a new parse-results representing parse over the input stream `'((a . 1) (b . 2) (c . 3))`.

The first argument to prepend-base, the parse-position, should be either a parse-position representing the location the base token being prepended, or #f if the input position of the base token is unknown.

Function prepend-semantic-value parse-position key-object semantic-value parse-results

This function is similar to prepend-base, but prepends an already-computed semantic value to a parse-results, again primarily for use in implementing extensible parsers. The resulting parse-results is assigned the given parse-position, and has an entry in its result map associating the given key-object with the given semantic-value and input parse-results.

Function results->result parse-results key-object result-thunk

This function is the central function that drives the parsing process. It examines the result in the parse-results given to it, searching for an entry matching the given key-object. If such an entry is found, the parse-result structure associated with the key is returned; otherwise, the nullary result-thunk is called, and the resulting parse-result is both stored into the result map and returned to the caller of `results->result`.

#### parse-error

Parse-error structure represent collected error information from attempted parses. They contain two kinds of error report, following [3]: a collection of "expected token" messages, and a collection of free-format message strings.

Function parse-error? object

This is a predicate which answers #t if and only if its argument is a parse-error record.

Function parse-error-position parse-error

Retrieves the parse-position in the input stream that this parse-error is describing. A #f result indicates an unknown position.

Function parse-error-expected parse-error

Retrieves the set (represented as a list) of token class identifiers that could have allowed the parse to continue from this point.

Function parse-error-message parse-error

Retrieves the list of error messages associated with this parser-error.

Function make-error-expected object

Constructs an "expected token" parse-error record from its arguments. Called by `make-expected-result`.

Function make-error-message string

Constructs an "general error message" parse-error record from its arguments. Called by `make-message-result`.

Function parse-error-empty parse-error

Returns #f if its argument contains no expected tokens, and no general error messages; otherwise returns #f. Used internally by `merge-result-errors`.

Function merge-result-errors parse-error parse-error

Merges two parse-error records, following [3]. If one record represents a position earlier in the input stream than the other, then that record is returned; if they both represent the same position, the "expected token" sets are unioned and the general message lists are appended to form a new parse-error record at the same position. The standard parsing combinators call this function as appropriate to propagate error information through the parse.

#### parse-position

A parse-position record represents a character location in an input stream.

Function make-parse-position filename linenumber columnnumber

Constructs a parse-position record from its arguments. The given filename may be #f if the filename is unknown or not appropriate for the input stream the parse-position is indexing into.

Function parse-position? object

This is a predicate which answer #t if any only if its argument is parse-position record.

Function parse-position-file parse-position

Retrieves the file name associated with a parse-position record. Returns #f if the filename is absent or not appropriate for this input stream.

Function parse-position-line parse-position

Retrieves the line number this parse-position represents. Line numbers begin at 1; that is all characters on the very first line in a file will have line number 1.

Function parse-position-column parse-position

Retrieves the column number within a line that parse-position represents. Column numbers begin at 0; that is, the very first character of the very first line in a file will have line number 1 and column number 0.

Function top-parse-position string

Constructs a parse-position representing the very beginning of an input stream. The argument is passed into `make-parse-position` as the "filename" parameter, and so may be either a string or #f.

Function update-parse-position parse-position character

Given a position, and the character occurring at that position, returns the position of the next character in the input stream. Most characters simply increment the column number. Exceptions to this rule are: `#\return`, which resets the column number to zero; `#\newline`, which both resets the column number to zero and increments the line number; and `#\tab`, which increments the column number to the nearest multiple of eight, just as terminal with an eight-column tab stop setting might do.

Function parse-position->string parse-position

Converts a parse-position record into an emacs-compatible display format. If the filename in the parse-position is unknown, the string "<??>" is used in its place. The result is of the form

    filename:linenumber:columnnumber

for example,

    main.c:33:7

Function parse-position>? parse-position parse-position

Returns #t if the first parse-position is more than advanced in the input stream than the second parse-position. Either or both positions may be #f, representing unknown positions; an unknown position is considered to be less advanced in the input stream than any known position. Note that the filename associated with each parse-position is completely ignored. It is the caller's responsibility to ensure the two positions are associated with the same input stream.

### Parsing Combinators

Parsing combinators are functions taking a parse-results structure and retruning a parse-result structure. Each combinator attempts to parse the input stream in some manner, and the result of the combinator is either a successful parse with an associated semantic value, or a failed parse with an associated error record.

This section describes the procedures that produce the mid-level parsing combinators provided as part of the library.

The type of a parser combinator, written in ML-like notation, would be

    parse-results -> parse-result

Function packrat-check-base kind-object semantic-value-acceptor

Returns a combinator which, if the next base token has token class identifier equal to the first argument ("kind-object"), calls the second argument ("semantic-value-acceptor") with the semantic value of the next base token. The result of this cal should be another parser combinator, which is applied to the parse-results representing the remainder of the input stream.

The type of the semantic value acceptor, written in ML-like notation, would be

    semanticValue -> parserCombinator

or more fully expanded,

    semanticValue -> parse-results -> parse-result

These types recall the types of functions that work with monads.

Function packrat-check combinator semantic-value-acceptor

Returns a combinator which attempts to parse using the first argument, and if the parse is successful, hands the resulting semantic value to the semantic-value-acceptor (which has the same type as the semantic-value-acceptor passed to `packrat-check-base` ) and continues parsing using the resulting combinator.

Function packrat-or combinator combinator

Returns a combinator which attempts to parse using the first argument, only trying the second argument if the first argument fails to parse the input. This is the basic combinator used to implement a choice among several alternative means of parsing an input stream.

Function packrat-unless string combinator combinator

The combinator returned from this function first tries the first combinator given. If it fails, the second is tried; otherwise, an error message containing the given string is returned as the result. This can be used to assert that a particular sequence of tokens does not occur at the current position before continuing on. (This is the "not-followed-by" matcher).

### The parckrat-parser macro

Macro packrat-parser result-expr nonterminal-definition ...

The `packrat-parse` macro provides syntactic sugar for building complex parser combinators from simpler combinators. The general form of the macro, in an EBNF-like language, is:

    (packrat-parser <result-expr> <nonterminal-definition>*)

where

    <nonterminal-definition> :==
      (<nonterminal-id> (<sequence> <body-expr>+)*)
    <sequence> :== (<part>*)
    <part> :== (! <part>*)
           |   (/ <sequence>*)
           |   <var> <- '<kind-object>
           |   <var> <-

           |   <var> <- <nonterminal-id>
           |   '<kind-object>
           |   <nonterminal-id>

Each nonterminal-definition expands into a parser-combinator. The collection of defined nonterminal parser-combinators expands to a `(begin)` containing an internal definition for each nonterminal.

The result of the whole `packrat-parser` form is the `<result-expr>`immediately following the `packrat-parser` keyword. Since `(begin)`within `(begin)` forms are flattened out in Scheme, the `<result-expr>` can be used to introduce handwritten parser combinators which can call, and can be called by, the nonterminal definitions built in the rest of the parser definition.

Each nonterminal definition expands into:

    (define (<nonterminal-id> results)
      (results->result results 'nonterminal-id
        (lambda ()
          (<...> results))))

where `<...>` is the expanded definition-of-sequences combinator formed form the body of the nonterminal definition.

An alternation (either implicit in the main body of a nonterminal definition, or introduced via a `<part>` of the form `(/ <sequence> ...)`) expands to

`(packrat-or <expansion-of-first-alternative> (packrat-or <expansion-of-second-alternative> ...))` This causes each alternative to be tried in turn, in left-to-right order of occurrence.

Wherever a `<part>` of the form `"<var> <- ..."` occurs, a variable binding for `<var>` is made available in the `<body-expr>`s that make up each arm of a nonterminal definition. The variable will be bound to the semantic value resulting form parsing according to the parser definition to the right of the arrow (the `"..."` above).

The `(! <part> ...)` syntax expands into an invocation of `packrat-unless`.

The `"@"` syntax in `"<var> <- @"` causes `<var>`to be bound to the parse-position at that point in the input stream. This can be used for annotating abstract syntax trees with location information.

`<part>`s of the form `'<kind-object>` expand into invocations of `packrat-check-base`; those of the form `<nonterminal-id>` expand into invocations of `packrat-check`, with the procedure associated with the named nonterminal passed in as the combinator argument.

### References

[1] Alexander Birman and Jeffrey D. Ullman. Parsing algorithms with backtrack. Information and Control, 23(1):1 34, August 1973

[2] Bryan Ford. Parsing expression grammars: A recognition-based syntactic foundation.

[3] Bryan Ford. Packrat parsing: a practical linear-time algorithm with backtracking. Master's thesis. Massachusetts Institute of Technology, Sep 2002.

[4] Bryan Ford. Packrat parsing: Simple, powerful, lazy, linear time. In Proceedings of the 2002 International Conference on Functional Programming. Oct 2002.

## (json) -- JSON parser library

Library (json)

This library is compatible with Chicken Scheme json module and provides JSON reader and writer. The library is a thin wrapper of (text json) library.

Function json-read :optional (port (current-input-port))

Reads JSON from given port and returns representing S-expression.

Conversion rules:

    JSON array   <-> list
    JSON table   <-> vector
    JSON boolean <-> boolean
    JSON null    <-> symbol `null`

Read and write procedure always use above conversion rules even if `*json-map-type*` is set to `'alist`.

Function json-write json :optional (port (current-output-port))

Writes the given S-expression JSON representing object to given port.

# Supporting SRFIs

SRFI is a great libraries, so there is no reason not to support. Without exception Sagittarius also supports several SRFIs. The following list is the supported SRFI. Documents are not written for now. So if you need to refer the functions, please look for SRFI's site. I might write it later.

For now, I just put pointer to the SRFI's web site

SRFI number | Library name
--- | ---
SRFI-0 | (srfi :0 cond-expand)
SRFI-1 | (srfi :1 lists)
SRFI-2 | (srfi :2 and-let*)
SRFI-4 | (srfi :4 numeric-vectors) SRFI-4
SRFI-6 | (srfi :6 basic-string-ports)
SRFI-8 | (srfi :8 receive)
SRFI-11 | (srfi :11 let-values)
SRFI-13 | (srfi :13 strings)
SRFI-14 | (srfi :14 char-set)
SRFI-16 | (srfi :16 case-lambda)
SRFI-17 | (srfi :17 generalized-set!)
SRFI-18 | (srfi :18 multithreading)
SRFI-19 | (srfi :19 time)
SRFI-22 | This SRFI does not provide any library.
SRFI-23 | (srfi :23 error)
SRFI-25 | (srfi :25 multi-dimensional-arrays)
SRFI-26 | (srfi :26 cut)
SRFI-27 | (srfi :27 random-bits)
SRFI-29 | (srfi :27 localization)
SRFI-31 | (srfi :31 rec)
SRFI-37 | (srfi :37 args-fold)
SRFI-38 | (srfi :38 with-shared-structure)
SRFI-39 | (srfi :39 parameters)
SRFI-41 | (srfi :41 streams)
SRFI-42 | (srfi :42 eager-comprehensions)
SRFI-43 | (srfi :43 vectors)
SRFI-45 | (srfi :45 lazy)
SRFI-49 | (srfi :49)
SRFI-57 | (srfi :57 records)
SRFI-60 | (srfi :60 integer-bits)
SRFI-61 | (srfi :61 cond) builtin
SRFI-64 | (srfi :64 testing)
SRFI-69 | (srfi :69 basic-hash-tables)
SRFI-78 | (srfi :78 lightweight-testing)
SRFI-86 | (srfi :86 mu-and-nu)
SRFI-87 | (srfi :87 case)
SRFI-98 | (srfi :98 os-environment-variables)
SRFI-99 | (srfi :99 records)
SRFI-100 | (srfi :100 define-lambda-object) longname
SRFI-101 | (srfi :101 random-access-lists)
SRFI-105 | (srfi :105) SRFI-105
SRFI-106 | (srfi :106 socket)
SRFI-110 | (srfi :110) SRFI-110
SRFI-111 | (srfi :111 boxes) longname
SRFI-112 | (srfi :112 inquery) longname
SRFI-113 | (srfi :113 sets) longname
SRFI-114 | (srfi :114 comparators) longname
SRFI-115 | (srfi :115 regex) longname
SRFI-116 | (srfi :116 ilists) longname
SRFI-117 | (srfi :117 list-queues) longname
SRFI-120 | (srfi :120 timer) longname
SRFI-121 | (srfi :121 generators) longname
SRFI-123 | (srfi :123 generic-ref)
SRFI-124 | (srfi :124 ephemerons) longname
SRFI-125 | (srfi :125 hashtables) longname
SRFI-126 | (srfi :126 r6rs-hashtables) longname
SRFI-127 | (srfi :127 lazy-sequences) longname
SRFI-128 | (srfi :128 comparators) longname
SRFI-129 | (srfi :129 titlecase) longname
SRFI-130 | (srfi :130 string-cursors) longname
SRFI-131 | (srfi :131 records) longname
SRFI-132 | (srfi :132 sorting) longname
SRFI-133 | (srfi :133 vectors) longname
SRFI-134 | (srfi :134 ideque) longname
SRFI-135 | (srfi :135 texts) longname
SRFI-139 | (srfi :139 syntax-parameters) longname
SRFI-141 | (srfi :141 integer-division) longname
SRFI-142 | (srfi :142 bitwise) longname
SRFI-143 | (srfi :143 fixnums) longname
SRFI-144 | (srfi :144 flonums) longname
SRFI-145 | (srfi :145 assumptions) longname
SRFI-146 | (srfi :146 mapping) longname and (srfi :146 hash)
SRFI-151 | (srfi :151 bitwise-operations) longname
SRFI-152 | (srfi :152 strings)
SRFI-154 | (srfi :154 dynamic-extents) longname
SRFI-156 | (srfi :156 predicate-combiners) longname
SRFI-158 | (srfi :158 generators-and-accumulators) longname
SRFI-159 | (srfi :159)
SRFI-160 | (srfi :160) SRFI-160
SRFI-193 | (srfi :193 command-line) longname
SRFI-195 | (srfi :195 boxes) longname
SRFI-197 | (srfi :197 pipeline) longname
SRFI-210 | (srfi :210 multiple-values) longname
SRFI-219 | (srfi :219 define)[^longname] builtin
SRFI-230 | (srfi :230 atomic)

SRFI-4

This SRFI also contains reader macro described below this section.

SRFI-49

The library exports `srfi-49-read`, `srfi-49-load` procedures. And also be able to replace reader, For more detail, see (sagittarius reader) - reader macro library.

builtin

The syntax provided by this SRFI is supported by the builtin syntax. This SRFI can be used for portability.

longname

The long name is Sagittarius specific and the specified library name is `(srfi :_number_)`. So for the portability it's better to use the specified one. The long name is taken from the SRFI name.

SRFI-105

The library exports `curly-infix-read` and `neoteric-read` procedures. These procedures read SRFI-105 the infix style code that SRFI-105 specifying. And this also exports reader macros, you can activate it with `#!read-macro=srfi/:105` or `#!read-macro=curly-infix`.
Even though the specification said it MUST support `#!curly-infix`, however the library just ignore and not activate the reader macros. So you need to explicitly write the one mentioned above. To keep your code portable between implementations that support this SRFI, you need to write both style as following;

    ;; write both
    #!read-macro=curly-infix
    #!curly-infix

The order doesn't matter, Sagittarius just ignores the latter style.

SRFI-110

The library exports a replacible reader. To use it write following hash-bang directives.

    ;; write both for compatibility
    #!reader=sweet
    #!sweet

The order doesn't matter, Sagittarius just ignores the latter style.

SRFI-152

This library doesn't extend comparisons, thus it behaves as the SRFI specifies. (e.g. Passing 0 or 1 argument to `string=?` raises an error)

SRFI-160

The short name is Sagittarius specific which provides all the bindings from the below libraries which are specified in the SRFI:

- `(srfi :160 base)`

- `(srfi :160 u8)`

- `(srfi :160 s8)`

- `(srfi :160 u16)`

- `(srfi :160 s16)`

- `(srfi :160 u32)`

- `(srfi :160 s32)`

- `(srfi :160 u64)`

- `(srfi :160 s64)`

- `(srfi :160 f32)`

- `(srfi :160 f64)`

- `(srfi :160 c64)`

- `(srfi :160 c128)`

Each library can be imported like this:

    (import (srfi :1))

So you don't have to type the long name.

All libraries have R7RS style library name as well. So SRFI-1 can be imported like this:

    (import (srfi 1))

## Reader macros for SRFIs

### SRFI-4

The SRFI-4 also defines its reader macro. Sagittarius also suppots these. It defines tagged vector and the tags can be `s8`, `u8`, `s16`, `u16`, `s32`, `u32`, `s64`, `u64`, `f32` or `f64`. For each value of tags, the external representation of instances of the vector is `#_tag_(... elements ...)`On Sagittarius, these reader macros are not automatically enabled. You need to explicitly import it. For more detail, see (sagittarius reader) - reader macro library.

# Index

# $ & ( * + - / < = > ? @ ^ _ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

##### #

#/-reader | User level APIs for regular expression
#?= | (sagittarius debug) - Debugging support

##### $

$any | Predefined parsers
$bind | Predefined parsers
$char-set-contains? | Character specific parsers
$cond | Predefined parsers
$cond | Predefined parsers
$do | Predefined parsers
$empty | Predefined parsers
$eof | Predefined parsers
$eqv? | Predefined parsers
$expect | Predefined parsers
$fail | Predefined parsers
$guard | Predefined parsers
$if | Predefined parsers
$lazy | Predefined parsers
$many | Predefined parsers
$many | Predefined parsers
$many | Predefined parsers
$not | Predefined parsers
$optional | Predefined parsers
$optional | Predefined parsers
$or | Predefined parsers
$parameterize | Predefined parsers
$peek | Predefined parsers
$repeat | Predefined parsers
$return | Predefined parsers
$return | Predefined parsers
$return | Predefined parsers
$satisfy | Predefined parsers
$satisfy | Predefined parsers
$seq | Predefined parsers
$token | Character specific parsers
$unless | Predefined parsers
$when | Predefined parsers

##### &

&assertion | Standard condition types
&crypto-error | Cryptographic conditions
&dbi-driver-not-exist | Conditions
&dbi-error | Conditions
&dbi-sql-error | Conditions
&dbi-unsupported | Conditions
&decode-error | Cryptographic conditions
&decrypt-error | Cryptographic conditions
&encode-error | Cryptographic conditions
&encrypt-error | Cryptographic conditions
&error | Standard condition types
&future-terminated | Future
&host-not-found | Socket conditions
&http-error | (rfc http) - HTTP client
&i/o | I/O condition types
&i/o-decoding | Transcoders
&i/o-encoding | Transcoders
&i/o-file-already-exists | I/O condition types
&i/o-file-does-not-exist | I/O condition types
&i/o-file-is-read-only | I/O condition types
&i/o-file-protection | I/O condition types
&i/o-filename | I/O condition types
&i/o-invalid-position | I/O condition types
&i/o-port | I/O condition types
&i/o-read | I/O condition types
&i/o-write | I/O condition types
&implementation-restriction | Standard condition types
&integrity-error | Cryptographic conditions
&invalid-pem-format | Conditions
&irritants | Standard condition types
&lexical | Standard condition types
&message | Standard condition types
&no-infinities | Flonums
&no-nans | Flonums
&non-continuable | Standard condition types
&pem-error | Conditions
&pre-allocated-buffer-overflow | Conditions
&pre-eb-as-boundary | Conditions
&rejected-execution-error | Thread pool executor
&serious | Standard condition types
&socket | Socket conditions
&socket-closed | Socket conditions
&socket-connection | Socket conditions
&socket-port | Socket conditions
&socket-read-timeout | Socket conditions
&syntax | Standard condition types
&undefined | Standard condition types
&violation | Standard condition types
&warning | Standard condition types
&who | Standard condition types
&zlib-error | (rfc zlib) - zlib compression library

##### (

(archive interface) | Implementing archive implementation library
(asn.1) | (asn.1) - Abstract Syntas Notation One library
(binary data) | (binary io) - Binary I/O utilities
(binary data) | (binary data) - Binary data read/write
(binary pack) | (binary pack) - Packing binary data
(clos core) | (clos core) - CLOS core library
(clos user) | (clos user) -CLOS user APIs
(crypto) | (crypto) - Cryptographic library
(dbd odbc) | (dbd odbc) - DBD for ODBC
(dbi) | (dbi) - Database independent access layer
(dbm) | (dbm) - Generic DBM interface
(getopt) | (getopt) - Parsing command-line options
(json) | (json) -- JSON parser library
(match) | (match) -- Pattern matching
(math hash) | Hash operations
(math helper) | Misc arithmetic operations
(math prime) | Prime number operations
(math random) | Random number operations
(math) | (math) - Mathematics library
(net http) | (net http) - Async HTTP client
(net http-client) | (net http-client) - Modern HTTP client
(net mq amqp) | (net mq amqp) - AMQP library
(net mq mqtt broker) | MQTT broker
(net mq mqtt) | (net mq mqtt) - MQTT library
(net oauth) | (net oauth) - OAuth library
(net server) | (net server) - Simple server framework
(net socket) | (net socket) - Modern Socket library
(odbc) | (odbc) - ODBC binding
(packrat) | (packrat) -- Packrat parser library
(peg chars) | Character specific parsers
(peg) | (peg) - PEG library
(record builder) | (record builder) - Record builder
(rfc :5322) | (rfc :5322) - Internet message format library
(rfc base32) | (rfc base32) - Base 32 encode and decode library
(rfc base64) | (rfc base64) - Base 64 encode and decode library
(rfc cmac) | (rfc cmac) - CMAC library
(rfc hmac) | (rfc hmac) - HMAC library
(rfc hotp) | (rfc hotp) - HMAC-based One-Time Password library
(rfc http) | (rfc http-connections) - HTTP client utilities
(rfc http) | (rfc http) - HTTP client
(rfc http2) | (rfc http2) - HTTP/2 client
(rfc json-pointer) | (rfc json-pointer) - JSON Pointer
(rfc jwe) | (rfc jwe) - Json Web Encryption
(rfc jwk) | (rfc jwk) - Json Web Key
(rfc jws) | (rfc jws) - Json Web Signature
(rfc jwt) | (rfc jwt) - Json Web Token
(rfc pem) | (rfc pem) - PEM format library
(rfc quoted-printable) | (rfc quoted-printable) - Base 64 encode and decode library
(rfc smtp) | (rfc smtp) - SMTP client
(rfc tls) | (rfc tls) - TLS protocol library
(rfc totp) | (rfc totp) - Time-based One-Time Password library
(rfc uri) | (rfc uri) - Parse and construct URIs
(rfc uri-template) | (rfc uri-template) - URI template
(rfc uuid) | (rfc uuid) - UUID generate library
(rfc websocket) | (rfc websocket) - WebSocket
(rfc x.509) | (rfc x.509) - X.509 certificate utility library
(rfc zlib) | (rfc zlib) - zlib compression library
(rnrs (6)) | Top library
(rnrs arithmetic bitwise (6)) | Exact bitwise arithmetic
(rnrs arithmetic fixnums (6)) | Fixnums
(rnrs arithmetic flonums (6)) | Flonums
(rnrs base (6)) | Base Library
(rnrs bytevectors (6)) | Bytevectors
(rnrs conditions (6)) | Conditions
(rnrs control (6)) | Control structures
(rnrs enums (6)) | Enumerations
(rnrs eval (6)) | eval
(rnrs exceptions (6)) | Exceptions
(rnrs files (6)) | File system
(rnrs hashtable (6)) | Hashtables
(rnrs io ports (6)) | Port I/O
(rnrs io simple (6)) | Simple I/O
(rnrs lists (6)) | List utilities
(rnrs mutable-pairs (6)) | Mutable pairs
(rnrs mutable-stringss (6)) | Mutable strings
(rnrs programs (6)) | Command-line access and exit values
(rnrs r5rs (6)) | R5RS compatibility
(rnrs records procedural (6)) | Records procedural layer
(rnrs records syntactic (6)) | Records inspection
(rnrs records syntactic (6)) | Records syntactic layer
(rnrs sorting (6)) | Sorting
(rnrs syntax-case (6)) | Syntax-case
(rnrs unicode (6)) | Unicode
(rpc json) | (rpc json) - JSON RPC library
(rpc message) | Message framework
(rpc transport http) | Http transport
(rsa pkcs :5) | (rsa pkcs :5) - Password Based Cryptography library
(sagittarius atomic) | (sagittarius atomic) - Atomic operation
(sagittarius control) | (sagittarius control) - control library
(sagittarius crypto ciphers) | Cipher library - (sagittarius crypto ciphers)
(sagittarius crypto digests) | Digest library - (sagittarius crypto digests)
(sagittarius crypto kdfs) | KDF library - (sagittarius crypto kdfs)
(sagittarius crypto keys) | Key library - (sagittarius crypto keys)
(sagittarius crypto keystores) | Keystore library - (sagittarius crypto keystores)
(sagittarius crypto mac) | MAC library - (sagittarius crypto mac)
(sagittarius crypto random) | Random library - (sagittarius crypto random)
(sagittarius crypto signatures) | Signature library - (sagittarius crypto signatures)
(sagittarius crypto x509) | X.509 library - (sagittarius crypto x509)
(sagittarius debug) | (sagittarius debug) - Debugging support
(sagittarius ffi) | (sagittarius ffi) - Foreign Function Interface
(sagittarius filewatch) | (sagittarius filewatch) - Monitoring filesystem
(sagittarius generators) | (sagittarius generators) - Generators
(sagittarius io) | (sagittarius io) - Extra IO library
(sagittarius mop allocation) | (sagittarius mop allocation)
(sagittarius mop eql) | (sagittarius mop eql)
(sagittarius mop validator) | (sagittarius mop validator)
(sagittarius object) | (sagittarius object) - Convenient refs and coercion procedures
(sagittarius process) | (sagittarius process) - Process library
(sagittarius reader) | (sagittarius reader) - reader macro library
(sagittarius record) | (sagittarius record) - Extra record inspection library
(sagittarius regex) | (sagittarius regex) - regular expression library
(sagittarius socket) | (sagittarius socket) - socket library
(sagittarius threads) | (sagittarius threads) - Thread
(sagittarius timezone) | (sagittarius timezone) - Timezone
(sagittarius) | (sagittarius) - builtin library
(scheme base) | Base library
(scheme bitwise) | Bitwise library
(scheme box) | Box library
(scheme bytevector) | Bytevector library
(scheme case-lambda) | Case-lambda library
(scheme char) | Char library
(scheme charset) | Character set library
(scheme comparator) | Comparator library
(scheme complex) | Complex library
(scheme cxr) | CxR library
(scheme division) | Division library
(scheme ephemeron) | Ephemeron library
(scheme eval) | Eval library
(scheme file) | File library
(scheme fixnum) | Fixnum library
(scheme flonum) | Flonum library
(scheme format) | Format library
(scheme generator) | Generator library
(scheme hash-table) | Hashtable library
(scheme ideque) | Immutable deque library
(scheme ilist) | Immutable list library
(scheme inexact) | Inexact library
(scheme lazy) | Lazy library
(scheme lazy-seq) | Lazy sequence library
(scheme list queue) | List queue library
(scheme list) | List library
(scheme load) | Load library
(scheme mapping hash) | Hash mapping library
(scheme mapping) | Mapping library
(scheme process-context) | Process-Context library
(scheme r5rs) | R5RS library
(scheme read) | Read library
(scheme repl) | Repl library
(scheme rlist) | Random access list library
(scheme set) | Set library
(scheme sort) | Sorting library
(scheme stream) | Stream library
(scheme text) | Immutable text library
(scheme time) | Time library
(scheme vector | Homogeneous vector library per types
(scheme vector base) | Homogeneous vector library base
(scheme vector) | Vector library
(scheme write) | Write library
(security keystore) | (security keystore) - Generic Keystore Access
(security password) | (security password) - Password policy
(setter ref) | (sagittarius object) - Convenient refs and coercion procedures
(text csv) | (text csv) - Comma separated values parser library
(text html-lite) | (text html-lite) - Simple HTML document builder library
(text json jmespath) | (text json jmespath) - JMESPath
(text json mutable) | (text json mutable) - Mutable JSON
(text json object-builder) | (text json object-builder) -- JSON object builder/serializer
(text json pointer) | (text json patch) - JSON Patch
(text json pointer) | (text json pointer) - JSON Pointer
(text json schema) | (text json schema) - JSON Schema
(text json validator) | (text json validator) - JSON validator
(text json) | (text json) -- JSON parser
(text markdown parser) | Markdown extensions
(text markdown) | (text markdown) -- Markdown parser and converter
(text parse) | (text parse) - Parsing input stream
(text sxml html-parser) | (text sxml html-parser) - Flxible HTML parser
(text sxml object-builder) | (text sxml object-builder) - SXML to Scheme object builder
(text sxml ssax) | (text sxml ssax) - Functional XML parser
(text sxml sxpath) | (text sxml sxpath) - Functional XML parser
(text tree) | (text tree) - Lightweight text generation
(text yaml) | (text yaml) -- YAML parser
(thread-pool-current-thread-id) | Thread pool
(time) | Debugging aid
(tlv) | (tlv) - TLV library
(util buffer) | (util buffer) - Buffer utilities
(util bytevector) | (util bytevector) - Bytevector utility library
(util concurrent actor) | Actor
(util concurrent atomic) | Atomic
(util concurrent completable-future) | Actor
(util concurrent executor) | Executor
(util concurrent fork-join-pool) | Thread pool
(util concurrent future) | Future
(util concurrent shared-queue) | Shared queues
(util concurrent thread-pool) | Thread pool
(util concurrent) | (util concurrent) - Concurrency utilities
(util deque) | (util deque) - Deque
(util duration) | (util duration) - Duration
(util file) | (util file) - File operation utility library
(util hashtables) | (util hashtables) - Hashtable utilities
(util heap) | (util heap) - Heap
(util list) | (util list) - Extra list utility library
(util logging) | (util logging) - Logging utilities
(util queue) | (util queue) - Queue
(util timer) | (util timer) - Timer
(util treemap) | (util treemap) - Treemap
(util vector) | (util vector) - Extra vector utility library

##### *

* | Arithmetic operations
*. | Arithmetic operations
*base32-decode-table* | Low level APIs
*base32-encode-table* | Low level APIs
*base32hex-decode-table* | Low level APIs
*base32hex-encode-table* | Low level APIs
*base64-decode-table* | Low level APIs
*base64-decode-url-table* | Low level APIs
*base64-encode-table* | Low level APIs
*base64-encode-url-table* | Low level APIs
*ctr-mode:big-endian* | Ciphers parameters
*ctr-mode:little-endian* | Ciphers parameters
*ctr-mode:rfc3686 | Ciphers parameters
*digest:blake2b-160* | Digest descriptor
*digest:blake2b-256* | Digest descriptor
*digest:blake2b-384* | Digest descriptor
*digest:blake2b-512* | Digest descriptor
*digest:blake2s-128* | Digest descriptor
*digest:blake2s-160* | Digest descriptor
*digest:blake2s-224* | Digest descriptor
*digest:blake2s-256* | Digest descriptor
*digest:cshake-128* | Digest descriptor
*digest:cshake-256* | Digest descriptor
*digest:keccak-224* | Digest descriptor
*digest:keccak-256* | Digest descriptor
*digest:keccak-384* | Digest descriptor
*digest:keccak-512* | Digest descriptor
*digest:md2* | Digest descriptor
*digest:md4* | Digest descriptor
*digest:md5* | Digest descriptor
*digest:ripemd-128* | Digest descriptor
*digest:ripemd-160* | Digest descriptor
*digest:ripemd-256* | Digest descriptor
*digest:ripemd-320* | Digest descriptor
*digest:sha-1* | Digest descriptor
*digest:sha-224* | Digest descriptor
*digest:sha-256* | Digest descriptor
*digest:sha-384* | Digest descriptor
*digest:sha-512* | Digest descriptor
*digest:sha-512/224* | Digest descriptor
*digest:sha-512/256* | Digest descriptor
*digest:sha3-224* | Digest descriptor
*digest:sha3-256* | Digest descriptor
*digest:sha3-384* | Digest descriptor
*digest:sha3-512* | Digest descriptor
*digest:shake-128* | Digest descriptor
*digest:shake-256* | Digest descriptor
*digest:tiger-192* | Digest descriptor
*digest:whirlpool* | Digest descriptor
*ec-parameter:b163* | Asymmetric key operations
*ec-parameter:b233* | Asymmetric key operations
*ec-parameter:b283* | Asymmetric key operations
*ec-parameter:b409* | Asymmetric key operations
*ec-parameter:b571* | Asymmetric key operations
*ec-parameter:brainpool-p160r1* | Asymmetric key operations
*ec-parameter:brainpool-p160t1* | Asymmetric key operations
*ec-parameter:brainpool-p192r1* | Asymmetric key operations
*ec-parameter:brainpool-p192t1* | Asymmetric key operations
*ec-parameter:brainpool-p224r1* | Asymmetric key operations
*ec-parameter:brainpool-p224t1* | Asymmetric key operations
*ec-parameter:brainpool-p256r1* | Asymmetric key operations
*ec-parameter:brainpool-p256t1* | Asymmetric key operations
*ec-parameter:brainpool-p320r1* | Asymmetric key operations
*ec-parameter:brainpool-p320t1* | Asymmetric key operations
*ec-parameter:brainpool-p384r1* | Asymmetric key operations
*ec-parameter:brainpool-p384t1* | Asymmetric key operations
*ec-parameter:brainpool-p512r1* | Asymmetric key operations
*ec-parameter:brainpool-p512t1* | Asymmetric key operations
*ec-parameter:k163* | Asymmetric key operations
*ec-parameter:k233* | Asymmetric key operations
*ec-parameter:k283* | Asymmetric key operations
*ec-parameter:k409* | Asymmetric key operations
*ec-parameter:k571* | Asymmetric key operations
*ec-parameter:p192* | Asymmetric key operations
*ec-parameter:p224* | Asymmetric key operations
*ec-parameter:p256* | Asymmetric key operations
*ec-parameter:p384* | Asymmetric key operations
*ec-parameter:p521* | Asymmetric key operations
*ec-parameter:secp160k1* | Asymmetric key operations
*ec-parameter:secp160r1* | Asymmetric key operations
*ec-parameter:secp160r2* | Asymmetric key operations
*ec-parameter:secp192k1* | Asymmetric key operations
*ec-parameter:secp192r1* | Asymmetric key operations
*ec-parameter:secp224k1* | Asymmetric key operations
*ec-parameter:secp224r1* | Asymmetric key operations
*ec-parameter:secp256k1* | Asymmetric key operations
*ec-parameter:secp256r1* | Asymmetric key operations
*ec-parameter:secp384r1* | Asymmetric key operations
*ec-parameter:secp521r1* | Asymmetric key operations
*ec-parameter:sect113r1* | Asymmetric key operations
*ec-parameter:sect163k1* | Asymmetric key operations
*ec-parameter:sect163r1* | Asymmetric key operations
*ec-parameter:sect163r2* | Asymmetric key operations
*ec-parameter:sect233k1* | Asymmetric key operations
*ec-parameter:sect233r1* | Asymmetric key operations
*ec-parameter:sect239k1* | Asymmetric key operations
*ec-parameter:sect283k1* | Asymmetric key operations
*ec-parameter:sect283r1* | Asymmetric key operations
*ec-parameter:sect409k1* | Asymmetric key operations
*ec-parameter:sect409r1* | Asymmetric key operations
*ec-parameter:sect571k1* | Asymmetric key operations
*ec-parameter:sect571r1* | Asymmetric key operations
*extension:authority-info-access* | X.509 extension
*extension:authority-key-identifier* | X.509 extension
*extension:basic-constraints* | X.509 extension
*extension:certificate-issuer* | X.509 extension
*extension:certificate-policies* | X.509 extension
*extension:crl-distribution-points* | X.509 extension
*extension:crl-number* | X.509 extension
*extension:crl-reason* | X.509 extension
*extension:delta-crl-indicator* | X.509 extension
*extension:ext-key-usage* | X.509 extension
*extension:freshest-crl* | X.509 extension
*extension:hold-instruction-code* | X.509 extension
*extension:inhibit-any-policy* | X.509 extension
*extension:invalidity-date* | X.509 extension
*extension:issuer-alt-name* | X.509 extension
*extension:issuing-distribution-point* | X.509 extension
*extension:key-usage* | X.509 extension
*extension:name-constraints* | X.509 extension
*extension:policy-constraints* | X.509 extension
*extension:policy-mappings* | X.509 extension
*extension:private-key-usage-period* | X.509 extension
*extension:subject-alt-name* | X.509 extension
*extension:subject-directory-attributes* | X.509 extension
*extension:subject-info-access* | X.509 extension
*extension:subject-key-identifier* | X.509 extension
*http-user-agent* | Request APIs
*json-map-type* | (text json) -- JSON parser
*json-patcher:ignore-no-such-path* | (text json patch) - JSON Patch
*json-schema:external-schema-resolver* | JSON Schema validator
*json-schema:lint-mode?* | JSON Schema validator
*json-schema:report-port* | JSON Schema validator
*json-schema:resolve-external-schema?* | JSON Schema validator
*json-schema:validate-format?* | JSON Schema validator
*json-schema:validator-error-reporter* | JSON Schema validator
*key:dsa | Asymmetric key operations
*key:ecdsa | Asymmetric key operations
*key:ed25519 | Asymmetric key operations
*key:ed448 | Asymmetric key operations
*key:rsa | Asymmetric key operations
*key:x25519 | Asymmetric key operations
*key:x448 | Asymmetric key operations
*mac:cmac* | Algorithms
*mac:gmac* | Algorithms
*mac:hmac* | Algorithms
*mac:kmac* | Algorithms
*mac:kmac-128* | Algorithms
*mac:kmac-256* | Algorithms
*memory-order:acq-rel* | Atomic
*memory-order:acq-rel* | (sagittarius atomic) - Atomic operation
*memory-order:acquire* | Atomic
*memory-order:acquire* | (sagittarius atomic) - Atomic operation
*memory-order:consume* | Atomic
*memory-order:consume* | (sagittarius atomic) - Atomic operation
*memory-order:relaxed* | Atomic
*memory-order:relaxed* | (sagittarius atomic) - Atomic operation
*memory-order:release* | Atomic
*memory-order:release* | (sagittarius atomic) - Atomic operation
*memory-order:seq-cst* | Atomic
*memory-order:seq-cst* | (sagittarius atomic) - Atomic operation
*mode:cbc* | Symmetric ciphers
*mode:ccm* | Symmetric ciphers
*mode:cfb* | Symmetric ciphers
*mode:ctr* | Symmetric ciphers
*mode:eax* | Symmetric ciphers
*mode:ecb* | Symmetric ciphers
*mode:f8* | Symmetric ciphers
*mode:gcm* | Symmetric ciphers
*mode:gcm-siv* | Symmetric ciphers
*mode:lrw* | Symmetric ciphers
*mode:ocb* | Symmetric ciphers
*mode:ocb3* | Symmetric ciphers
*mode:ofb* | Symmetric ciphers
*namespace* | High level APIs
*password-policy:default-char-set* | Password policy operations
*password-policy:default-length* | Password policy operations
*pkcs-9:channelge-password* | X.509 attribute
*pkcs-9:extenion-request* | X.509 attribute
*post-json-array-build* | JSON object builder
*post-json-object-build* | JSON object builder
*private-key-formats* | Asymmetric key operations
*prng:chacha20* | PRNG descriptor
*prng:fortuna* | PRNG descriptor
*prng:rc4* | PRNG descriptor
*prng:sober-128* | PRNG descriptor
*prng:system* | PRNG descriptor
*prng:yarrow* | PRNG descriptor
*public-key-formats* | Asymmetric key operations
*rfc2396-unreserved-char-set* | (rfc uri) - Parse and construct URIs
*rfc3986-unreserved-char-set* | (rfc uri) - Parse and construct URIs
*rfc5322-atext-chars* | Basic field parsers
*rfc5322-standard-tokenizers* | Basic field parsers
*scheme:aes* | Symmetric ciphers
*scheme:aes-128* | Symmetric ciphers
*scheme:aes-192* | Symmetric ciphers
*scheme:aes-256* | Symmetric ciphers
*scheme:blowfish* | Symmetric ciphers
*scheme:camellia* | Symmetric ciphers
*scheme:cast-128* | Symmetric ciphers
*scheme:cast5* | Symmetric ciphers
*scheme:chacha20* | Symmetric ciphers
*scheme:chacha20-poly1305* | Symmetric ciphers
*scheme:des* | Symmetric ciphers
*scheme:des3* | Symmetric ciphers
*scheme:desede* | Symmetric ciphers
*scheme:kasumi* | Symmetric ciphers
*scheme:khazad* | Symmetric ciphers
*scheme:noekeon* | Symmetric ciphers
*scheme:rc2* | Symmetric ciphers
*scheme:rc5* | Symmetric ciphers
*scheme:rc6* | Symmetric ciphers
*scheme:rsa* | Asymmetric ciphers
*scheme:safer+* | Symmetric ciphers
*scheme:safer-k128* | Symmetric ciphers
*scheme:safer-k64* | Symmetric ciphers
*scheme:safer-sk128* | Symmetric ciphers
*scheme:safer-sk64* | Symmetric ciphers
*scheme:seed* | Symmetric ciphers
*scheme:skipjack* | Symmetric ciphers
*scheme:twofish* | Symmetric ciphers
*scheme:x-tea* | Symmetric ciphers
*scheme:xchacha20* | Symmetric ciphers
*scheme:xchacha20-poly1305* | Symmetric ciphers
*signature-algorithm:dsa-sha224* | Supporting algorithms' OIDs
*signature-algorithm:dsa-sha256* | Supporting algorithms' OIDs
*signature-algorithm:dsa-sha384* | Supporting algorithms' OIDs
*signature-algorithm:dsa-sha512* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha1* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha224* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha256* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha3-224* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha3-256* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha3-384* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha3-512* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha384* | Supporting algorithms' OIDs
*signature-algorithm:ecdsa-sha512* | Supporting algorithms' OIDs
*signature-algorithm:ed25519* | Supporting algorithms' OIDs
*signature-algorithm:ed448* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha1* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha224* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha256* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha3-224* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha3-256* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha3-384* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha3-512* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha384* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha512* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha512/224* | Supporting algorithms' OIDs
*signature-algorithm:rsa-pkcs-v1.5-sha512/256* | Supporting algorithms' OIDs
*signature-algorithm:rsa-ssa-pss* | Supporting algorithms' OIDs
*signature:dsa* | Algorithms
*signature:ecdsa* | Algorithms
*signature:ed25519* | Algorithms
*signature:ed25519ctx* | Algorithms
*signature:ed25519ph* | Algorithms
*signature:ed448* | Algorithms
*signature:ed448ph* | Algorithms
*signature:eddsa* | Algorithms
*signature:rsa* | Algorithms
*tls-version-1.0* | Implementation notes:
*tls-version-1.1* | Implementation notes:
*tls-version-1.2* | Implementation notes:
*uuid-clock-seq* | Predefined namespaces and parameters
*uuid-node* | Predefined namespaces and parameters
*uuid-random-state* | Predefined namespaces and parameters
*uuids-per-tick* | Predefined namespaces and parameters

##### +

+ | Arithmetic operations
+. | Arithmetic operations
+debug-level+ | Loggers
+default-chunk-size+ | Chunk buffered port
+error-level+ | Loggers
+fatal-level+ | Loggers
+info-level+ | Loggers
+mqtt-3.1+ | (net mq mqtt) - MQTT library
+mqtt-3.1.1+ | (net mq mqtt) - MQTT library
+namespace-dns+ | Predefined namespaces and parameters
+namespace-oid+ | Predefined namespaces and parameters
+namespace-url+ | Predefined namespaces and parameters
+namespace-x500+ | Predefined namespaces and parameters
+qos-at-least-once+ | (net mq mqtt) - MQTT library
+qos-at-most-once+ | (net mq mqtt) - MQTT library
+qos-exactly-once+ | (net mq mqtt) - MQTT library
+ssh-fxf-append+ | High level APIs
+ssh-fxf-creat+ | High level APIs
+ssh-fxf-excl+ | High level APIs
+ssh-fxf-read+ | High level APIs
+ssh-fxf-trunc+ | High level APIs
+ssh-fxf-write+ | High level APIs
+trace-level+ | Loggers
+warn-level+ | Loggers
+websocket-binary-frame+ | WebSocket Messages
+websocket-close-frame+ | WebSocket Messages
+websocket-ping-frame+ | WebSocket Messages
+websocket-pong-frame+ | WebSocket Messages
+websocket-text-frame+ | WebSocket Messages

##### -

- | Arithmetic operations
- | Arithmetic operations
-. | Arithmetic operations
-. | Arithmetic operations
-> | JSON object serializer
->binary-pre-allocated-buffer-output-port | Operations
->chunked-binary-input-port | Chunk buffered port
->generator | Generator constructors
->integer | (sagittarius object) - Convenient refs and coercion procedures
->number | (sagittarius object) - Convenient refs and coercion procedures
->odd-parity | (util bytevector) - Bytevector utility library
->odd-parity! | (util bytevector) - Bytevector utility library
->string | (sagittarius object) - Convenient refs and coercion procedures

##### /

/ | Arithmetic operations
/ | Arithmetic operations
/. | Arithmetic operations
/. | Arithmetic operations

##### <

< | Arithmetic operations
<!> | High level APIs
<= | Arithmetic operations
<allocation-meta> | (sagittarius mop allocation)
<allocation-mixin> | (sagittarius mop allocation)
<appender> | Appenders
<archive-entry> | Implementing archive implementation library
<archive-input> | Implementing archive implementation library
<archive-output> | Implementing archive implementation library
<async-logger> | Loggers
<binary-request-payload> | HTTP request payload
<cipher-spi> | Creating own cipher
<csv> | Low level APIs
<ctr-paramater> | Mode parameters
<custom-binary-input-port> | Custom ports
<custom-binary-input/output-port> | Custom ports
<custom-binary-output-port> | Custom ports
<custom-random-generator> | Custom random generator
<custom-textual-input-port> | Custom ports
<custom-textual-input/output-port> | Custom ports
<custom-textual-output-port> | Custom ports
<daily-rolling-file-appender> | Appenders
<dbm-meta> | Opening and closing a dbm database
<dbm> | Opening and closing a dbm database
<deque> | (util deque) - Deque
<eql-specializable-generic> | (sagittarius mop eql)
<executor-future> | Executor future
<executor> | Generic Executor APIs
<file-appender> | Appenders
<fork-join-executor> | Fork join executor
<fork-join-pool> | Thread pool
<future> | Future
<heap> | Constructors, predicates and accessors
<http-request-payload> | HTTP request payload
<iv-paramater> | Mode parameters
<json-request-payload> | HTTP request payload
<json-request> | (rpc json) - JSON RPC library
<json-response> | (rpc json) - JSON RPC library
<json-validator> | (text json validator) - JSON validator
<jwe-header> | JWE Header
<jwe-object> | JWE Object
<jws-header> | JWS Header
<jws-object> | JWS Object
<jws-signed-object> | JWS Object
<jwt-claims> | JWT Claims
<key-provider> | Key Provider
<keystore> | Generic APIs
<log> | Creating appenders
<logger> | Loggers
<mtdeque> | (util deque) - Deque
<mtqueue> | (util queue) - Queue
<octet-stream-request-payload> | HTTP request payload
<padding-paramater> | Mode parameters
<pkcs12-keystore> | Keystore APIs
<pre-allocated-buffer> | Pre-allocated buffer
<private-key> | Key operations
<public-key> | Key operations
<queue> | (util queue) - Queue
<rfc3686-paramater> | Mode parameters
<rolling-file-appender> | Appenders
<server-config> | Configuration
<shared-queue> | Shared queues
<simple-future> | Simple future
<simple-server> | Server
<socket-info> | Socket information
<thread-pool-executor> | Thread pool executor
<thread-pool> | Thread pool
<uuid> | (rfc uuid) - UUID generate library
<validator-meta> | (sagittarius mop validator)
<validator-mixin> | (sagittarius mop validator)
<x-www-form-urlencoded-request-payload> | HTTP request payload

##### =

= | Arithmetic operations

##### >

> | Arithmetic operations
>= | Arithmetic operations

##### ?

? | High level APIs
? | JSON object serializer
? | JSON object builder
?? | High level APIs

##### @

@ | JSON object serializer
@ | JSON object builder

##### ^

^ | (sagittarius control) - control library
^c | (sagittarius control) - control library
^c* | (sagittarius control) - control library

##### _

_struct-name_ | C struct operations
_struct-name_ | C struct operations

##### A

aad-parameter? | Ciphers parameters
abort-rejected-handler | Thread pool executor
abs | Arithmetic operations
access-protected-resource | (net oauth) - OAuth library
acons | List operations
acos | Arithmetic operations
actor-receive-message! | Actor
actor-running? | Actor
actor-send-message! | Actor
actor-terminate! | Actor
actor-wait! | Actor
actor? | Actor
add-load-path | Load path
add-load-suffix | Load path
add-method | (clos core) - CLOS core library
add-record! | Low level APIs
add-records! | Low level APIs
add-records! | Low level APIs
address | Creating C functions
address | Creating C functions
addrinfo-sockaddr | Addrinfo
addrinfo? | Addrinfo
adler32 | (rfc zlib) - zlib compression library
AES | Cipher operations
AES-128 | Cipher operations
AES-192 | Cipher operations
AES-256 | Cipher operations
align-of- | Sizes and aligns
alist->hashtable | (util hashtables) - Hashtable utilities
alist->heap | Constructors, predicates and accessors
alist->treemap | Conversions
all-threads | (sagittarius debug) - Debugging support
allocate-c-struct | C struct operations
allocate-pointer | Pointer operations
amqp-connection? | High level APIs
amqp-message? | High level APIs
amqp-receiver? | High level APIs
amqp-sender? | High level APIs
amqp-session? | High level APIs
and | Derived conditionals
angle | Arithmetic operations
any-in-deque | (util deque) - Deque
any-in-queue | (util queue) - Queue
append | Pairs and lists
append! | List operations
append-entry! | Archive output
append-log | Creating appenders
appender-finish | Creating appenders
appender-log-format | Creating appenders
appender? | Appenders
apply | Control features
archive | (archive) - Generic archive interface
archive-entry-name | Entry accessor
archive-entry-type | Entry accessor
arity | Debugging aid
array_of | Extra functions
as-nodeset | Basic converters and applicators
asin | Arithmetic operations
assc | List utilities
assert-curr-char | (text parse) - Parsing input stream
assertion-violation | Errors and violations
assertion-violation? | Standard condition types
assp | List utilities
assq | List utilities
assv | List utilities
asymmetric-cipher-decrypt-bytevector | Asymmetric ciphers
asymmetric-cipher-descriptor? | Asymmetric ciphers
asymmetric-cipher-done! | Asymmetric ciphers
asymmetric-cipher-encrypt-bytevector | Asymmetric ciphers
asymmetric-cipher-init | Asymmetric ciphers
asymmetric-cipher-init! | Asymmetric ciphers
asymmetric-cipher? | Asymmetric ciphers
asymmetric-key? | Key type
async-http-request | HTTP request procedures
async-http-request/client | HTTP request procedures
async-http-{bodied-methods} | HTTP request procedures
async-http-{bodied-methods} | HTTP request procedures
async-http-{bodied-methods} | HTTP request procedures
async-http-{bodied-methods}/client | HTTP request procedures
async-http-{bodied-methods}/client | HTTP request procedures
async-http-{bodied-methods}/client | HTTP request procedures
async-http-{nobody-methods} | HTTP request procedures
async-http-{nobody-methods} | HTTP request procedures
async-http-{nobody-methods}/client | HTTP request procedures
async-http-{nobody-methods}/client | HTTP request procedures
async-logger? | Loggers
async-process-read | Middle level APIs
atan | Arithmetic operations
atan | Arithmetic operations
atomic-compare-and-swap! | Atomic
atomic-compare-and-swap! | (sagittarius atomic) - Atomic operation
atomic-exchange! | Atomic
atomic-exchange! | (sagittarius atomic) - Atomic operation
atomic-fetch-compare-and-swap! | Atomic
atomic-fetch-compare-and-swap! | (sagittarius atomic) - Atomic operation
atomic-fixnum-add! | Atomic
atomic-fixnum-add! | (sagittarius atomic) - Atomic operation
atomic-fixnum-and! | Atomic
atomic-fixnum-and! | (sagittarius atomic) - Atomic operation
atomic-fixnum-dec! | Atomic
atomic-fixnum-dec! | (sagittarius atomic) - Atomic operation
atomic-fixnum-exchange! | Atomic
atomic-fixnum-exchange! | (sagittarius atomic) - Atomic operation
atomic-fixnum-inc! | Atomic
atomic-fixnum-inc! | (sagittarius atomic) - Atomic operation
atomic-fixnum-ior! | Atomic
atomic-fixnum-ior! | (sagittarius atomic) - Atomic operation
atomic-fixnum-load | Atomic
atomic-fixnum-load | (sagittarius atomic) - Atomic operation
atomic-fixnum-store! | Atomic
atomic-fixnum-store! | (sagittarius atomic) - Atomic operation
atomic-fixnum-sub! | Atomic
atomic-fixnum-sub! | (sagittarius atomic) - Atomic operation
atomic-fixnum-xor! | Atomic
atomic-fixnum-xor! | (sagittarius atomic) - Atomic operation
atomic-fixnum? | Atomic
atomic-fixnum? | (sagittarius atomic) - Atomic operation
atomic-flag? | Atomic
atomic-flag? | (sagittarius atomic) - Atomic operation
atomic-load | Atomic
atomic-load | (sagittarius atomic) - Atomic operation
atomic-pair? | Atomic
atomic-pair? | (sagittarius atomic) - Atomic operation
atomic-store! | Atomic
atomic-store! | (sagittarius atomic) - Atomic operation
atomic-thread-fence | Atomic
atomic-thread-fence | (sagittarius atomic) - Atomic operation
atomic? | Atomic
atomic? | (sagittarius atomic) - Atomic operation
attlist->alist | Low-level parsing code
attlist-add | Low-level parsing code
attlist-fold | Low-level parsing code
attlist-null? | Low-level parsing code
attlist-remove-top | Low-level parsing code
authorize-request-token | (net oauth) - OAuth library

##### B

base-generator->results | parse-results
base32-decode | Decoding procedures
base32-decode-string | Decoding procedures
base32-encode | Encoding procedures
base32-encode-string | Encoding procedures
base32hex-decode | Decoding procedures
base32hex-decode-string | Decoding procedures
base32hex-encode | Encoding procedures
base32hex-encode-string | Encoding procedures
base64-decode | Decoding procedures
base64-decode-string | Decoding procedures
base64-encode | Encoding procedures
base64-encode-string | Encoding procedures
base64url-decode | Decoding procedures
base64url-decode-string | Decoding procedures
base64url-encode | Encoding procedures
base64url-encode-string | Encoding procedures
begin | Sequencing
begin | Sequencing
begin-amqp-session! | High level APIs
begin0 | (sagittarius control) - control library
binary-payload | HTTP request payload
binary-port? | Input and output ports
binary-pre-allocated-buffer-can-store? | Operations
binary-pre-allocated-buffer-get-bytevector-n! | Operations
binary-pre-allocated-buffer-put-bytevector! | Operations
binary-pre-allocated-buffer-put-f32! | Operations
binary-pre-allocated-buffer-put-f64! | Operations
binary-pre-allocated-buffer-put-s16! | Operations
binary-pre-allocated-buffer-put-s32! | Operations
binary-pre-allocated-buffer-put-s64! | Operations
binary-pre-allocated-buffer-put-s8! | Operations
binary-pre-allocated-buffer-put-u16! | Operations
binary-pre-allocated-buffer-put-u32! | Operations
binary-pre-allocated-buffer-put-u64! | Operations
binary-pre-allocated-buffer-put-u8! | Operations
binary-pre-allocated-buffer-set-bytevector! | Operations
binary-pre-allocated-buffer-set-f32! | Operations
binary-pre-allocated-buffer-set-f64! | Operations
binary-pre-allocated-buffer-set-s16! | Operations
binary-pre-allocated-buffer-set-s32! | Operations
binary-pre-allocated-buffer-set-s64! | Operations
binary-pre-allocated-buffer-set-s8! | Operations
binary-pre-allocated-buffer-set-u16! | Operations
binary-pre-allocated-buffer-set-u32! | Operations
binary-pre-allocated-buffer-set-u64! | Operations
binary-pre-allocated-buffer-set-u8! | Operations
binary-pre-allocated-buffer-swap! | Operations
binary-pre-allocated-buffer? | Binary pre-allocated buffer
binary-request-payload? | HTTP request payload
bind-parameter! | (odbc) - ODBC binding
bitwise-and | Exact bitwise arithmetic
bitwise-arithmetic-shift | Exact bitwise arithmetic
bitwise-arithmetic-shift-left | Exact bitwise arithmetic
bitwise-arithmetic-shift-right | Exact bitwise arithmetic
bitwise-bit-count | Exact bitwise arithmetic
bitwise-bit-field | Exact bitwise arithmetic
bitwise-bit-set? | Exact bitwise arithmetic
bitwise-copy-bit | Exact bitwise arithmetic
bitwise-copy-bit-field | Exact bitwise arithmetic
bitwise-first-bit-set | Exact bitwise arithmetic
bitwise-if | Exact bitwise arithmetic
bitwise-ior | Exact bitwise arithmetic
bitwise-length | Exact bitwise arithmetic
bitwise-not | Exact bitwise arithmetic
bitwise-reverse-bit-field | Exact bitwise arithmetic
bitwise-rotate-bit-field | Exact bitwise arithmetic
bitwise-xor | Exact bitwise arithmetic
BLAKE2b-160 | Hash operations
BLAKE2b-256 | Hash operations
BLAKE2b-384 | Hash operations
BLAKE2b-512 | Hash operations
BLAKE2s-128 | Hash operations
BLAKE2s-160 | Hash operations
BLAKE2s-224 | Hash operations
BLAKE2s-256 | Hash operations
block-cipher-block-length | Symmetric ciphers
block-cipher-decrypt | Symmetric ciphers
block-cipher-decrypt! | Symmetric ciphers
block-cipher-decrypt-last-block | Symmetric ciphers
block-cipher-decrypt-last-block! | Symmetric ciphers
block-cipher-descriptor-block-length | Symmetric ciphers
block-cipher-descriptor-suggested-key-length | Symmetric ciphers
block-cipher-descriptor? | Symmetric ciphers
block-cipher-done! | Symmetric ciphers
block-cipher-done/tag | Symmetric ciphers
block-cipher-done/tag! | Symmetric ciphers
block-cipher-encrypt | Symmetric ciphers
block-cipher-encrypt! | Symmetric ciphers
block-cipher-encrypt-last-block | Symmetric ciphers
block-cipher-encrypt-last-block! | Symmetric ciphers
block-cipher-init | Symmetric ciphers
block-cipher-init! | Symmetric ciphers
block-cipher-last-block-size | Symmetric ciphers
block-cipher-max-tag-length | Symmetric ciphers
block-cipher-update-aad! | Symmetric ciphers
block-cipher-update-iv! | Symmetric ciphers
block-cipher? | Symmetric ciphers
Blowfish | Cipher operations
boolean=? | Booleans
boolean? | Booleans
bound-identifier=? | Syntax-case
buffer-mode | Buffer modes
buffer-mode? | Buffer modes
buffered-port | (sagittarius io) - Extra IO library
buffered-port | I/O
build-path | Path operations
build-path | File system operations
build-path* | Path operations
builtin-random-generator? | Random generator
bytevector | Bytevectors
bytevector->escaped-string | (util bytevector) - Bytevector utility library
bytevector->generator | Generator constructors
bytevector->hex-string | (util bytevector) - Bytevector utility library
bytevector->integer | Bytevector operations
bytevector->pkcs12-keystore | Keystore library - (sagittarius crypto keystores)
bytevector->pointer | Pointer operations
bytevector->sint-list | Operations on integers of arbitary size
bytevector->sinteger | Bytevector operations
bytevector->string | Transcoders
bytevector->subject-public-key-info | X.509 subject public key info
bytevector->u8-list | Operation on bytes and octets
bytevector->uint-list | Operations on integers of arbitary size
bytevector->uinteger | Bytevector operations
bytevector->uuid | Converters
bytevector->x509-certificate | X.509 certificate
bytevector->x509-certificate-revocation-list | X.509 CRL
bytevector->x509-certification-request | X.509 CSR
bytevector-and | (util bytevector) - Bytevector utility library
bytevector-and! | (util bytevector) - Bytevector utility library
bytevector-append | Bytevector operations
bytevector-append | Bytevectors
bytevector-concatenate | Bytevector operations
bytevector-contains | Bytevectors as ASCII strings
bytevector-copy | General operations
bytevector-copy! | Bytevectors
bytevector-copy! | General operations
bytevector-delete | Bytevectors as ASCII strings
bytevector-drop | Bytevectors as ASCII strings
bytevector-drop-right | Bytevectors as ASCII strings
bytevector-fill! | General operations
bytevector-filter | Bytevectors as ASCII strings
bytevector-fold | Bytevectors as ASCII strings
bytevector-fold-right | Bytevectors as ASCII strings
bytevector-ieee-double-native-ref | Operation on IEEE-754 representations
bytevector-ieee-double-native-set! | Operation on IEEE-754 representations
bytevector-ieee-double-ref | Operation on IEEE-754 representations
bytevector-ieee-double-set! | Operation on IEEE-754 representations
bytevector-ieee-single-native-ref | Operation on IEEE-754 representations
bytevector-ieee-single-native-set! | Operation on IEEE-754 representations
bytevector-ieee-single-ref | Operation on IEEE-754 representations
bytevector-ieee-single-set! | Operation on IEEE-754 representations
bytevector-index | Bytevectors as ASCII strings
bytevector-index-right | Bytevectors as ASCII strings
bytevector-ior | (util bytevector) - Bytevector utility library
bytevector-ior! | (util bytevector) - Bytevector utility library
bytevector-length | General operations
bytevector-pad | Bytevectors as ASCII strings
bytevector-pad-right | Bytevectors as ASCII strings
bytevector-prefix-length | Bytevectors as ASCII strings
bytevector-prefix? | Bytevectors as ASCII strings
bytevector-replace | Bytevectors as ASCII strings
bytevector-reverse | (util bytevector) - Bytevector utility library
bytevector-reverse! | (util bytevector) - Bytevector utility library
bytevector-s16-native-ref | Operation on 16-bit integers
bytevector-s16-native-set! | Operation on 16-bit integers
bytevector-s16-ref | Operation on 16-bit integers
bytevector-s16-set! | Operation on 16-bit integers
bytevector-s32-native-ref | Operation on 32-bit integers
bytevector-s32-native-set! | Operation on 32-bit integers
bytevector-s32-ref | Operation on 32-bit integers
bytevector-s32-set! | Operation on 32-bit integers
bytevector-s64-native-ref | Operation on 64-bit integers
bytevector-s64-native-set! | Operation on 64-bit integers
bytevector-s64-ref | Operation on 64-bit integers
bytevector-s64-set! | Operation on 64-bit integers
bytevector-s8-ref | Operation on bytes and octets
bytevector-s8-set! | Operation on bytes and octets
bytevector-sint-ref | Operations on integers of arbitary size
bytevector-sint-set! | Operations on integers of arbitary size
bytevector-skip | Bytevectors as ASCII strings
bytevector-skip-right | Bytevectors as ASCII strings
bytevector-slices | (util bytevector) - Bytevector utility library
bytevector-split-at* | (util bytevector) - Bytevector utility library
bytevector-suffix-length | Bytevectors as ASCII strings
bytevector-suffix? | Bytevectors as ASCII strings
bytevector-take | Bytevectors as ASCII strings
bytevector-take-right | Bytevectors as ASCII strings
bytevector-tokenize | Bytevectors as ASCII strings
bytevector-trim | Bytevectors as ASCII strings
bytevector-trim-both | Bytevectors as ASCII strings
bytevector-trim-right | Bytevectors as ASCII strings
bytevector-u16-native-ref | Operation on 16-bit integers
bytevector-u16-native-set! | Operation on 16-bit integers
bytevector-u16-ref | Operation on 16-bit integers
bytevector-u16-set! | Operation on 16-bit integers
bytevector-u32-native-ref | Operation on 32-bit integers
bytevector-u32-native-set! | Operation on 32-bit integers
bytevector-u32-ref | Operation on 32-bit integers
bytevector-u32-set! | Operation on 32-bit integers
bytevector-u64-native-ref | Operation on 64-bit integers
bytevector-u64-native-set! | Operation on 64-bit integers
bytevector-u64-ref | Operation on 64-bit integers
bytevector-u64-set! | Operation on 64-bit integers
bytevector-u8-ref | Operation on bytes and octets
bytevector-u8-set! | Operation on bytes and octets
bytevector-uint-ref | Operations on integers of arbitary size
bytevector-uint-set! | Operations on integers of arbitary size
bytevector-xor | (util bytevector) - Bytevector utility library
bytevector-xor! | (util bytevector) - Bytevector utility library
bytevector<=? | (util bytevector) - Bytevector utility library
bytevector<? | (util bytevector) - Bytevector utility library
bytevector=? | General operations
bytevector>=? | (util bytevector) - Bytevector utility library
bytevector>? | (util bytevector) - Bytevector utility library
bytevector? | General operations

##### C

c-callback | Creating C functions
c-free | Pointer operations
c-function | Creating C functions
c-malloc | Pointer operations
c-struct-ref | Low level C struct accessors
c-struct-set! | Low level C struct accessors
caar | Pairs and lists
cadddr | Pairs and lists
cadr | Pairs and lists
calculate-key-agreement | Asymmetric key operations
calculate-key-agreement | Asymmetric key operations
calculate-key-agreement | Asymmetric key operations
call | High level APIs
call-with-amqp-connection | High level APIs
call-with-amqp-connection | High level APIs
call-with-bytevector-output-port | Output ports
call-with-current-continuation | Control features
call-with-input-archive | Archive input
call-with-input-archive-file | Archive input
call-with-input-archive-port | Archive input
call-with-input-file | Simple I/O
call-with-input-string | (sagittarius io) - Extra IO library
call-with-output-archive | Archive output
call-with-output-archive-file | Archive output
call-with-output-archive-port | Archive output
call-with-output-file | Simple I/O
call-with-output-string | (sagittarius io) - Extra IO library
call-with-port | Input and output ports
call-with-sftp-connection | High level APIs
call-with-socket | Integration methods
call-with-socket | (sagittarius socket) - socket library
call-with-string-output-port | Output ports
call-with-values | Control features
call/cc | Control features
Camellia | Cipher operations
car | Pairs and lists
car-sxpath | Wrappers
case | Derived conditionals
case-lambda | Control structures
CAST-128 | Cipher operations
CAST5 | Cipher operations
cddddr | Pairs and lists
cdr | Pairs and lists
ceiling | Arithmetic operations
change-file-mode | File system operations
change-file-timestamp! | File system operations
char->integer | Characters
char-alphabetic? | Characters
char-ci<=? | Characters
char-ci<? | Characters
char-ci=? | Characters
char-ci>=? | Characters
char-ci>? | Characters
char-downcase | Characters
char-foldcase | Characters
char-general-category | Characters
char-lower-case? | Characters
char-numeric? | Characters
char-ready? | I/O
char-set->u8-set | U8 sets
char-title-case? | Characters
char-titlecase | Characters
char-upcase | Characters
char-upper-case? | Characters
char-whitespace? | Characters
char<=? | Characters
char<? | Characters
char=? | Characters
char>=? | Characters
char>? | Characters
char? | Characters
character-policy? | Password policy operations
check-arg | (sagittarius control) - control library
check-validity | (rfc x.509) - X.509 certificate utility library
cipher-decrypt | Cipher operations
cipher-decrypt/tag | Cipher operations
cipher-decrypt/verify | Cipher operations
cipher-descriptor-name | Ciphers
cipher-descriptor? | Ciphers
cipher-direction | Ciphers
cipher-encrypt | Cipher operations
cipher-encrypt/tag | Cipher operations
cipher-keysize | Cipher operations
cipher-max-tag-size | Cipher operations
cipher-parameter-aad | Ciphers parameters
cipher-parameter-counter-mode | Ciphers parameters
cipher-parameter-iv | Ciphers parameters
cipher-parameter-nonce | Ciphers parameters
cipher-parameter-rounds | Ciphers parameters
cipher-parameter-salt | Ciphers parameters
cipher-parameter-tag | Ciphers parameters
cipher-parameter-tag-length | Ciphers parameters
cipher-parameter-tweak | Ciphers parameters
cipher-parameter? | Ciphers parameters
cipher-signature | Cipher operations
cipher-spi? | Creating own cipher
cipher-tag | Cipher operations
cipher-tag! | Cipher operations
cipher-update-aad! | Cipher operations
cipher-verify | Cipher operations
cipher? | Cipher operations
cipher? | Ciphers
circular-generator | Generator constructors
circular-list? | List operations
close | Custom ports
close-amqp-connection! | High level APIs
close-http-connection! | (rfc http-connections) - HTTP client utilities
close-http2-client-connection! | (rfc http2) - HTTP/2 client
close-input-file | Simple I/O
close-mqtt-connection! | (net mq mqtt) - MQTT library
close-output-file | Simple I/O
close-port | Input and output ports
close-shared-library | Shared library operations
close-shared-memory | Inter-process communication (IPC)
CMAC | (rfc cmac) - CMAC library
collect-sockets | FD sets
column-count | (odbc) - ODBC binding
combine-key-components | Key operations
combine-key-components! | Key operations
command-line | Command-line access and exit values
commit! | (odbc) - ODBC binding
commonmark-parser | Markdown parser APIs
compile-regex | Low level APIs for regular expression
complex? | Numerical type predicates
compute-getter-and-setter | (clos core) - CLOS core library
compute-getters-and-setters | (clos core) - CLOS core library
cond | Derived conditionals
cond-expand | Builtin Syntax
cond-list | (util list) - Extra list utility library
condition | Conditions
condition-accessor | Conditions
condition-decrypt-mechanism | Cryptographic conditions
condition-driver-name | Conditions
condition-encrypt-mechanism | Cryptographic conditions
condition-irritants | Standard condition types
condition-message | Standard condition types
condition-predicate | Conditions
condition-variable-broadcast! | Condition variable APIs
condition-variable-name | Condition variable APIs
condition-variable-signal | Condition variable APIs
condition-variable-specific | Condition variable APIs
condition-variable-specific-set! | Condition variable APIs
condition-variable? | Condition variable APIs
condition-who | Standard condition types
condition-zlib-stream | (rfc zlib) - zlib compression library
condition? | Conditions
connect! | (odbc) - ODBC binding
connection-open? | (odbc) - ODBC binding
cons | Pairs and lists
cons* | List utilities
convert-markdown | Markdown converter APIs
convert-markdown | Markdown converter APIs
copy-deque | (util deque) - Deque
copy-directory | Directory operations
copy-file | File system operations
copy-heap | Constructors, predicates and accessors
copy-queue | (util queue) - Queue
cos | Arithmetic operations
counter-mode-parameter? | Ciphers parameters
cpu-count | System and platform
crc32 | (rfc zlib) - zlib compression library
create-amqp-binary-message data | High level APIs
create-amqp-mime-message content-type data | High level APIs
create-amqp-receiver | High level APIs
create-amqp-sender | High level APIs
create-amqp-text-message text | High level APIs
create-directory | Directory operations
create-directory | File system operations
create-directory* | Directory operations
create-entry | Archive output
create-entry | Archive output
create-odbc-env | (odbc) - ODBC binding
create-process | Middle level APIs
create-symbolic-link | File system operations
crop-binary-buffer | Operations
crypto-error? | Cryptographic conditions
crypto-key? | Key type
crypto-object? | (crypto) - Cryptographic library
csv->list | Middle level APIs
csv-header | High level APIs
csv-read | High level APIs
csv-read | High level APIs
csv-records | High level APIs
csv-write | High level APIs
csv? | High level APIs
CTR_COUNTER_BIG_ENDIAN | Mode parameters
CTR_COUNTER_LITTLE_ENDIAN | Mode parameters
current-directory | File system operations
current-error-port | Output ports
current-input-port | Input ports
current-jiffy | Time library
current-output-port | Output ports
current-second | Time library
current-thread | Thread APIs
custom-random-generator? | Random generator

##### D

daily-rolling-file-appender? | Appenders
date->rfc5322-date | Message constructors
datum | (sagittarius control) - control library
datum->syntax | Syntax-case
dbi-bind-parameter! | DBI methods to implement
dbi-bind-parameter! | Preparing and executing queries
dbi-close | DBI methods to implement
dbi-close | DBI methods to implement
dbi-close | Preparing and executing queries
dbi-close | Database connection
dbi-columns | DBI methods to implement
dbi-columns | Preparing and executing queries
dbi-commit! | DBI methods to implement
dbi-commit! | DBI methods to implement
dbi-commit! | Preparing and executing queries
dbi-commit! | Database connection
dbi-connect | Database connection
dbi-driver-not-exist? | Conditions
dbi-error? | Conditions
dbi-execute! | DBI methods to implement
dbi-execute! | Preparing and executing queries
dbi-execute-query! | Preparing and executing queries
dbi-fetch! | DBI methods to implement
dbi-fetch! | Preparing and executing queries
dbi-fetch-all! | Preparing and executing queries
dbi-make-connection | DBI methods to implement
dbi-open? | DBI methods to implement
dbi-open? | DBI methods to implement
dbi-open? | Preparing and executing queries
dbi-open? | Database connection
dbi-prepare | DBI methods to implement
dbi-prepare | Preparing and executing queries
dbi-rollback | DBI methods to implement
dbi-rollback! | DBI methods to implement
dbi-rollback! | Preparing and executing queries
dbi-rollback! | Database connection
dbi-sql-error-code | Conditions
dbi-sql-error? | Conditions
dbi-unsupported? | Conditions
dbm-close | Opening and closing a dbm database
dbm-closed? | Opening and closing a dbm database
dbm-db-copy | Managing dbm database instance
dbm-db-exists? | Managing dbm database instance
dbm-db-move | Managing dbm database instance
dbm-db-remove | Managing dbm database instance
dbm-delete! | Accessing a dbm database
dbm-exists? | Accessing a dbm database
dbm-fold | Iterating on a dbm database
dbm-for-each | Iterating on a dbm database
dbm-get | Accessing a dbm database
dbm-map | Iterating on a dbm database
dbm-open | Opening and closing a dbm database
dbm-open | Opening and closing a dbm database
dbm-put! | Accessing a dbm database
dbm-type->class | Opening and closing a dbm database
debug-log | Loggers
decode-error? | Cryptographic conditions
decompose-path | Path operations
decrypt-error? | Cryptographic conditions
default-delegate-connection-manager-provider | Delegate Connection Manager providers
default-markdown-converter | Markdown converter APIs
define | Variable definitions
define | Variable definitions
define | Variable definitions
define | Variable definitions
define- | (binary pack) - Packing binary data
define-c-struct | C struct operations
define-c-struct | C struct operations
define-c-typedef | Typedef operations
define-class | (clos user) -CLOS user APIs
define-composite-data-define | (binary data) - Binary data read/write
define-condition-type | Conditions
define-constant | Builtin Syntax
define-dispatch-macro | (sagittarius reader) - reader macro library
define-dispatch-macro | (sagittarius reader) - reader macro library
define-enumeration | Enumerations
define-generic | (clos user) -CLOS user APIs
define-library | R7RS library system
define-logger-storage | Singleton logger
define-logger-storage | Singleton logger
define-macro | (sagittarius control) - control library
define-macro | (sagittarius control) - control library
define-method | (clos user) -CLOS user APIs
define-reader | Naming convention
define-reader | Naming convention
define-reader-macro | (sagittarius reader) - reader macro library
define-reader-macro | (sagittarius reader) - reader macro library
define-reader-macro | (sagittarius reader) - reader macro library
define-record-type | Records syntactic layer
define-simple | (binary data) - Binary data read/write
define-simple | (binary data) - Binary data read/write
define-simple-datum-define | (binary data) - Binary data read/write
define-syntax | Syntax definitions
define-values | Multiple-value definition
define-with-key | (sagittarius control) - control library
define-with-key | (sagittarius control) - control library
define-with-key | (sagittarius control) - control library
define-with-key | (sagittarius control) - control library
deflate-bytevector | (rfc zlib) - zlib compression library
delay | R5RS compatibility
delay-force | Lazy library
delete-directory | Directory operations
delete-directory | File system operations
delete-directory* | Directory operations
delete-file | File system
denominator | Arithmetic operations
deque->list | (util deque) - Deque
deque-empty? | (util deque) - Deque
deque-front | (util deque) - Deque
deque-length | (util deque) - Deque
deque-pop! | (util deque) - Deque
deque-pop-all! | (util deque) - Deque
deque-pop/wait! | (util deque) - Deque
deque-push! | (util deque) - Deque
deque-push-unique! | (util deque) - Deque
deque-push/wait! | (util deque) - Deque
deque-rear | (util deque) - Deque
deque-shift! | (util deque) - Deque
deque-shift-all! | (util deque) - Deque
deque-shift/wait! | (util deque) - Deque
deque-unshift! | (util deque) - Deque
deque-unshift-unique! | (util deque) - Deque
deque-unshift/wait! | (util deque) - Deque
deque? | (util deque) - Deque
deque? | (util deque) - Deque
dequeue! | (util queue) - Queue
dequeue-all! | (util queue) - Queue
dequeue/wait! | (util queue) - Queue
deref | Pointer operations
derive-key | Low level APIs
derive-key&iv | Low level APIs
DES | Cipher operations
DES3 | Cipher operations
DESede | Cipher operations
destroy-amqp-receiver | High level APIs
destroy-amqp-sender | High level APIs
digest-descriptor-block-size | Digest descriptor
digest-descriptor-digest-size | Digest descriptor
digest-descriptor-name | Digest descriptor
digest-descriptor-oid | Digest descriptor
digest-descriptor? | Digest descriptor
digest-message | Message Digest
digest-message! | Message Digest
digit-value | Char library
disasm | Debugging aid
disconnect! | (odbc) - ODBC binding
display | Simple I/O
div | Arithmetic operations
div-and-mod | Arithmetic operations
div0 | Arithmetic operations
div0-and-mod0 | Arithmetic operations
do | Control structures
do-entry | Archive input
do-entry | Archive input
do-generator | Generator operations
dolist | (sagittarius control) - control library
dotimes | (sagittarius control) - control library
dotted-list? | List operations
drop* | (util list) - Extra list utility library
DSA | Cipher operations
dump-tlv | High level APIs
duration:of-days | (util duration) - Duration
duration:of-hours | (util duration) - Duration
duration:of-millis | (util duration) - Duration
duration:of-minutes | (util duration) - Duration
duration:of-nanos | (util duration) - Duration
duration:of-seconds | (util duration) - Duration
dynamic-wind | Control features

##### E

ECDSA | Cipher operations
emergency-exit | Process-Context library
empty-pointer | Pointer operations
encode | High level user APIs
encode-error? | Cryptographic conditions
encrypt-error? | Cryptographic conditions
end-amqp-session! | High level APIs
endianness | General operations
enqueue! | (util queue) - Queue
enqueue-unique! | (util queue) - Queue
enqueue/wait! | (util queue) - Queue
enum-set->list | Enumerations
enum-set-complement | Enumerations
enum-set-constructor | Enumerations
enum-set-difference | Enumerations
enum-set-indexer | Enumerations
enum-set-intersection | Enumerations
enum-set-member | Enumerations
enum-set-projection | Enumerations
enum-set-subst? | Enumerations
enum-set-union | Enumerations
enum-set-universe | Enumerations
enum-set=? | Enumerations
environment | eval
eof-object | End-of-file object
eof-object? | End-of-file object
eol-style | Transcoders
eq? | Equivalence predicates
equal-hash | Hash functions
equal? | Differ from R6RS
equal? | Equivalence predicates
eqv? | Equivalence predicates
er-macro-transformer | Macro transformer
error | Errors and violations
error-handling-mode | Transcoders
error-log | Loggers
error-object-irritants | Error objects
error-object-message | Error objects
error-object? | Error objects
error? | Standard condition types
eval | eval
even? | Arithmetic operations
every-in-deque | (util deque) - Deque
every-in-queue | (util queue) - Queue
exact | Generic conversion
exact->inexect | R5RS compatibility
exact-integer? | Numerical operations
exact? | Numerical type predicates
execute! | (odbc) - ODBC binding
execute-future! | Generic Executor APIs
executor-available? | Generic Executor APIs
executor-future? | Executor future
executor-state | Generic Executor APIs
executor-submit! | Generic Executor APIs
executor? | Generic Executor APIs
exists | List utilities
exit | Command-line access and exit values
exp | Arithmetic operations
expand-uri-template | (rfc uri-template) - URI template
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-private-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
export-public-key | Asymmetric key operations
expt | Arithmetic operations
extract-all-entries | Archive input
extract-entry | Archive input

##### F

fatal-log | Loggers
fdset-ref | FD sets
fdset-set! | FD sets
fdset? | FD sets
features | System interface
fetch! | (odbc) - ODBC binding
fields | Records syntactic layer
file->bytevector | File to Scheme object operations
file->list | File to Scheme object operations
file->sexp-list | File to Scheme object operations
file->string | File to Scheme object operations
file->string-list | File to Scheme object operations
file-appender-filename | Appenders
file-appender-filename | Appenders
file-appender? | Appenders
file-directory? | File system operations
file-error? | I/O
file-executable? | File system operations
file-exists? | File system
file-options | File options
file-readable? | File system operations
file-regular? | File system operations
file-size-in-bytes | File system operations
file-stat-atime | File system operations
file-stat-ctime | File system operations
file-stat-mtime | File system operations
file-symbolic-link? | File system operations
file-writable? | File system operations
filesystem-watcher-add-path! | (sagittarius filewatch) - Monitoring filesystem
filesystem-watcher-remove-path! | (sagittarius filewatch) - Monitoring filesystem
filesystem-watcher-start-monitoring! | (sagittarius filewatch) - Monitoring filesystem
filesystem-watcher-stop-monitoring! | (sagittarius filewatch) - Monitoring filesystem
filesystem-watcher? | (sagittarius filewatch) - Monitoring filesystem
filter | List utilities
find | List utilities
find-files | Path operations
find-in-deque | (util deque) - Deque
find-in-queue | (util queue) - Queue
find-string-from-port? | (text parse) - Parsing input stream
finish! | Implementing archive implementation library
finish! | Archive output
finish! | Archive input
finite? | Arithmetic operations
fixnum->flonum | Flonums
fixnum-width | Fixnums
fixnum? | Fixnums
fl* | Flonums
fl+ | Flonums
fl<=? | Flonums
fl<? | Flonums
fl=? | Flonums
fl>=? | Flonums
fl>? | Flonums
flabs | Flonums
flacos | Flonums
flasin | Flonums
flatan | Flonums
flceiling | Flonums
flcos | Flonums
fldenominator | Flonums
fldiv | Flonums
fldiv-and-mod | Flonums
fldiv0 | Flonums
fldiv0-and-mod0 | Flonums
fleven? | Flonums
flexp | Flonums
flexpt | Flonums
flfinite? | Flonums
flfloor | Flonums
flinfinite? | Flonums
flinteger? | Flonums
fllog | Flonums
flmax | Flonums
flmin | Flonums
flmod | Flonums
flmod0 | Flonums
flnan? | Flonums
flnegative? | Flonums
flnumerator | Flonums
flodd? | Flonums
flonum? | Flonums
floor | Arithmetic operations
floor-quotient | Numerical operations
floor-remainder | Numerical operations
floor/ | Numerical operations
flpositive? | Flonums
flround | Flonums
flsin | Flonums
flsqrt | Flonums
fltan | Flonums
fltruncate | Flonums
flush | Custom ports
flush-output-port | Output ports
flzero? | Flonums
fold-left | List utilities
fold-right | List utilities
foo | Notations
for-all | List utilities
for-each | Pairs and lists
for-each-with-index | (util list) - Extra list utility library
force | R5RS compatibility
fork-join-executor-available? | Fork join executor
fork-join-executor-execute-future! | Fork join executor
fork-join-executor-max-thread-count | Fork join executor
fork-join-executor-shutdown! | Fork join executor
fork-join-executor-thread-count | Fork join executor
fork-join-executor? | Fork join executor
fork-join-pool-available? | Thread pool
fork-join-pool-max-threads | Thread pool
fork-join-pool-push-task! | Thread pool
fork-join-pool-shutdown! | Thread pool
fork-join-pool-thread-count | Thread pool
fork-join-pool-wait-all! | Thread pool
fork-join-pool? | Thread pool
format | I/O
format | I/O
format-log | Creating appenders
format-size | (binary pack) - Packing binary data
format-size | (binary pack) - Packing binary data
Fortuna | Random number operations
free-c-callback | Creating C functions
free-handle | (odbc) - ODBC binding
free-identifier=? | Syntax-case
future | Future
future | Future
future-cancel | Future
future-cancelled? | Future
future-done? | Future
future-flatmap | Actor
future-flatmap/executor | Actor
future-get | Future
future-guard | Actor
future-map | Actor
future-map/executor | Actor
future-state | Future
future-terminated? | Future
future? | Future
fx* | Fixnums
fx*/carry | Fixnums
fx+ | Fixnums
fx+/carry | Fixnums
fx- | Fixnums
fx-/carry | Fixnums
fx<=? | Fixnums
fx<? | Fixnums
fx=? | Fixnums
fx>=? | Fixnums
fx>? | Fixnums
fxand | Fixnums
fxarithmetic-shift | Fixnums
fxarithmetic-shift-left | Fixnums
fxarithmetic-shift-right | Fixnums
fxbit-count | Fixnums
fxbit-field | Fixnums
fxbit-set? | Fixnums
fxcopy-bit | Fixnums
fxcopy-bit-field | Fixnums
fxdiv | Fixnums
fxdiv-and-mod | Fixnums
fxdiv0 | Fixnums
fxdiv0-and-mod0 | Fixnums
fxeven? | Fixnums
fxfirst-bit-set | Fixnums
fxif | Fixnums
fxior | Fixnums
fxlength | Fixnums
fxmax | Fixnums
fxmin | Fixnums
fxmod | Fixnums
fxmod0 | Fixnums
fxnegative? | Fixnums
fxnot | Fixnums
fxodd? | Fixnums
fxpositive? | Fixnums
fxreverse-bit-field | Fixnums
fxrotate-bit-field | Fixnums
fxxor | Fixnums
fxzero? | Fixnums

##### G

gappend | Generator operations
gc | System and platform
gcd | Arithmetic operations
gcombine | Generator operations
gconcatenate | Generator operations
gcons* | Generator operations
gdelete | Generator operations
gdelete-neighbor-dups | Generator operations
gdrop | Generator operations
gdrop-while | Generator operations
generate | Generator operations
generate-hmac-based-one-time-password | (rfc hotp) - HMAC-based One-Time Password library
generate-key-pair | Key operations
generate-key-pair | Asymmetric key operations
generate-mac | (rfc cmac) - CMAC library
generate-mac | Algorithms
generate-mac! | (rfc cmac) - CMAC library
generate-mac! | Algorithms
generate-password | Password policy operations
generate-private-key | Key operations
generate-private-key | Asymmetric key operations
generate-public-key | Key operations
generate-public-key | Asymmetric key operations
generate-secret-key | User level APIs
generate-secret-key | Key operations
generate-symmetric-key | Symmetric key operations
generate-symmetric-key | Symmetric key operations
generate-symmetric-key | Symmetric key operations
generate-temporaries | Syntax-case
generate-time-based-one-time-password | (rfc totp) - Time-based One-Time Password library
get-addrinfo | Addrinfo
get-bytevector-all | Binary input
get-bytevector-n | Binary input
get-bytevector-n! | Binary input
get-bytevector-some | Binary input
get-char | Textual input
get-data! | (odbc) - ODBC binding
get-datum | Textual input
get-dispatch-macro-character | (sagittarius reader) - reader macro library
get-enviromnent-variable | Process-Context library
get-enviromnent-variables | Process-Context library
get-f32 | Binary I/O
get-f64 | Binary I/O
get-keyword | Keywords
get-line | Binary I/O
get-line | Textual input
get-mac-address | System and platform
get-macro-character | (sagittarius reader) - reader macro library
get-optionals | (sagittarius control) - control library
get-optionals | (sagittarius control) - control library
get-output-bytevector | I/O
get-output-string | I/O
get-process-times | System and platform
get-s16 | Binary I/O
get-s16 | I/O
get-s32 | Binary I/O
get-s32 | I/O
get-s64 | Binary I/O
get-string-all | Textual input
get-string-n | Textual input
get-string-n! | Textual input
get-thread-times | System and platform
get-u16 | Binary I/O
get-u16 | I/O
get-u32 | Binary I/O
get-u32 | I/O
get-u64 | Binary I/O
get-u8 | Binary input
get-unpack | (binary pack) - Packing binary data
getpid | Low level APIs
gfilter | Generator operations
gfilter-map | Generator operations
gflatten | Generator operations
giota | Generator constructors
glet* | Generator operations
glet1 | Generator operations
gmap | Generator operations
gmerge | Generator operations
grange | Generator constructors
greatest-fixnum | Fixnums
gremove | Generator operations
gselect | Generator operations
gselect | Generator operations
gtake | Generator operations
gtake-while | Generator operations
guard | Exceptions
gunfold | Generator constructors

##### H

hash | User level APIs of hash operations
hash-algorithm | Hash operations
hash-algorithm? | Hash operations
hash-block-size | User level APIs of hash operations
hash-done! | Low level APIs of hash operations
hash-init! | Low level APIs of hash operations
hash-oid | Hash operations
hash-process! | Low level APIs of hash operations
hash-size | User level APIs of hash operations
hashtable->alist | (util hashtables) - Hashtable utilities
hashtable-clear | Procedures
hashtable-contains? | Procedures
hashtable-copy | Procedures
hashtable-delete! | Procedures
hashtable-entries | Procedures
hashtable-equivalence-function | Inspection
hashtable-fold | (util hashtables) - Hashtable utilities
hashtable-for-each | (util hashtables) - Hashtable utilities
hashtable-hash-function | Inspection
hashtable-keys | Procedures
hashtable-keys-list | Hashtables
hashtable-map | (util hashtables) - Hashtable utilities
hashtable-mutable? | Inspection
hashtable-ref | Procedures
hashtable-set! | Procedures
hashtable-size | Procedures
hashtable-type | Hashtables
hashtable-update! | Procedures
hashtable-values | Hashtables
hashtable-values-list | Hashtables
hashtable-weakness | Hashtables
hashtable? | Procedures
heap-clear! | Heap operations
heap-compare | Constructors, predicates and accessors
heap-delete! | Heap operations
heap-delete! | Heap operations
heap-empty? | Constructors, predicates and accessors
heap-entry-key | Constructors, predicates and accessors
heap-entry-value | Constructors, predicates and accessors
heap-entry-value-set! | Constructors, predicates and accessors
heap-entry? | Constructors, predicates and accessors
heap-extract-min! | Heap operations
heap-merge! | Heap operations
heap-min | Heap operations
heap-ref | Heap operations
heap-search | Heap operations
heap-set! | Heap operations
heap-size | Constructors, predicates and accessors
heap-update! | Heap operations
heap? | Constructors, predicates and accessors
hex-string->bytevector | (util bytevector) - Bytevector utility library
hkdf | KDF library - (sagittarius crypto kdfs)
HMAC | (rfc hmac) - HMAC library
host-not-found-error-node | Socket conditions
host-not-found-error-service | Socket conditions
host-not-found-error? | Socket conditions
hostname | Socket information
hotp | (rfc hotp) - HMAC-based One-Time Password library
html->shtml | High level APIs
html->sxml | High level APIs
html->sxml-0nf | High level APIs
html->sxml-1nf | High level APIs
html->sxml-2nf | High level APIs
html-doctype | (text html-lite) - Simple HTML document builder library
html-escape | (text html-lite) - Simple HTML document builder library
html-escape-string | (text html-lite) - Simple HTML document builder library
html: | (text html-lite) - Simple HTML document builder library
http-binary-receiver | Senders and receivers
http-blob-sender | (rfc http-connections) - HTTP client utilities
http-blob-sender | (rfc http-connections) - HTTP client utilities
http-blob-sender | (rfc http-connections) - HTTP client utilities
http-blob-sender | Senders and receivers
http-compose-form-data | Utilities
http-compose-query | Utilities
http-connection-config-builder | Ephemeral Connection Manager
http-connection-config? | Ephemeral Connection Manager
http-connection-secure? | (rfc http-connections) - HTTP client utilities
http-connection-server | (rfc http-connections) - HTTP client utilities
http-connection-server&port | (rfc http-connections) - HTTP client utilities
http-connection? | (rfc http-connections) - HTTP client utilities
http-delete | Request APIs
http-ephemeral-connection-manager? | Ephemeral Connection Manager
http-error? | (rfc http) - HTTP client
http-file-receiver | Senders and receivers
http-get | Request APIs
http-gzip-receiver | Senders and receivers
http-head | Request APIs
http-multipart-sender | Senders and receivers
http-null-receiver | (rfc http-connections) - HTTP client utilities
http-null-receiver | (rfc http-connections) - HTTP client utilities
http-null-receiver | (rfc http-connections) - HTTP client utilities
http-null-receiver | Senders and receivers
http-null-sender | (rfc http-connections) - HTTP client utilities
http-null-sender | (rfc http-connections) - HTTP client utilities
http-null-sender | (rfc http-connections) - HTTP client utilities
http-null-sender | Senders and receivers
http-oport-receiver | (rfc http-connections) - HTTP client utilities
http-oport-receiver | (rfc http-connections) - HTTP client utilities
http-oport-receiver | (rfc http-connections) - HTTP client utilities
http-oport-receiver | Senders and receivers
http-pooling-connection-config-builder | Pooling Connection Manager
http-pooling-connection-config? | Pooling Connection Manager
http-pooling-connection-manager? | Pooling Connection Manager
http-post | Request APIs
http-put | Request APIs
http-request | (rfc http-connections) - HTTP client utilities
http-request | Request APIs
http-request-context-builder | HTTP request context
http-request-context? | HTTP request context
http-request-payload? | HTTP request payload
http-string-receiver | Senders and receivers
http-string-sender | (rfc http-connections) - HTTP client utilities
http-string-sender | (rfc http-connections) - HTTP client utilities
http-string-sender | (rfc http-connections) - HTTP client utilities
http-string-sender | Senders and receivers
http-{bodied-methods} | HTTP request procedures
http-{bodied-methods} | HTTP request procedures
http-{bodied-methods} | HTTP request procedures
http-{nobody-methods} | HTTP request procedures
http-{nobody-methods} | HTTP request procedures
http1-connection? | (rfc http-connections) - HTTP client utilities
http2-binary-receiver | HTTP/2 receiver
http2-client-connection? | (rfc http2) - HTTP/2 client
http2-composite-sender | HTTP/2 sender
http2-connection? | (rfc http-connections) - HTTP client utilities
http2-data-receiver | HTTP/2 receiver
http2-data-sender | HTTP/2 sender
http2-get | High level APIs
http2-gzip-receiver | HTTP/2 receiver
http2-head | High level APIs
http2-headers-sender | HTTP/2 sender
http2-null-receiver | HTTP/2 receiver
http2-post | High level APIs
http2-request | High level APIs
http:client-builder | HTTP client
http:client-send | HTTP client
http:client-send-async | HTTP client
http:client-shutdown! | HTTP client
http:client? | HTTP client
http:headers-add! | HTTP request and response
http:headers-names | HTTP request and response
http:headers-ref | HTTP request and response
http:headers-ref* | HTTP request and response
http:headers-set! | HTTP request and response
http:headers? | HTTP request and response
http:make-headers | HTTP request and response
http:redirect | HTTP client
http:request-basic-auth | Authorization header value providers
http:request-basic-bearer | Authorization header value providers
http:request-builder | HTTP request and response
http:request? | HTTP request and response
http:response-body | HTTP request and response
http:response-cookies | HTTP request and response
http:response-headers | HTTP request and response
http:response-status | HTTP request and response
http:response? | HTTP request and response
http:version | HTTP client

##### I

i/o-decoding-error? | Transcoders
i/o-encoding-error? | Transcoders
i/o-error-filename | I/O condition types
i/o-error-port | I/O condition types
i/o-error-position | I/O condition types
i/o-error? | I/O condition types
i/o-file-already-exists-error? | I/O condition types
i/o-file-does-not-exist-error? | I/O condition types
i/o-file-is-read-only-error? | I/O condition types
i/o-file-protection-error? | I/O condition types
i/o-filename-error? | I/O condition types
i/o-invalid-position-error? | I/O condition types
i/o-port-error? | I/O condition types
i/o-read-error? | I/O condition types
i/o-write-error? | I/O condition types
id | Custom ports
identifier-syntax | Macro transformers
identifier-syntax | Macro transformers
identifier? | Syntax-case
if | Conditionals
if | Conditionals
if-car-sxpath | Wrappers
if-sxpath | Wrappers
imag-part | Arithmetic operations
implementation-restriction-violation? | Standard condition types
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-private-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
import-public-key | Asymmetric key operations
include | Inclusion
include-ci | Inclusion
inexact | Generic conversion
inexact->exect | R5RS compatibility
inexact? | Numerical type predicates
infinite? | Arithmetic operations
inflate-bytevector | (rfc zlib) - zlib compression library
info-log | Loggers
input-port->chunked-binary-input-port | Chunk buffered port
input-port-open? | I/O
input-port? | Input ports
input-receiver | Actor
inspect-object | (sagittarius debug) - Debugging support
integer->bytevector | Bytevector operations
integer->char | Characters
integer->pointer | Pointer operations
integer-valued? | Numerical type predicates
integer? | Numerical type predicates
integrity-error? | Cryptographic conditions
interaction-environment | Repl library
intersperse | (util list) - Extra list utility library
invalid-pem-format? | Conditions
ip-address | Socket information
ip-address->bytevector | IP address operations
ip-address->string | IP address operations
irritants-condition? | Standard condition types
is-a? | (clos user) -CLOS user APIs
is-prime? | Prime number operations
is_even | Extra functions
is_odd | Extra functions
istring? | String operations
iv-parameter? | Ciphers parameters

##### J

jiffies-per-second | Time library
jmespath | Scheme APIs
jmespath-compile-error? | Conditions
jmespath-error-arguments | Conditions
jmespath-error-expression | Conditions
jmespath-error? | Conditions
jmespath-parse-error? | Conditions
jmespath-runtime-error? | Conditions
json->jwe-header | JWE Header
json->jwk | JWK
json->jwk-set | JWK Set
json->jws-header | JWS Header
json->jwt-claims | JWT Claims
json->mutable-json | (text json mutable) - Mutable JSON
json->object | JSON object builder
json-diff | (text json patch) - JSON Patch
json-object-builder | JSON object builder
json-object-serializer | JSON object serializer
json-patch-compile-error? | (text json patch) - JSON Patch
json-patch-error-patch | (text json patch) - JSON Patch
json-patch-error-path | (text json patch) - JSON Patch
json-patch-error? | (text json patch) - JSON Patch
json-patch-error? | (text json patch) - JSON Patch
json-patch-path-illegal-type-error? | (text json patch) - JSON Patch
json-patch-path-not-found-error? | (text json patch) - JSON Patch
json-patcher | (text json patch) - JSON Patch
json-payload | HTTP request payload
json-pointer | (text json pointer) - JSON Pointer
json-read | (json) -- JSON parser library
json-read | (text json) -- JSON parser
json-read-error? | (text json) -- JSON parser
json-request->json-string | Converters
json-request-id | Accessors
json-request-method | Accessors
json-request-params | Accessors
json-request-payload? | HTTP request payload
json-request? | Predicates
json-response->json-string | Converters
json-response-id | Accessors
json-response-result | Accessors
json-response? | Predicates
json-schema->json-validator | JSON Schema validator
json-string->json-request | Constructors
json-string->json-response | Constructors
json-string->jwe-header | JWE Header
json-string->jwk | JWK
json-string->jwk-set | JWK Set
json-string->jws-header | JWS Header
json-string->jwt-claims | JWT Claims
json-string->object | JSON object builder
json-validator-validator | (text json validator) - JSON validator
json-validator? | (text json validator) - JSON validator
json-write | (json) -- JSON parser library
json-write | (text json) -- JSON parser
json-write-error? | (text json) -- JSON parser
json-write/normalized | (text json) -- JSON parser
json-write/pretty | (text json) -- JSON parser
json:builder? | JSON object builder
json:serializer? | JSON object serializer
jwe-header->json | JWE Header
jwe-header->json-string | JWE Header
jwe-header-builder | JWE Header
jwe-header? | JWE Header
jwe-object-authentication-tag | JWE Object
jwe-object-cipher-text | JWE Object
jwe-object-encrypted-key | JWE Object
jwe-object-header | JWE Object
jwe-object-iv | JWE Object
jwe-object? | JWE Object
jwe:encrypt | JWE Operations
jwe:encrypt | JWE Operations
jwe:encrypt | JWE Operations
jwe:parse | JWE Operations
jwe:serialize | JWE Operations
jwk->json | JWK
jwk->json-string | JWK
jwk->jwk-config | To JWK Conversion
jwk->octet-key | From JWK Conversion
jwk->private-key | From JWK Conversion
jwk->public-jwk | From JWK Conversion
jwk->public-key | From JWK Conversion
jwk-alg | JWK
jwk-config-builder | To JWK Conversion
jwk-key-ops | JWK
jwk-kid | JWK
jwk-kty | JWK
jwk-matcher:alg | JWK Matcher
jwk-matcher:crv | JWK Matcher
jwk-matcher:ec | JWK Matcher
jwk-matcher:key-ops | JWK Matcher
jwk-matcher:kid | JWK Matcher
jwk-matcher:kty | JWK Matcher
jwk-matcher:oct | JWK Matcher
jwk-matcher:okp | JWK Matcher
jwk-matcher:rsa | JWK Matcher
jwk-matcher:use | JWK Matcher
jwk-matcher:x5t | JWK Matcher
jwk-matcher:x5t-s256 | JWK Matcher
jwk-set->json | JWK Set
jwk-set->json-string | JWK Set
jwk-set-keys | JWK Set
jwk-set:find-key | JWK Set
jwk-set? | JWK Set
jwk-use | JWK
jwk-x5c | JWK
jwk-x5t | JWK
jwk-x5t-s256 | JWK
jwk-x5u | JWK
jwk:config? | To JWK Conversion
jwk? | JWK
jws-header->json | JWS Header
jws-header->json-string | JWS Header
jws-header-builder | JWS Header
jws-header? | JWS Header
jws-object-header | JWS Object
jws-object-payload | JWS Object
jws-object? | JWS Object
jws-signed-object-signature | JWS Object
jws-signed-object? | JWS Object
jws:parse | JWS Operations
jws:serialize | JWS Operations
jws:serialize | JWS Operations
jws:sign | JWS Operations
jws:verify | JWS Operations
jws:verify | JWS Operations
jwt-claims->json | JWT Claims
jwt-claims->json-string | JWT Claims
jwt-claims-aud | JWT Claims
jwt-claims-builder | JWT Claims
jwt-claims-custom-claims | JWT Claims
jwt-claims-exp | JWT Claims
jwt-claims-iat | JWT Claims
jwt-claims-iss | JWT Claims
jwt-claims-jti | JWT Claims
jwt-claims-nbf | JWT Claims
jwt-claims-sub | JWT Claims
jwt-claims? | JWT Claims
jwt-consumer-builder | JWT Consumer
jwt-consumer? | JWT Consumer
jwt:aud-required-validator | JWT Consumer
jwt:aud-validator | JWT Consumer
jwt:consume | JWT
jwt:exp-required-validator | JWT Consumer
jwt:exp-validator | JWT Consumer
jwt:exp-validator | JWT Consumer
jwt:exp-validator | JWT Consumer
jwt:iat-required-validator | JWT Consumer
jwt:iat-validator | JWT Consumer
jwt:iat-validator | JWT Consumer
jwt:iss-required-validator | JWT Consumer
jwt:iss-validator | JWT Consumer
jwt:jti-required-validator | JWT Consumer
jwt:nbf-required-validator | JWT Consumer
jwt:nbf-validator | JWT Consumer
jwt:nbf-validator | JWT Consumer
jwt:sub-required-validator | JWT Consumer
jwt:sub-validator | JWT Consumer

##### K

KASUMI | Cipher operations
key->jwk | To JWK Conversion
key->jwk | To JWK Conversion
key->oid | Asymmetric key operations
key-manager | Key Manager
key-manager? | Key Manager
key-pair-private | Asymmetric key operations
key-pair-public | Asymmetric key operations
key-pair? | Asymmetric key operations
key-provider-key-retrievers | Key Provider
key-provider? | Key Provider
key? | Key operations
keypair-private | Key operations
keypair-public | Key operations
keypair? | Key operations
keystore-aliases | Generic APIs
keystore-contains-alias? | Generic APIs
keystore-delete-entry! | Generic APIs
keystore-get-certificate | Generic APIs
keystore-get-certificate-chain | Generic APIs
keystore-get-creation-date | Generic APIs
keystore-get-key | Generic APIs
keystore-key-provider-add-key-retriever! | Key Provider
keystore-key-provider? | Key Provider
keystore-set-certificate! | Generic APIs
keystore-set-key! | Generic APIs
keystore? | Generic APIs
keyword->string | Keywords
keyword->symbol | Keywords
keyword? | Keywords
Khazad | Cipher operations

##### L

lambda | Procedures
latin-1-codec | Transcoders
lcm | Arithmetic operations
least-fixnum | Fixnums
length | Pairs and lists
length-policy? | Password policy operations
let | Iteration
let | Binding constructs
let* | Binding constructs
let*-values | Binding constructs
let-keywords | (sagittarius control) - control library
let-keywords | (sagittarius control) - control library
let-keywords* | (sagittarius control) - control library
let-keywords* | (sagittarius control) - control library
let-optionals* | (sagittarius control) - control library
let-optionals* | (sagittarius control) - control library
let-syntax | Differ from R6RS
let-syntax | Binding constructs for syntactic keywords
let-values | Binding constructs
let1 | (sagittarius control) - control library
letrec | Binding constructs
letrec* | Binding constructs
letrec-syntax | Differ from R6RS
letrec-syntax | Binding constructs for syntactic keywords
lexical-violation? | Standard condition types
library | Library form
list | Pairs and lists
list->deque | (util deque) - Deque
list->generator | Generator constructors
list->key-manager | Key Manager
list->lock-free-queue | Atomic
list->queue | (util queue) - Queue
list->string | Strings
list->vector | Vectors
list->x509-name | Distinguished name (DN)
list-copy | Lists
list-ref | Pairs and lists
list-set! | Lists
list-sort | Sorting
list-tail | Pairs and lists
list? | Pairs and lists
load | Load library
load-keystore | Generic APIs
load-keystore-file | Generic APIs
load-path | Load path
load-path | Load path
load-pkcs12-keystore | Keystore APIs
load-pkcs12-keystore-file | Keystore APIs
lock-free-queue | Atomic
lock-free-queue->list | Atomic
lock-free-queue-empty? | Atomic
lock-free-queue-get! | Atomic
lock-free-queue-pop! | Atomic
lock-free-queue-push! | Atomic
lock-free-queue-remove! | Atomic
lock-free-queue-remp! | Atomic
lock-free-queue-size | Atomic
lock-free-queue? | Atomic
log | Arithmetic operations
log | Arithmetic operations
log-arguments | Creating appenders
log-level | Creating appenders
log-message | Creating appenders
log-when | Creating appenders
log? | Creating appenders
logger-debug? | Loggers
logger-error? | Loggers
logger-fatal? | Loggers
logger-info? | Loggers
logger-trace? | Loggers
logger-warn? | Loggers
logger? | Loggers
lookahead-char | Textual input
lookahead-u8 | Binary input
looking-at | User level APIs for regular expression

##### M

mac->prf-provider | KDF library - (sagittarius crypto kdfs)
mac-done! | (rfc cmac) - CMAC library
mac-done! | Algorithms
mac-init! | (rfc cmac) - CMAC library
mac-init! | Algorithms
mac-mac-size | Algorithms
mac-oid | Algorithms
mac-process! | (rfc cmac) - CMAC library
mac-process! | Algorithms
mac-type | Algorithms
mac? | Algorithms
macroexpand | (sagittarius debug) - Debugging support
macroexpand-1 | (sagittarius debug) - Debugging support
macroexpand-n | (sagittarius debug) - Debugging support
magnitude | Arithmetic operations
make | (clos user) -CLOS user APIs
make-aad-parameter | Ciphers parameters
make-access-token | (net oauth) - OAuth library
make-addrinfo | Addrinfo
make-aes-key-unwrap | Key wrapping
make-aes-key-unwrap | Symmetric key operations
make-aes-key-wrap | Key wrapping
make-aes-key-wrap | Symmetric key operations
make-aeskw-jwe-decryptor | JWE Decryptors
make-aeskw-jwe-encryptor | JWE Encryptors
make-appender | Appenders
make-archive-input | Implementing archive implementation library
make-archive-output | Implementing archive implementation library
make-assertion-violation | Standard condition types
make-asymmetric-cipher | Asymmetric ciphers
make-async-logger | Loggers
make-atomic | Atomic
make-atomic | (sagittarius atomic) - Atomic operation
make-atomic-fixnum | Atomic
make-atomic-fixnum | (sagittarius atomic) - Atomic operation
make-atomic-flag | Atomic
make-atomic-flag | (sagittarius atomic) - Atomic operation
make-atomic-pair | Atomic
make-atomic-pair | (sagittarius atomic) - Atomic operation
make-authorization-uri | (net oauth) - OAuth library
make-base32-decoder | Low level APIs
make-base32-encoder | Low level APIs
make-base32hex-decoder | Low level APIs
make-base32hex-encoder | Low level APIs
make-base64-decoder | Low level APIs
make-base64-encoder | Low level APIs
make-ber-application-specific | Middle level user APIs
make-ber-constructed-octet-string | Middle level user APIs
make-ber-constructed-octet-string | Middle level user APIs
make-ber-null | Middle level user APIs
make-ber-sequence | Middle level user APIs
make-ber-set | Middle level user APIs
make-ber-tagged-object | Middle level user APIs
make-binary-pre-allocated-buffer | Binary pre-allocated buffer
make-block-cipher | Symmetric ciphers
make-bytevector | General operations
make-c-callback | Creating C functions
make-c-function | Creating C functions
make-c20pkw-jwe-decryptor | JWE Decryptors
make-c20pkw-jwe-encryptor | JWE Encryptors
make-camellia-key-unwrap | Symmetric key operations
make-camellia-key-wrap | Symmetric key operations
make-character-policy | Password policy operations
make-cipher | Cipher operations
make-cipher-parameter | Ciphers parameters
make-client-sftp-connection | Mid level APIs
make-client-socket | (net socket) - Modern Socket library
make-client-socket | (sagittarius socket) - socket library
make-client-tls-socket | Implementation notes:
make-client-tls-socket | (net socket) - Modern Socket library
make-cmac | (rfc cmac) - CMAC library
make-codec | I/O
make-composite-parameter | Mode parameters
make-condition-variable | Condition variable APIs
make-consumer-token | (net oauth) - OAuth library
make-counter-mode-parameter | Ciphers parameters
make-ctr-paramater | Mode parameters
make-custom-binary-input-port | Input ports
make-custom-binary-input/output-port | Input/output ports
make-custom-binary-output-port | Output ports
make-custom-random-generator | Custom random generator
make-custom-string-output-port | Output ports
make-custom-textual-input-port | Input ports
make-custom-textual-input/output-port | Input/output ports
make-daily-rolling-file-appender | Appenders
make-dbi-error | Conditions
make-dbi-sql-error | Conditions
make-dbi-unsupported | Conditions
make-deque | (util deque) - Deque
make-der-application-specific | Middle level user APIs
make-der-application-specific | Middle level user APIs
make-der-application-specific | Middle level user APIs
make-der-application-specific | Middle level user APIs
make-der-bit-string | Middle level user APIs
make-der-bit-string | Middle level user APIs
make-der-bmp-string | Middle level user APIs
make-der-bmp-string | Middle level user APIs
make-der-boolean | Middle level user APIs
make-der-boolean | Middle level user APIs
make-der-enumerated | Middle level user APIs
make-der-enumerated | Middle level user APIs
make-der-external | Middle level user APIs
make-der-external | Middle level user APIs
make-der-general-string | Middle level user APIs
make-der-general-string | Middle level user APIs
make-der-generalized-time | Middle level user APIs
make-der-generalized-time | Middle level user APIs
make-der-generalized-time | Middle level user APIs
make-der-ia5-string | Middle level user APIs
make-der-ia5-string | Middle level user APIs
make-der-ia5-string | Middle level user APIs
make-der-integer | Middle level user APIs
make-der-integer | Middle level user APIs
make-der-null | Middle level user APIs
make-der-numeric-string | Middle level user APIs
make-der-numeric-string | Middle level user APIs
make-der-numeric-string | Middle level user APIs
make-der-object-identifier | Middle level user APIs
make-der-object-identifier | Middle level user APIs
make-der-octet-string | Middle level user APIs
make-der-octet-string | Middle level user APIs
make-der-printable-string | Middle level user APIs
make-der-printable-string | Middle level user APIs
make-der-printable-string | Middle level user APIs
make-der-sequence | Middle level user APIs
make-der-sequence | Middle level user APIs
make-der-sequence | Middle level user APIs
make-der-set | Middle level user APIs
make-der-set | Middle level user APIs
make-der-set | Middle level user APIs
make-der-t61-string | Middle level user APIs
make-der-t61-string | Middle level user APIs
make-der-tagged-object | Middle level user APIs
make-der-tagged-object | Middle level user APIs
make-der-tagged-object | Middle level user APIs
make-der-universal-string | Middle level user APIs
make-der-utc-time | Middle level user APIs
make-der-utc-time | Middle level user APIs
make-der-utc-time | Middle level user APIs
make-der-utf8-string | Middle level user APIs
make-der-utf8-string | Middle level user APIs
make-der-visible-string | Middle level user APIs
make-der-visible-string | Middle level user APIs
make-digit-policy | Password policy operations
make-direct-jwe-decryptor | JWE Decryptors
make-direct-jwe-encryptor | JWE Encryptors
make-dispatch-macro-character | (sagittarius reader) - reader macro library
make-ecdh-es-jwe-decryptor | JWE Decryptors
make-ecdh-es-jwe-encryptor | JWE Encryptors
make-ecdh-jwe-decryptor | JWE Decryptors
make-ecdh-jwe-encryptor | JWE Encryptors
make-ecdsa-jws-signer | JWS Signers
make-ecdsa-jws-verifier | JWS Verifiers
make-eddsa-jws-signer | JWS Signers
make-eddsa-jws-verifier | JWS Verifiers
make-empty-attlist | Low-level parsing code
make-emv-tlv-parser | High level APIs
make-enumeration | Enumerations
make-eq-hashtable | Constructors
make-equal-hashtable | Hashtables
make-eqv-hashtable | Constructors
make-error | Standard condition types
make-error-expected | parse-error
make-error-message | parse-error
make-executor-future | Executor future
make-expected-result | parse-result
make-fdset | FD sets
make-file-appender | Appenders
make-filesystem-watcher | (sagittarius filewatch) - Monitoring filesystem
make-fork-join-executor | Fork join executor
make-fork-join-executor | Fork join executor
make-fork-join-executor | Fork join executor
make-fork-join-pool | Thread pool
make-gzip-receiver | HTTP/2 receiver
make-hashtable | Constructors
make-heap | Constructors, predicates and accessors
make-hint-addrinfo | Addrinfo
make-hmac-k-generator | DSA and ECDSA signature specific
make-host-not-found-error | Socket conditions
make-http-default-connection-manager | Connection Manager
make-http-ephemeral-connection-manager | Ephemeral Connection Manager
make-http-pooling-connection-manager | Pooling Connection Manager
make-http1-connection | (rfc http-connections) - HTTP client utilities
make-http2-client-connection | (rfc http2) - HTTP/2 client
make-http2-connection | (rfc http-connections) - HTTP client utilities
make-i/o-decoding-error | Transcoders
make-i/o-encoding-error | Transcoders
make-i/o-error | I/O condition types
make-i/o-file-already-exists-error | I/O condition types
make-i/o-file-does-not-exist-error | I/O condition types
make-i/o-file-is-read-only-error | I/O condition types
make-i/o-file-protection-error | I/O condition types
make-i/o-filename-error | I/O condition types
make-i/o-invalid-position-error | I/O condition types
make-i/o-port-error | I/O condition types
make-i/o-read-error | I/O condition types
make-i/o-write-error | I/O condition types
make-implementation-restriction-violation | Standard condition types
make-input-archive | Archive input
make-irritants-condition | Standard condition types
make-iv-paramater | Mode parameters
make-iv-parameter | Ciphers parameters
make-json-request | Constructors
make-json-validator | (text json validator) - JSON validator
make-jwk-set | JWK Set
make-jws-object | JWS Object
make-jws-object | JWE Object
make-key-manager | Key Manager
make-key-provider | Key Provider
make-keystore | Generic APIs
make-keystore-key-provider | Key Provider
make-keyword | Keywords
make-length-policy | Password policy operations
make-lexical-violation | Standard condition types
make-list | Lists
make-lock-free-queue | Atomic
make-log | Creating appenders
make-logger | Loggers
make-lower-case-policy | Password policy operations
make-mac | Algorithms
make-mac-jws-signer | JWS Signers
make-mac-jws-verifier | JWS Verifiers
make-max-uuid | Constructors
make-message-condition | Standard condition types
make-message-digest | Message Digest
make-message-result | parse-result
make-mqtt-broker | MQTT broker
make-mqtt-broker-config | MQTT broker
make-mtdeque | (util deque) - Deque
make-mtqueue | (util queue) - Queue
make-mutex | Mutex APIs
make-nil-uuid | Constructors
make-no-infinities-violation | Flonums
make-no-nans-violation | Flonums
make-non-continuable-violation | Standard condition types
make-nonce-parameter | Ciphers parameters
make-null-uuid | Constructors
make-output-archive | Archive output
make-padding-paramater | Mode parameters
make-parameter | Parameters
make-parse-position | parse-position
make-pbe-parameter | User level APIs
make-pbes2-jwe-decryptor | JWE Decryptors
make-pbes2-jwe-encryptor | JWE Encryptors
make-pkcs12-keystore | Keystore APIs
make-pkcs12-keystore | Keystore library - (sagittarius crypto keystores)
make-polar | Arithmetic operations
make-process | Low level APIs
make-queue | (util queue) - Queue
make-random-k-generator | DSA and ECDSA signature specific
make-rb-treemap | Predicate and constructurs
make-record-builder | (record builder) - Record builder
make-record-constructor-descriptor | Records procedural layer
make-record-type | (sagittarius record) - Extra record inspection library
make-record-type-descriptor | Records procedural layer
make-rectangular | Arithmetic operations
make-remote-debugger | (sagittarius debug) - Debugging support
make-result | parse-result
make-rfc3394-key-unwrap | Symmetric key operations
make-rfc3394-key-wrap | Symmetric key operations
make-rfc3686-paramater | Mode parameters
make-rolling-file-appender | Appenders
make-round-parameter | Ciphers parameters
make-rsa-jwe-decryptor | JWE Decryptors
make-rsa-jwe-encryptor | JWE Encryptors
make-rsa-jws-signer | JWS Signers
make-rsa-jws-verifier | JWS Verifiers
make-salt-parameter | Ciphers parameters
make-semaphore | Semaphore APIs
make-serious-condition | Standard condition types
make-server-config | Configuration
make-server-socket | (net socket) - Modern Socket library
make-server-socket | (sagittarius socket) - socket library
make-server-tls-socket | Implementation notes:
make-server-tls-socket | (net socket) - Modern Socket library
make-shared-priority-queue-channel-actor | Actor
make-shared-queue | Shared queues
make-shared-queue-channel-actor | Actor
make-shtml-entity | Low level APIs
make-signer | Signer
make-simple-future | Simple future
make-simple-server | Server
make-smtp-alternative | Middle level APIs
make-smtp-alternative-component | Middle level APIs
make-smtp-attachment | Middle level APIs
make-smtp-bcc | Middle level APIs
make-smtp-bcc | Middle level APIs
make-smtp-cc | Middle level APIs
make-smtp-cc | Middle level APIs
make-smtp-connection | High level APIs
make-smtp-from | Middle level APIs
make-smtp-from | Middle level APIs
make-smtp-mail | Middle level APIs
make-smtp-to | Middle level APIs
make-smtp-to | Middle level APIs
make-socket | Socket
make-socket-closed-error | Socket conditions
make-socket-closed-error | Socket conditions
make-socket-connection-error | Socket conditions
make-socket-error | Socket conditions
make-socket-port-error | Socket conditions
make-stream-cipher | Symmetric ciphers
make-string | Strings
make-string-hashtable | Hashtables
make-symbol-policy | Password policy operations
make-symmetric-key | Symmetric key operations
make-syntax-violation | Standard condition types
make-tag-length-parameter | Ciphers parameters
make-tag-parameter | Ciphers parameters
make-temporary-file | Temporary directory operations
make-thread | Thread APIs
make-thread-pool | Thread pool
make-thread-pool-executor | Thread pool executor
make-timer | (util timer) - Timer
make-transcoder | Transcoders
make-tweak-parameter | Ciphers parameters
make-undefined-violation | Standard condition types
make-upper-case-policy | Password policy operations
make-v1-uuid | Constructors
make-v3-uuid | Constructors
make-v4-uuid | Constructors
make-v5-uuid | Constructors
make-v6-uuid | Constructors
make-v7-uuid | Constructors
make-vector | Vectors
make-verifier | Verifier
make-violation | Standard condition types
make-warning | Standard condition types
make-weak-box | Weak box
make-weak-eq-hashtable | Weak hashtable
make-weak-eqv-hashtable | Weak hashtable
make-weak-vector | Weak vector
make-websocket | User level APIs
make-websocket-connection | WebSocket Connection
make-who-condition | Standard condition types
make-x509-algorithm-identifier | X.509 algorithm identifier
make-x509-certificate | (rfc x.509) - X.509 certificate utility library
make-x509-certificate | (rfc x.509) - X.509 certificate utility library
make-x509-challenge-password-attribute | X.509 attribute
make-x509-extension-request-attribute | X.509 attribute
make-x509-revoked-certificate | X.509 CRL
make-x509-validity | X.509 validity
make-xml-object | XML object
make-xml-token | Data Types
map | Pairs and lists
map-union | Basic converters and applicators
map-with-index | (util list) - Extra list utility library
markdown->html-converter | Markdown converter APIs
markdown->sxml-converter | Markdown converter APIs
markdown-conversion-options-builder | Markdown converter APIs
markdown-conversion-options? | Markdown converter APIs
markdown-converter:convert | Markdown converter APIs
markdown-converter:convert | Markdown converter APIs
markdown-converter:merge | Markdown converter APIs
markdown-converter? | Markdown converter APIs
markdown-node? | Markdown parser APIs
markdown-parser | Markdown parser APIs
markdown-parser-builder | Markdown extensions
markdown-parser-builder:build | Markdown extensions
markdown-parser-builder? | Markdown extensions
markdown-parser-error? | Deprecated APIs
markdown-parser-expected | Deprecated APIs
markdown-parser-position | Deprecated APIs
markdown-parser:parse | Markdown parser APIs
markdown-parser:parse | Markdown parser APIs
markdown-parser? | Markdown parser APIs
markdown-read | Deprecated APIs
markdown-sexp->string | Deprecated APIs
markdown-sexp->sxml | Deprecated APIs
match | Syntax
match | Syntax
match-lambda | Syntax
match-lambda* | Syntax
match-let | Syntax
match-let | Syntax
match-let* | Syntax
match-letrec | Syntax
max | Arithmetic operations
MD2 | Hash operations
MD4 | Hash operations
MD5 | Hash operations
member | List utilities
memory-order? | Atomic
memory-order? | (sagittarius atomic) - Atomic operation
memp | List utilities
memq | List utilities
memv | List utilities
merge-heaps | Heap operations
merge-heaps! | Heap operations
merge-result-errors | parse-error
merge-result-errors | parse-result
message-condition? | Standard condition types
message-digest-descriptor | Message Digest
message-digest-digest-size | Message Digest
message-digest-done | Message Digest
message-digest-done! | Message Digest
message-digest-init! | Message Digest
message-digest-process! | Message Digest
message-digest? | Message Digest
mgf-1 | PKCS operations
mgf-1 | RSA signature specific
mgf-1 | Asymmetric ciphers
min | Arithmetic operations
mod | Arithmetic operations
mod-expt | Misc arithmetic operations
mod-expt | Arithmetic operations
mod-inverse | Misc arithmetic operations
mod-inverse | Arithmetic operations
mod0 | Arithmetic operations
mode-descriptor-name | Symmetric ciphers
mode-descriptor? | Symmetric ciphers
mode-parameter? | Mode parameters
mode-pos | Basic converters and applicators
MODE_CBC | Cipher operations
MODE_CFB | Cipher operations
MODE_CTR | Cipher operations
MODE_ECB | Cipher operations
MODE_GCM | Cipher operations
MODE_OFB | Cipher operations
modulo | R5RS compatibility
mqtt-broker-start! | MQTT broker
mqtt-broker-stop! | MQTT broker
mqtt-connection? | (net mq mqtt) - MQTT library
mqtt-ping | (net mq mqtt) - MQTT library
mqtt-publish | (net mq mqtt) - MQTT library
mqtt-receive-message | (net mq mqtt) - MQTT library
mqtt-subscribe | (net mq mqtt) - MQTT library
mqtt-unsubscribe | (net mq mqtt) - MQTT library
mtdeque-max-length | (util deque) - Deque
mtdeque-room | (util deque) - Deque
mtqueue-max-length | (util queue) - Queue
mtqueue-room | (util queue) - Queue
mtqueue? | (util queue) - Queue
mutable-json->json | (text json mutable) - Mutable JSON
mutable-json-array-delete! | Mutable JSON array
mutable-json-array-insert! | Mutable JSON array
mutable-json-array-ref | Mutable JSON array
mutable-json-array-set! | Mutable JSON array
mutable-json-array-size | Mutable JSON array
mutable-json-array? | Mutable JSON array
mutable-json-not-found? | Mutable JSON object
mutable-json-object-contains? | Mutable JSON object
mutable-json-object-delete! | Mutable JSON object
mutable-json-object-merge! | Mutable JSON object
mutable-json-object-ref | Mutable JSON object
mutable-json-object-set! | Mutable JSON object
mutable-json-object? | Mutable JSON object
mutable-json? | (text json mutable) - Mutable JSON
mutex-lock! | Mutex APIs
mutex-name | Mutex APIs
mutex-specific | Mutex APIs
mutex-specific-set! | Mutex APIs
mutex-state | Mutex APIs
mutex-unlock! | Mutex APIs
mutex? | Mutex APIs

##### N

name-compare | Low-level parsing code
nan? | Arithmetic operations
native-endianness | General operations
native-eol-style | Transcoders
native-transcoder | Transcoders
negative? | Arithmetic operations
newline | Simple I/O
next-addrinfo | Addrinfo
next-entry! | Archive input
next-token | (text parse) - Parsing input stream
next-token-of | (text parse) - Parsing input stream
no-invinities-violation? | Flonums
no-nans-violation? | Flonums
node-closure | Converter combinators
node-eq? | Basic converters and applicators
node-equal? | Basic converters and applicators
node-join | Converter combinators
node-or | Converter combinators
node-reduce | Converter combinators
node-reverse | Basic converters and applicators
node-self | Converter combinators
node-trace | Basic converters and applicators
nodeset? | Basic converters and applicators
Noekeon | Cipher operations
non-continuable-violation? | Standard condition types
nonce-parameter? | Ciphers parameters
nongenerative | Records syntactic layer
not | Booleans
ntype-names?? | Basic converters and applicators
ntype-names?? | Basic converters and applicators
ntype-namespace-id?? | Basic converters and applicators
null-environment | R5RS compatibility
null-generator | Generator constructors
null-pointer | Pointer operations
null-pointer? | Pointer operations
null? | Pairs and lists
num-prams | (odbc) - ODBC binding
number->string | Numerical input and output
number->string | Numerical input and output
number? | Numerical type predicates
numerator | Arithmetic operations

##### O

oaep-encoding | Asymmetric ciphers
oauth-compose-query | (net oauth) - OAuth library
oauth-uri-encode | (net oauth) - OAuth library
object->json | JSON object serializer
object->json-string | JSON object serializer
object->pointer | Pointer operations
object-equal? | (clos user) -CLOS user APIs
obtain-access-token | (net oauth) - OAuth library
obtain-request-token | (net oauth) - OAuth library
octet-stream-payload | HTTP request payload
octet-stream-request-payload? | HTTP request payload
odbc-connection? | (odbc) - ODBC binding
odbc-env? | (odbc) - ODBC binding
odbc-statement? | (odbc) - ODBC binding
odd? | Arithmetic operations
oid->key-operation | Asymmetric key operations
on-server-start! | Server
on-server-stop! | Server
opaque | Records syntactic layer
open-amqp-connection | High level APIs
open-base32-decode-input-port | Decoding procedures
open-base32-decode-output-port | Decoding procedures
open-base32-encode-input-port | Encoding procedures
open-base32-encode-output-port | Encoding procedures
open-base32hex-decode-input-port | Decoding procedures
open-base32hex-decode-output-port | Decoding procedures
open-base32hex-encode-input-port | Encoding procedures
open-base32hex-encode-output-port | Encoding procedures
open-base64-decode-input-port | Decoding procedures
open-base64-decode-output-port | Decoding procedures
open-base64-encode-input-port | Encoding procedures
open-base64-encode-output-port | Encoding procedures
open-base64url-decode-input-port | Decoding procedures
open-base64url-decode-output-port | Decoding procedures
open-base64url-encode-input-port | Encoding procedures
open-base64url-encode-output-port | Encoding procedures
open-binary-input-file | File library
open-binary-output-file | File library
open-bytevector-input-port | Input ports
open-bytevector-output-port | Output ports
open-client-sftp-connection! | Mid level APIs
open-deflating-output-port | (rfc zlib) - zlib compression library
open-file-input-port | Input ports
open-file-input/output-port | Input/output ports
open-file-output-port | Output ports
open-http-connection! | (rfc http-connections) - HTTP client utilities
open-inflating-input-port | (rfc zlib) - zlib compression library
open-input-bytevector | I/O
open-input-file | Simple I/O
open-input-string | I/O
open-mqtt-connection | (net mq mqtt) - MQTT library
open-output-bytevector | I/O
open-output-file | Simple I/O
open-output-string | I/O
open-semaphore | Semaphore APIs
open-shared-library | Shared library operations
open-shared-memory | Inter-process communication (IPC)
open-string-input-port | Input ports
open-string-output-port | Output ports
or | Derived conditionals
output-port-buffer-mode | Output ports
output-port-open? | I/O
output-port? | Output ports
output-sender | Actor

##### P

pack | (binary pack) - Packing binary data
pack! | (binary pack) - Packing binary data
packrat-check | Parsing Combinators
packrat-check-base | Parsing Combinators
packrat-or | Parsing Combinators
packrat-parser | The parckrat-parser macro
packrat-unless | Parsing Combinators
pair? | Pairs and lists
parameterize | Parameters
parent | Extra functions
parent | Records syntactic layer
parent-rtd | Records syntactic layer
parse-error-empty | parse-error
parse-error-expected | parse-error
parse-error-message | parse-error
parse-error-position | parse-error
parse-error? | parse-error
parse-markdown | Deprecated APIs
parse-markdown | Markdown parser APIs
parse-markdown | Markdown parser APIs
parse-pem | Operations
parse-pem-file | Operations
parse-pem-string | Operations
parse-position->string | parse-position
parse-position-column | parse-position
parse-position-file | parse-position
parse-position-line | parse-position
parse-position>? | parse-position
parse-position? | parse-position
parse-result-error | parse-result
parse-result-next | parse-result
parse-result-semantic-value | parse-result
parse-result-successful? | parse-result
parse-result? | parse-result
parse-results-base | parse-results
parse-results-next | parse-results
parse-results-position | parse-results
parse-results-token-kind | parse-results
parse-results-token-kind | parse-results
parse-results-token-value | parse-results
parse-results? | parse-results
parse-uri-template | (rfc uri-template) - URI template
partition | List utilities
password-policies | Password policy operations
password-policy->generator | Generator integration
password-policy->predicate | Password policy operations
password-policy-char-set | Password policy operations
password-policy-compliant? | Password policy operations
password-policy-entropy | Password policy operations
password-policy-length | Password policy operations
password-policy? | Password policy operations
path-basename | Path operations
path-extension | Path operations
path-for-each | Path operations
path-map | Path operations
path-sans-extension | Path operations
pbe-with-md5-and-des | User level APIs
pbe-with-md5-and-rc2 | User level APIs
pbe-with-sha1-and-des | User level APIs
pbe-with-sha1-and-rc2 | User level APIs
pbkdf-1 | Low level APIs
pbkdf-1 | KDF library - (sagittarius crypto kdfs)
pbkdf-2 | Low level APIs
pbkdf-2 | KDF library - (sagittarius crypto kdfs)
peak-char | Simple I/O
peek-next-char | (text parse) - Parsing input stream
peek-u8 | I/O
pid->process | Low level APIs
pkcf12-kdf | KDF library - (sagittarius crypto kdfs)
PKCS-1-EME | PKCS operations
PKCS-1-EMSA | PKCS operations
pkcs-v1.5-padding | PKCS operations
pkcs1-emsa-pss-encode | PKCS operations
pkcs1-emsa-pss-encode | RSA signature specific
pkcs1-emsa-pss-verify | PKCS operations
pkcs1-emsa-pss-verify | RSA signature specific
pkcs1-emsa-v1.5-encode | PKCS operations
pkcs1-emsa-v1.5-encode | RSA signature specific
pkcs1-emsa-v1.5-verify | PKCS operations
pkcs1-emsa-v1.5-verify | RSA signature specific
pkcs1-v1.5-encoding | Asymmetric ciphers
pkcs12-keystore->bytevector | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-aliases | Keystore APIs
pkcs12-keystore-certificate-chain-ref | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-certificate-ref | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-certificate-set! | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-contains-alias? | Keystore APIs
pkcs12-keystore-delete-all-entries! | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-delete-entry! | Keystore APIs
pkcs12-keystore-delete-entry! | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-get-certificate | Keystore APIs
pkcs12-keystore-get-certificate-chain | Keystore APIs
pkcs12-keystore-get-key | Keystore APIs
pkcs12-keystore-private-key-ref | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-private-key-set! | Keystore library - (sagittarius crypto keystores)
pkcs12-keystore-set-certificate! | Keystore APIs
pkcs12-keystore-set-key! | Keystore APIs
pkcs12-keystore? | Keystore APIs
pkcs12-keystore? | Keystore library - (sagittarius crypto keystores)
pkcs5-padder | PKCS operations
pointer->bytevector | Pointer operations
pointer->integer | Pointer operations
pointer->object | Pointer operations
pointer->string | Pointer operations
pointer->uinteger | Pointer operations
pointer-address | Pointer operations
pointer-ref-c- | Pointer operations
pointer-set-c- | Pointer operations
pointer-set-c- | Pointer operations
pointer? | Pointer operations
pop! | (sagittarius control) - control library
port | Socket information
port->byte-generator | Generator constructors
port->char-generator | Generator constructors
port->mqtt-connection | (net mq mqtt) - MQTT library
port-closed? | I/O
port-eof? | Input ports
port-has-port-position? | Input and output ports
port-has-set-port-position!? | Input and output ports
port-position | Input and output ports
port-ready? | I/O
port-transcoder | Input and output ports
port? | Input and output ports
position | Custom ports
positive? | Arithmetic operations
pre-allocated-buffer-buffer | Pre-allocated buffer
pre-allocated-buffer-overflow-data | Conditions
pre-allocated-buffer-overflow? | Conditions
pre-allocated-buffer-reset! | Pre-allocated buffer
pre-allocated-buffer-size | Pre-allocated buffer
pre-allocated-buffer? | Pre-allocated buffer
pre-eb-as-boundary? | Conditions
prepare | (odbc) - ODBC binding
prepend-base | parse-results
prepend-semantic-value | parse-results
prime? | Prime number operations
print | (sagittarius debug) - Debugging support
print/ss | (sagittarius debug) - Debugging support
private-key-format | Asymmetric key operations
private-key-format? | Asymmetric key operations
private-key? | Key operations
private-key? | Key type
prng-descriptor-name | PRNG descriptor
prng-descriptor? | PRNG descriptor
prng-state | Random number operations
prng? | Random number operations
procedure? | Procedure predicate
process-active? | Low level APIs
process-call | Low level APIs
process-error-port | Low level APIs
process-input-port | Low level APIs
process-kill | Low level APIs
process-output-port | Low level APIs
process-run | Low level APIs
process-wait | Low level APIs
process? | Low level APIs
protocol | Records syntactic layer
pseudo-random | Random number operations
pseudo-random-generator | Random generator
pseudo-random? | Random number operations
public-key->subject-public-key-info | X.509 subject public key info
public-key-format | Asymmetric key operations
public-key-format? | Asymmetric key operations
public-key? | Key operations
public-key? | Key type
push! | (sagittarius control) - control library
push-future-handler | Thread pool executor
push-log | Creating appenders
put-bytevector | Binary output
put-char | Textual output
put-datum | Textual output
put-f32 | Binary I/O
put-f64 | Binary I/O
put-s16 | Binary I/O
put-s16 | I/O
put-s32 | Binary I/O
put-s32 | I/O
put-s64 | Binary I/O
put-string | Textual output
put-u16 | Binary I/O
put-u16 | I/O
put-u32 | Binary I/O
put-u32 | I/O
put-u64 | Binary I/O
put-u8 | Binary output

##### Q

quasiquote | Quasiquote
quasisyntax | Syntax-case
queue->list | (util queue) - Queue
queue-empty? | (util queue) - Queue
queue-front | (util queue) - Queue
queue-length | (util queue) - Queue
queue-pop! | (util queue) - Queue
queue-pop/wait! | (util queue) - Queue
queue-push! | (util queue) - Queue
queue-push-unique! | (util queue) - Queue
queue-push/wait! | (util queue) - Queue
queue-rear | (util queue) - Queue
queue? | (util queue) - Queue
quote | Quotation
quoted-printable-decode | Decoding procedures
quoted-printable-decode-string | Decoding procedures
quoted-printable-encode | Encoding procedures
quoted-printable-encode-string string | Encoding procedures
quotient | R5RS compatibility

##### R

raise | Exceptions
raise-continuable | Exceptions
raise-decode-error | Cryptographic conditions
raise-decrypt-error | Cryptographic conditions
raise-encode-error | Cryptographic conditions
raise-encrypt-error | Cryptographic conditions
random | Random number operations
random | Random number operations
random-generator-random-integer | Random generator
random-generator-randomize! | Random generator
random-generator-read-random-bytes | Random generator
random-generator-read-random-bytes! | Random generator
random-generator-state | Random generator
random-generator-state | Random generator
random-generator? | Random generator
random-prime | Prime number operations
random-seed-set! | Random number operations
rational-valued? | Numerical type predicates
rational? | Numerical type predicates
rationalize | Arithmetic operations
RC2 | Cipher operations
RC4 | Random number operations
RC5-32/12/b | Cipher operations
RC6-32/20/b | Cipher operations
read | Custom ports
read | Read library
read | Simple I/O
read-asn.1-object | High level user APIs
read-bytevector | I/O
read-bytevector! | I/O
read-char | Simple I/O
read-delimited-list | (sagittarius reader) - reader macro library
read-directory | File system operations
read-error? | I/O
read-jwe-header | JWE Header
read-jwe-header | JWE Header
read-jwk | JWK
read-jwk | JWK
read-jwk-set | JWK Set
read-jwk-set | JWK Set
read-jws-header | JWS Header
read-jws-header | JWS Header
read-jwt-claims | JWT Claims
read-jwt-claims | JWT Claims
read-line | I/O
read-object-from-json | JSON object builder
read-pkcs12-keystore | Keystore library - (sagittarius crypto keystores)
read-random-bytes | Random number operations
read-random-bytes! | Random number operations
read-string | (text parse) - Parsing input stream
read-string | I/O
read-sys-random | Random number operations
read-sys-random! | Random number operations
read-sys-random! | Random number operations
read-sys-random! | Random number operations
read-u8 | I/O
read-x509-certificate | X.509 certificate
read-x509-certificate-revocation-list | X.509 CRL
read-x509-certification-request | X.509 CSR
read/ss | I/O
real-part | Arithmetic operations
real-valued? | Numerical type predicates
real? | Numerical type predicates
receive | Builtin Syntax
receive-amqp-message | High level APIs
record-accessor | Records procedural layer
record-constructor | Records procedural layer
record-constructor-descriptor | Records syntactic layer
record-mutator | Records procedural layer
record-predicate | Records procedural layer
record-rtd | Records inspection
record-type-descriptor | Records syntactic layer
record-type-descriptor? | Records procedural layer
record-type-field-names | Records inspection
record-type-generative? | Records inspection
record-type-mutable? | Records inspection
record-type-name | Records inspection
record-type-opaque? | Records inspection
record-type-parent | Records inspection
record-type-rtd | (sagittarius record) - Extra record inspection library
record-type-rtd | (sagittarius record) - Extra record inspection library
record-type-sealed? | Records inspection
record-type-uid | Records inspection
record-type? | (sagittarius record) - Extra record inspection library
record? | Records inspection
ref | (sagittarius object) - Convenient refs and coercion procedures
regex | User level APIs for regular expression
regex-capture-count | Low level APIs for regular expression
regex-find | Low level APIs for regular expression
regex-group | Low level APIs for regular expression
regex-looking-at | Low level APIs for regular expression
regex-matcher | Low level APIs for regular expression
regex-matcher? | Low level APIs for regular expression
regex-matches | Low level APIs for regular expression
regex-pattern? | Low level APIs for regular expression
regex-replace-all | User level APIs for regular expression
regex-replace-all | User level APIs for regular expression
regex-replace-first | User level APIs for regular expression
regex-replace-first | User level APIs for regular expression
register-cipher-spi | Creating own cipher
register-ffi-finalizer | Finalizer operations
rejected-execution-error? | Thread pool executor
rejected-executor | Thread pool executor
rejected-future | Thread pool executor
release-filesystem-watcher! | (sagittarius filewatch) - Monitoring filesystem
remainder | R5RS compatibility
remote-debugger-port | (sagittarius debug) - Debugging support
remote-debugger-terminate! | (sagittarius debug) - Debugging support
remote-debugger? | (sagittarius debug) - Debugging support
remove | Extra functions
remove | List utilities
remove-from-deque! | (util deque) - Deque
remove-from-queue! | (util queue) - Queue
remove_entry | Extra functions
remp | List utilities
remq | List utilities
remv | List utilities
rename-file | File system operations
result-columns | (odbc) - ODBC binding
results->result | parse-results
reverse | Pairs and lists
reverse! | List operations
reverse-vector->generator | Generator constructors
rfc sftp | (rfc sftp) - SFTP library
rfc5322-dot-atom | Basic field parsers
rfc5322-field->tokens | Basic field parsers
rfc5322-header-ref | Parsing message headers
rfc5322-header-ref* | Parsing message headers
rfc5322-line-reader | Parsing message headers
rfc5322-next-token | Basic field parsers
rfc5322-parse-date | Specific field parsers
rfc5322-quoted-string | Basic field parsers
rfc5322-read-headers | Parsing message headers
rfc5322-skip-cfws | Basic field parsers
rfc5322-write-headers | Message constructors
RIPEMD-128 | Hash operations
RIPEMD-160 | Hash operations
RIPEMD-256 | Hash operations
RIPEMD-320 | Hash operations
rlet1 | (sagittarius control) - control library
rollback! | (odbc) - ODBC binding
rolling-file-appender? | Appenders
round | Arithmetic operations
round-parameter? | Ciphers parameters
row-count | (odbc) - ODBC binding
rpc-http-content-type | Transport methods
rpc-http-content-type | Http transport hook
rpc-http-method | Http transport hook
rpc-http-receiver | Http transport hook
rpc-http-request | Http transport
rpc-http-response-type | Transport methods
rpc-http-response-type | Http transport hook
rpc-http-sender | Http transport hook
rpc-http-unmarshall-message | Http transport hook
rpc-marshall-message | Message methods
rpc-marshall-message | Message framework
rpc-unmarshall-message | Message methods
rpc-unmarshall-message | Message framework
RSA | Cipher operations
rsa pkcs :12 | (rsa pkcs :12) - PKCS#12
run | High level APIs

##### S

SAFER+ | Cipher operations
SAFER-K128 | Cipher operations
SAFER-K64 | Cipher operations
SAFER-SK128 | Cipher operations
SAFER-SK64 | Cipher operations
sagittarius | Invoking Sagittarius
salt-parameter? | Ciphers parameters
scheme-report-environment | R5RS compatibility
scrypt | KDF library - (sagittarius crypto kdfs)
sealed | Records syntactic layer
secure-random | Random number operations
secure-random-generator | Random generator
secure-random-generator? | Random generator
secure-random? | Random number operations
SEED | Cipher operations
select-kids | Converter combinators
semaphore-close! | Semaphore APIs
semaphore-destroy! | Semaphore APIs
semaphore-name | Semaphore APIs
semaphore-post! | Semaphore APIs
semaphore-wait! | Semaphore APIs
semaphore? | Semaphore APIs
send-amqp-message | High level APIs
serious-condition? | Standard condition types
server-config | Server
server-config? | Configuration
server-detach-socket! | Socket detaching
server-start! | Server
server-stop! | Server
server-stopped? | Server
server-tls-socket-options-builder | (net socket) - Modern Socket library
server-tls-socket-options? | (net socket) - Modern Socket library
server? | Server
set! | Assignment
set-car! | Mutable pairs
set-cdr! | Mutable pairs
set-current-directory | File system operations
set-dispatch-macro-character | (sagittarius reader) - reader macro library
set-header! | Low level APIs
set-header! | Low level APIs
set-macro-character | (sagittarius reader) - reader macro library
set-pointer-value! | Pointer operations
set-port-position! | Input and output ports
set-position | Custom ports
sftp-binary-receiver | High level APIs
sftp-close | High level APIs
sftp-exists? | High level APIs
sftp-file-receiver | High level APIs
sftp-mkdir! | High level APIs
sftp-open | High level APIs
sftp-opendir | High level APIs
sftp-oport-receiver | High level APIs
sftp-read | High level APIs
sftp-readdir | High level APIs
sftp-readdir-as-filenames | High level APIs
sftp-readdir-as-longnames | High level APIs
sftp-remove! | High level APIs
sftp-rename! | High level APIs
sftp-rmdir! | High level APIs
sftp-write! | High level APIs
SHA-1 | Hash operations
SHA-224 | Hash operations
SHA-256 | Hash operations
SHA-3-224 | Hash operations
SHA-3-256 | Hash operations
SHA-3-384 | Hash operations
SHA-3-512 | Hash operations
SHA-384 | Hash operations
SHA-512 | Hash operations
SHA-512/224 | Hash operations
SHA-512/256 | Hash operations
shared-memory->bytevector | Inter-process communication (IPC)
shared-memory? | Inter-process communication (IPC)
shared-object-suffix | Shared library operations
shared-queue-clear! | Shared queues
shared-queue-empty? | Shared queues
shared-queue-find | Shared queues
shared-queue-get! | Shared queues
shared-queue-locked? | Shared queues
shared-queue-max-length | Shared queues
shared-queue-overflows? | Shared queues
shared-queue-put! | Shared queues
shared-queue-remove! | Shared queues
shared-queue-size | Shared queues
shared-queue? | Shared queues
shtml->html | High level APIs
shtml-comment-symbol | Low level APIs
shtml-decl-symbol | Low level APIs
shtml-empty-symbol | Low level APIs
shtml-end-symbol | Low level APIs
shtml-entity-symbol | Low level APIs
shtml-entity-value | Low level APIs
shtml-named-char-id | Low level APIs
shtml-numeric-char-id | Low level APIs
shtml-pi-symbol | Low level APIs
shtml-start-symbol | Low level APIs
shtml-text-symbol | Low level APIs
shtml-top-symbol | Low level APIs
shutdown-executor! | Generic Executor APIs
shutdown-input-port | (sagittarius socket) - socket library
shutdown-output-port | (sagittarius socket) - socket library
shutdown-port | (sagittarius socket) - socket library
sign-x509-certificate-revocation-list-template | X.509 CRL
sign-x509-certificate-template | X.509 certificate
sign-x509-certification-request-template | X.509 CSR
signer-init! | Signer
signer-process! | Signer
signer-sign! | Signer
signer-sign-message | Signer
signer? | Signer
simple-condition | Conditions
simple-future? | Simple future
simple-json-schema-error-reporter | JSON Schema validator
sin | Arithmetic operations
sint-list->bytevector | Operations on integers of arbitary size
sinteger->bytevector | Bytevector operations
size-of- | Sizes and aligns
size-of-c-struct | C struct operations
skip-until | (text parse) - Parsing input stream
skip-while | (text parse) - Parsing input stream
Skipjack | Cipher operations
sleeping-threads | (sagittarius debug) - Debugging support
slices | (util list) - Extra list utility library
slot-bound-using-class? | (clos user) -CLOS user APIs
slot-bound? | (clos user) -CLOS user APIs
slot-definition-name | (clos core) - CLOS core library
slot-definition-option | (clos core) - CLOS core library
slot-definition-options | (clos core) - CLOS core library
slot-ref | (sagittarius debug) - Debugging support
slot-ref | (clos user) -CLOS user APIs
slot-ref-using-accessor | (clos user) -CLOS user APIs
slot-ref-using-class | (clos user) -CLOS user APIs
slot-set! | (clos user) -CLOS user APIs
slot-set-using-accessor! | (clos user) -CLOS user APIs
slot-set-using-accessor! | (clos user) -CLOS user APIs
smtp-authenticate! | High level APIs
smtp-authentication-required? | High level APIs
smtp-bcc? | Middle level APIs
smtp-cc? | Middle level APIs
smtp-connect! | High level APIs
smtp-connect! | High level APIs
smtp-connection-authentication-methods | High level APIs
smtp-connection? | High level APIs
smtp-from? | Middle level APIs
smtp-login-authentication | High level APIs
smtp-mail->string | High level APIs
smtp-mail-add-attachment! | Middle level APIs
smtp-mail-add-header! | Middle level APIs
smtp-mail-add-recipent! | Middle level APIs
smtp-mail? | Middle level APIs
smtp-plain-authentication | High level APIs
smtp-recipient? | Middle level APIs
smtp-send! | High level APIs
smtp-to? | Middle level APIs
smtp:attachment | High level APIs
smtp:bcc | High level APIs
smtp:cc | High level APIs
smtp:from | High level APIs
smtp:header | High level APIs
smtp:mail | High level APIs
smtp:subject | High level APIs
smtp:to | High level APIs
SOBER-128 | Random number operations
sockaddr? | Addrinfo
socket-accept | Integration methods
socket-accept | Integration methods
socket-accept | (sagittarius socket) - socket library
socket-bind! | Socket
socket-blocking! | Socket
socket-close | Integration methods
socket-close | (sagittarius socket) - socket library
socket-closed-error? | Socket conditions
socket-closed-error? | Socket conditions
socket-connect! | Socket
socket-connect! | Socket
socket-connection-error? | Socket conditions
socket-error-port | Socket conditions
socket-error-select | Socket
socket-error-socket | Socket conditions
socket-error? | Socket conditions
socket-getsockopt | Socket
socket-info | Socket information
socket-info-values | Integration methods
socket-info-values | Socket information
socket-input-port | Integration methods
socket-input-port | (sagittarius socket) - socket library
socket-listen! | Socket
socket-name | Integration methods
socket-name | Socket information
socket-node | Socket information
socket-nonblocking! | Socket
socket-options->client-socket | (net socket) - Modern Socket library
socket-options-builder | (net socket) - Modern Socket library
socket-options? | (net socket) - Modern Socket library
socket-output-port | Integration methods
socket-output-port | (sagittarius socket) - socket library
socket-parameter-socket-hostname | Socket parameter
socket-parameter-socket-ip-address | Socket parameter
socket-parameter-socket-node | Socket parameter
socket-parameter-socket-service | Socket parameter
socket-parameter? | Socket parameter
socket-peer | Integration methods
socket-peer | Socket information
socket-port | Integration methods
socket-port | (sagittarius socket) - socket library
socket-port-error? | Socket conditions
socket-read-select | Socket
socket-recv | Integration methods
socket-recv | (sagittarius socket) - socket library
socket-recvfrom | Socket
socket-select | Socket
socket-select! | Socket
socket-send | Integration methods
socket-send | (sagittarius socket) - socket library
socket-sendto | Socket
socket-service | Socket information
socket-set-read-timeout! | Socket
socket-setsockopt! | Socket
socket-shutdown | (sagittarius socket) - socket library
socket-write-select | Socket
socket? | (sagittarius socket) - socket library
sockets->fdset | FD sets
split-at* | (util list) - Extra list utility library
split-key | Key operations
sqrt | Arithmetic operations
square | Numerical operations
ssax:assert-token | Higher-level parsers and scanners
ssax:complete-start-tag | Low-level parsing code
ssax:handle-parsed-entity | Low-level parsing code
ssax:largest-unres-name | Low-level parsing code
ssax:make-elem-parser | Highest-level parsers: XML to SXML
ssax:make-parser | Highest-level parsers: XML to SXML
ssax:make-pi-parser | Highest-level parsers: XML to SXML
ssax:ncname-starting-char? | Low-level parsing code
ssax:Prefix-XML | Low-level parsing code
ssax:read-attributes | Low-level parsing code
ssax:read-cdata-body | Low-level parsing code
ssax:read-char-data | Higher-level parsers and scanners
ssax:read-char-ref | Low-level parsing code
ssax:read-external-id | Low-level parsing code
ssax:read-markup-token | Low-level parsing code
ssax:read-NCName | Low-level parsing code
ssax:read-pi-body-as-string | Low-level parsing code
ssax:read-QName | Low-level parsing code
ssax:resolve-name | Low-level parsing code
ssax:reverse-collect-str | Highest-level parsers: XML to SXML
ssax:reverse-collect-str-drop-ws | Highest-level parsers: XML to SXML
ssax:scan-Misc | Higher-level parsers and scanners
ssax:skip-internal-dtd | Low-level parsing code
ssax:skip-pi | Low-level parsing code
ssax:skip-S | Low-level parsing code
ssax:uri-string->symbol | Low-level parsing code
ssax:xml->sxml | Highest-level parsers: XML to SXML
standard-error-port | Output ports
standard-input-port | Input ports
standard-output-port | Output ports
statement-open? | (odbc) - ODBC binding
store-keystore | Generic APIs
store-keystore-to-file | Generic APIs
store-pkcs12-keystore | Keystore APIs
store-pkcs12-keystore-to-file | Keystore APIs
stream-cipher-descriptor-aead? | Symmetric ciphers
stream-cipher-descriptor? | Symmetric ciphers
stream-cipher? | Symmetric ciphers
string | Strings
string->bytevector | Transcoders
string->generator | Generator constructors
string->istring | String operations
string->keyword | Keywords
string->list | Strings
string->markdown | Deprecated APIs
string->symbol | Symbols
string->u8-set | U8 sets
string->utf16 | Operation on strings
string->utf32 | Operation on strings
string->utf8 | Operation on strings
string->uuid | Converters
string->vector | Vectors
string->x509-name | Distinguished name (DN)
string-append | Strings
string-ci-hash | Hash functions
string-ci<=? | Strings
string-ci<? | Strings
string-ci=? | Strings
string-ci>=? | Strings
string-ci>? | Strings
string-concatenate | String operations
string-copy | Strings
string-copy! | Strings
string-downcase | Strings
string-fill! | Mutable strings
string-foldcase | Strings
string-for-each | Strings
string-hash | Hash functions
string-length | Strings
string-map | Strings
string-nfc | Strings
string-nfd | Strings
string-nfkc | Strings
string-nfkd | Strings
string-prefix? | (sagittarius debug) - Debugging support
string-ref | Strings
string-scan | String operations
string-set! | Mutable strings
string-split | User level APIs for regular expression
string-suffix? | (sagittarius debug) - Debugging support
string-titlecase | Strings
string-upcase | Strings
string<=? | Strings
string<? | Strings
string=? | Strings
string>=? | Strings
string>? | Strings
string? | Strings
subject-public-key-info->bytevector | X.509 subject public key info
subject-public-key-info->public-key | X.509 subject public key info
subject-public-key-info? | X.509 subject public key info
substring | Strings
subtype? | (clos user) -CLOS user APIs
sxml->object | High level APIs
sxml->xml-object | XML object
sxml-object-builder | High level APIs
sxml:ancestor | XPath axes. An order in resulting nodeset is preserved
sxml:ancestor-or-self | XPath axes. An order in resulting nodeset is preserved
sxml:attr-list | Extensions
sxml:attribute | Extensions
sxml:boolean | SXML counterparts to W3C XPath Core Functions
sxml:child | Extensions
sxml:child-elements | Popular short cuts
sxml:child-nodes | Popular short cuts
sxml:complement | Basic converters and applicators
sxml:descendant | XPath axes. An order in resulting nodeset is preserved
sxml:descendant-or-self | XPath axes. An order in resulting nodeset is preserved
sxml:element? | Basic converters and applicators
sxml:equal? | Equality comparison
sxml:equality-cmp | Equality comparison
sxml:filter | Basic converters and applicators
sxml:following | XPath axes. An order in resulting nodeset is preserved
sxml:following-sibling | XPath axes. An order in resulting nodeset is preserved
sxml:id | SXML counterparts to W3C XPath Core Functions
sxml:id-alist | lookup by a value of ID type attribute
sxml:namespace | XPath axes. An order in resulting nodeset is preserved
sxml:node? node | Extensions
sxml:not-equal? | Equality comparison
sxml:number | SXML counterparts to W3C XPath Core Functions
sxml:parent | Extensions
sxml:preceding | XPath axes. An order in resulting nodeset is preserved
sxml:preceding-sibling | XPath axes. An order in resulting nodeset is preserved
sxml:relational-cmp | Relational comparison
sxml:string | SXML counterparts to W3C XPath Core Functions
sxml:string-value | SXML counterparts to W3C XPath Core Functions
sxpath | Abbreviated SXPath
symbol->keyword | Keywords
symbol->string | Symbols
symbol-hash | Hash functions
symbol<=? | Symbols
symbol<? | Symbols
symbol=? | Symbols
symbol>=? | Symbols
symbol>? | Symbols
symbol? | Symbols
symmetric-cipher-descriptor-max-key-length | Symmetric ciphers
symmetric-cipher-descriptor-min-key-length | Symmetric ciphers
symmetric-cipher-descriptor? | Symmetric ciphers
symmetric-cipher? | Symmetric ciphers
symmetric-key-value | Symmetric key operations
symmetric-key? | Key type
sync-process-read | Middle level APIs
syntax | Syntax-case
syntax->datum | Syntax-case
syntax-case | Syntax-case
syntax-error | Error objects
syntax-rules | Macro transformers
syntax-violation | Syntax-case
syntax-violation-form | Standard condition types
syntax-violation-subform | Standard condition types
syntax-violation? | Standard condition types
System | Random number operations

##### T

tag-length-parameter? | Ciphers parameters
tag-parameter? | Ciphers parameters
take* | (util list) - Extra list utility library
take-after | Basic converters and applicators
take-until | Basic converters and applicators
tan | Arithmetic operations
temporary-directory | Temporary directory operations
terminate-logger | Loggers
terminate-logger | Loggers
terminate-logger! | Loggers
terminate-oldest-handler | Thread pool executor
terminated-future | Future
textual-port? | Input and output ports
thread->pretty-backtrace-string | (sagittarius debug) - Debugging support
thread-backtrace | (sagittarius debug) - Debugging support
thread-backtrace->pretty-string | (sagittarius debug) - Debugging support
thread-backtrace-arguments | (sagittarius debug) - Debugging support
thread-backtrace-free-variables | (sagittarius debug) - Debugging support
thread-backtrace-local-variables | (sagittarius debug) - Debugging support
thread-backtrace-procedure | (sagittarius debug) - Debugging support
thread-backtrace-source | (sagittarius debug) - Debugging support
thread-backtrace-type | (sagittarius debug) - Debugging support
thread-current-procedure | (sagittarius debug) - Debugging support
thread-interrupt! | Thread APIs
thread-join! | Thread APIs
thread-name | (sagittarius debug) - Debugging support
thread-name | Thread APIs
thread-pool-executor-available? | Thread pool executor
thread-pool-executor-execute-future! | Thread pool executor
thread-pool-executor-max-pool-size | Thread pool executor
thread-pool-executor-pool-size | Thread pool executor
thread-pool-executor-shutdown! | Thread pool executor
thread-pool-executor? | Thread pool executor
thread-pool-push-task! | Thread pool
thread-pool-release! | Thread pool
thread-pool-size | Thread pool
thread-pool-thread | Thread pool
thread-pool-thread-id | Thread pool
thread-pool-thread-task-running? | Thread pool
thread-pool-thread-terminate! | Thread pool
thread-pool-wait-all! | Thread pool
thread-pool? | Thread pool
thread-resume! | Thread APIs
thread-sleep! | Thread APIs
thread-specific | (sagittarius debug) - Debugging support
thread-specific | Thread APIs
thread-specific-set! | Thread APIs
thread-start! | Thread APIs
thread-state | Thread APIs
thread-suspend! | Thread APIs
thread-terminate! | Thread APIs
thread-yield! | Thread APIs
thread? | (sagittarius debug) - Debugging support
thread? | Thread APIs
thunk->future | Actor
thunk->future | Actor
Tiger-192 | Hash operations
time | Debugging aid
timer-cancel! | (util timer) - Timer
timer-exists? | (util timer) - Timer
timer-remove! | (util timer) - Timer
timer-reschedule! | (util timer) - Timer
timer-schedule! | (util timer) - Timer
timer-start! | (util timer) - Timer
timer-state | (util timer) - Timer
timer-stop! | (util timer) - Timer
timer? | (util timer) - Timer
timezone | (sagittarius timezone) - Timezone
timezone-dst? | (sagittarius timezone) - Timezone
timezone-name | (sagittarius timezone) - Timezone
timezone-name-list | (sagittarius timezone) - Timezone
timezone-offset | (sagittarius timezone) - Timezone
timezone-raw-offset | (sagittarius timezone) - Timezone
timezone-short-name | (sagittarius timezone) - Timezone
timezone? | (sagittarius timezone) - Timezone
tls-client-handshake | Implementation notes:
tls-server-handshake | Implementation notes:
tls-socket-accept | Implementation notes:
tls-socket-close | Implementation notes:
tls-socket-closed? | Implementation notes:
tls-socket-info-values | Implementation notes:
tls-socket-input-port | Implementation notes:
tls-socket-name | Implementation notes:
tls-socket-options-builder | (net socket) - Modern Socket library
tls-socket-options? | (net socket) - Modern Socket library
tls-socket-output-port | Implementation notes:
tls-socket-peer | Implementation notes:
tls-socket-peer | Implementation notes:
tls-socket-port | Implementation notes:
tls-socket-recv | Implementation notes:
tls-socket-send | Implementation notes:
tlv->bytevector | High level APIs
tlv-builder | Custom object builder
tlv-components | High level APIs
tlv-data | High level APIs
tlv-object? | High level APIs
tlv-tag | High level APIs
token-consumer | (net oauth) - OAuth library
top-parse-position | parse-position
totp | (rfc totp) - Time-based One-Time Password library
trace-log | Loggers
transcoded-port | (sagittarius io) - Extra IO library
transcoded-port | Input and output ports
transcoder-codec | Transcoders
transcoder-eol-style | Transcoders
transcoder-error-handlingmode | Transcoders
tree->string | (text tree) - Lightweight text generation
treemap->alist | Conversions
treemap-clear! | Basic operations
treemap-contains? | Basic operations
treemap-copy | Basic operations
treemap-delete! | Basic operations
treemap-entries | Keys and values
treemap-entries-list | Keys and values
treemap-fold | Iterations
treemap-for-each | Iterations
treemap-keys | Keys and values
treemap-keys-list | Keys and values
treemap-map | Iterations
treemap-ref | Basic operations
treemap-set! | Basic operations
treemap-size | Basic operations
treemap-update! | Basic operations
treemap-values | Keys and values
treemap-values-list | Keys and values
treemap? | Predicate and constructurs
truncate | Arithmetic operations
truncate-quotient | Numerical operations
truncate-remainder | Numerical operations
truncate/ | Numerical operations
tweak-parameter? | Ciphers parameters
Twofish | Cipher operations

##### U

u8-list->bytevector | Operation on bytes and octets
u8-ready? | I/O
u8-set-contains? | U8 sets
u8-set? | U8 sets
u8? | U8 sets
uint-list->bytevector | Operations on integers of arbitary size
uinteger->bytevector | Bytevector operations
uname | System and platform
undefined-violation? | Standard condition types
unique | Extra functions
unless | Control structures
unpack | (binary pack) - Packing binary data
unpack | (binary pack) - Packing binary data
unquote | Quasiquote
unquote-splicing | Quasiquote
unregister-ffi-finalizer | Finalizer operations
unsyntax | Syntax-case
unsyntax-splicing | Syntax-case
unwind-protect | (sagittarius control) - control library
update-parse-position | parse-position
uri-compose | (rfc uri) - Parse and construct URIs
uri-decode | (rfc uri) - Parse and construct URIs
uri-decode-string | (rfc uri) - Parse and construct URIs
uri-decompose-authority | (rfc uri) - Parse and construct URIs
uri-decompose-hierarchical | (rfc uri) - Parse and construct URIs
uri-encode | (rfc uri) - Parse and construct URIs
uri-encode-string | (rfc uri) - Parse and construct URIs
uri-merge | (rfc uri) - Parse and construct URIs
uri-parse | (rfc uri) - Parse and construct URIs
uri-scheme&specific | (rfc uri) - Parse and construct URIs
url-server&path | Utilities
utf-16-codec | Transcoders
utf-8-codec | Transcoders
utf16->string | Operation on strings
utf32->string | Operation on strings
utf8->string | Operation on strings
uuid->bytevector | Converters
uuid->string | Converters
uuid->urn-format | Converters
uuid=? | Predicates
uuid? | Predicates

##### V

v1-uuid? | Predicates
v3-uuid? | Predicates
v4-uuid? | Predicates
v5-uuid? | Predicates
v6-uuid? | Predicates
v7-uuid? | Predicates
validate-json | (text json validator) - JSON validator
validate-x509-certificate | X.509 certificate
validate-x509-certificate-revocation-list | X.509 CRL
validate-x509-certification-request | X.509 CSR
validation-report-object | Custom error reporter
validation-report-path | Custom error reporter
validation-report-schema-path | Custom error reporter
values | Control features
vector | Vectors
vector->generator | Generator constructors
vector->list | Vectors
vector->string | Vectors
vector-append | Vector operations
vector-append | Vectors
vector-concatenate | Vector operations
vector-copy | Vector operations
vector-copy | Vectors
vector-copy! | Vectors
vector-fill! | Vectors
vector-filter | (util vector) - Extra vector utility library
vector-find | (util vector) - Extra vector utility library
vector-for-each | Vectors
vector-length | Vectors
vector-map | Vectors
vector-ref | Vectors
vector-ref | Vectors
vector-remove | (util vector) - Extra vector utility library
vector-reverse | Vector operations
vector-reverse! | Vector operations
vector-sort | Sorting
vector-sort! | Sorting
vector? | Vectors
verifier-init! | Verifier
verifier-process! | Verifier
verifier-verify! | Verifier
verifier-verify-signature | Verifier
verifier? | Verifier
verify | (rfc x.509) - X.509 certificate utility library
verify-mac | (rfc cmac) - CMAC library
verify-mac | Algorithms
violation? | Standard condition types

##### W

wait-finishing-handler | Thread pool executor
wait-server-stop! | Server
warn-log | Loggers
warning? | Standard condition types
weak-box-empty? | Weak box
weak-box-ref | Weak box
weak-box-set! | Weak box
weak-box? | Weak box
weak-hashtable-copy | Weak hashtable
weak-hashtable-delete! | Weak hashtable
weak-hashtable-keys-list | Weak hashtable
weak-hashtable-ref | Weak hashtable
weak-hashtable-set! | Weak hashtable
weak-hashtable-shrink | Weak hashtable
weak-hashtable-values-list | Weak hashtable
weak-hashtable? | Weak hashtable
weak-vector-length | Weak vector
weak-vector-ref | Weak vector
weak-vector-set! | Weak vector
weak-vector? | Weak vector
websocket-close | User level APIs
websocket-compose-close-status | WebSocket Messages
websocket-connection-close! | WebSocket Connection
websocket-connection-closed? | WebSocket Connection
websocket-connection-handshake! | WebSocket Connection
websocket-connection-pong-queue | WebSocket Connection
websocket-connection? | WebSocket Connection
websocket-error? | Conditions
websocket-on-binary-message | Event handling
websocket-on-close | Event handling
websocket-on-error | Event handling
websocket-on-open | Event handling
websocket-on-text-message | Event handling
websocket-open | User level APIs
websocket-parse-close-status | WebSocket Messages
websocket-ping | User level APIs
websocket-receive | WebSocket Messages
websocket-receive-fragments | WebSocket Messages
websocket-send | User level APIs
websocket-send-binary | WebSocket Messages
websocket-send-close | WebSocket Messages
websocket-send-ping | WebSocket Messages
websocket-send-pong | WebSocket Messages
websocket-send-text | WebSocket Messages
websocket? | User level APIs
when | Control structures
WHIRLPOOL | Hash operations
who-condition? | Standard condition types
with-args | (getopt) - Parsing command-line options
with-error-to-port | (sagittarius io) - Extra IO library
with-exception-handler | Exceptions
with-input-from-file | Simple I/O
with-input-from-port | (sagittarius io) - Extra IO library
with-input-from-string | (sagittarius io) - Extra IO library
with-library | (sagittarius control) - control library
with-output-to-file | Simple I/O
with-output-to-port | (sagittarius io) - Extra IO library
with-output-to-string | (sagittarius io) - Extra IO library
with-syntax | Syntax-case
with-syntax* | (sagittarius control) - control library
write | Custom ports
write | Write library
write | Simple I/O
write-bytevector | I/O
write-char | Simple I/O
write-jwe-header | JWE Header
write-jwe-header | JWE Header
write-jwk | JWK
write-jwk | JWK
write-jwk-set | JWK Set
write-jwk-set | JWK Set
write-jws-header | JWS Header
write-jws-header | JWS Header
write-jwt-claims | JWT Claims
write-jwt-claims | JWT Claims
write-object | (clos user) -CLOS user APIs
write-object-as-json | JSON object serializer
write-pkcs12-keystore | Keystore library - (sagittarius crypto keystores)
write-shared | Write library
write-shtml-as-html | High level APIs
write-simple | Write library
write-string | I/O
write-tlv | High level APIs
write-tree | (text tree) - Lightweight text generation
write-u8 | I/O
write-x509-certificate | X.509 certificate
write-x509-certificate-revocation-list | X.509 CRL
write-x509-certification-request | X.509 CSR
write/ss | I/O

##### X

X-Tea | Cipher operations
x-www-form-urlencoded-payload | HTTP request payload
x-www-form-urlencoded-request-payload? | HTTP request payload
x509-algorithm-identifier-oid | X.509 algorithm identifier
x509-algorithm-identifier-parameters | X.509 algorithm identifier
x509-algorithm-identifier? | X.509 algorithm identifier
x509-attribute->x509-extension-list | X.509 attribute
x509-attribute-of | X.509 attribute
x509-attribute-type | X.509 attribute
x509-attribute-values | X.509 attribute
x509-attribute? | X.509 attribute
x509-certificate->bytevector | X.509 certificate
x509-certificate-expired? | X.509 certificate
x509-certificate-extensions | X.509 certificate
x509-certificate-get-issuer-dn | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-not-after | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-not-before | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-public-key | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-serial-number | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-signature | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-signature-algorithm | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-subject-dn | (rfc x.509) - X.509 certificate utility library
x509-certificate-get-version | (rfc x.509) - X.509 certificate utility library
x509-certificate-issuer-dn | X.509 certificate
x509-certificate-public-key | X.509 certificate
x509-certificate-revocation-list->bytevector | X.509 CRL
x509-certificate-revocation-list-crl-extensions | X.509 CRL
x509-certificate-revocation-list-issuer | X.509 CRL
x509-certificate-revocation-list-issuer-validator | X.509 CRL
x509-certificate-revocation-list-next-update | X.509 CRL
x509-certificate-revocation-list-revoked-certificates | X.509 CRL
x509-certificate-revocation-list-signature | X.509 CRL
x509-certificate-revocation-list-signature-algorithm | X.509 CRL
x509-certificate-revocation-list-signature-validator | X.509 CRL
x509-certificate-revocation-list-template-builder | X.509 CRL
x509-certificate-revocation-list-template? | X.509 CRL
x509-certificate-revocation-list-this-update | X.509 CRL
x509-certificate-revocation-list? | X.509 CRL
x509-certificate-revoked? | X.509 certificate
x509-certificate-serial-number | X.509 certificate
x509-certificate-signature | X.509 certificate
x509-certificate-signature-algorithm | X.509 certificate
x509-certificate-signature-validator | X.509 certificate
x509-certificate-signed-by? | X.509 certificate
x509-certificate-subject-dn | X.509 certificate
x509-certificate-template-builder | X.509 certificate
x509-certificate-template? | X.509 certificate
x509-certificate-validity | X.509 certificate
x509-certificate-validity-validator | X.509 certificate
x509-certificate-version | X.509 certificate
x509-certificate? | (rfc x.509) - X.509 certificate utility library
x509-certificate? | X.509 certificate
x509-certification-request->bytevector | X.509 CSR
x509-certification-request-attributes | X.509 CSR
x509-certification-request-public-key | X.509 CSR
x509-certification-request-signature | X.509 CSR
x509-certification-request-signature-algorithm | X.509 CSR
x509-certification-request-signature-validator | X.509 CSR
x509-certification-request-subject | X.509 CSR
x509-certification-request-template-builder | X.509 CSR
x509-certification-request-template? | X.509 CSR
x509-certification-request-version | X.509 CSR
x509-certification-request? | X.509 CSR
x509-extension-critical? | X.509 extension
x509-extension-id | X.509 extension
x509-extension-of | X.509 extension
x509-extension-value | X.509 extension
x509-extension? | X.509 extension
x509-name | Distinguished name (DN)
x509-name->string | Distinguished name (DN)
x509-name? | Distinguished name (DN)
x509-revoked-certificate-crl-entry-extensions | X.509 CRL
x509-revoked-certificate-revocation-date | X.509 CRL
x509-revoked-certificate-serial-number | X.509 CRL
x509-revoked-certificate? | X.509 CRL
x509-validity-not-after | X.509 validity
x509-validity-not-before | X.509 validity
x509-validity? | X.509 validity
xml-object | XML object
xml-object-attributes | XML object
xml-object-contents | XML object
xml-object-name | XML object
xml-object? | XML object
xml-token-head | Data Types
xml-token-kind | Data Types
xml-token? | Data Types

##### Y

yaml-read | (text yaml) -- YAML parser
yaml-write | (text yaml) -- YAML parser
yaml-write | (text yaml) -- YAML parser
Yarrow | Random number operations

##### Z

Z_BEST_COMPRESSION | (rfc zlib) - zlib compression library
Z_BEST_SPEED | (rfc zlib) - zlib compression library
Z_DEFAULT_COMPRESSION | (rfc zlib) - zlib compression library
Z_DEFAULT_STRATEGY | (rfc zlib) - zlib compression library
Z_FILTERED | (rfc zlib) - zlib compression library
Z_FIXED | (rfc zlib) - zlib compression library
Z_HUFFMAN_ONLY | (rfc zlib) - zlib compression library
Z_NO_COMPRESSION | (rfc zlib) - zlib compression library
Z_RLE | (rfc zlib) - zlib compression library
zero? | Arithmetic operations
zlib-error-message | (rfc zlib) - zlib compression library
zlib-error? | (rfc zlib) - zlib compression library
zone-offset->timezones | (sagittarius timezone) - Timezone
zone-offset->timezones* | (sagittarius timezone) - Timezone