# Specifications of SigScheme

## 1. General

### 1.1. 64-bit data models

Supports LL64, LLP64, LP64 and ILP64 on both storage-fatty and storage-compact.

### 1.2. Addressable memory space

Ordinary storage implementation can address any Scheme object scattered on whole memory space. Both storage-fatty and storage-compact have no limitation on any 32 and 64-bit data models. But it may be limited if a storage implementation is designed to do so for some specific advantages, as like GNU Emacs' 28-bit tagged pointer does.

### 1.3. Integer range

Current implementation only supports fixnum, and its range varies by the user-selected underlying storage implementation. The range can be known via R6RS (R5.91RS) compatible `(fixnum-width)`, `(least-fixnum)` and `(greatest-fixnum)`.

## 2. R5RS conformance

### 2.1. Proper tail recursion

Supported. But the conformance of `eval` procedure is uncertain. See the comments of `scm_p_eval()` and `rec-by-eval` of `test-tail-rec.scm` for further information about `eval`.

### 2.2. Continuations

Limited to nested use due to its setjmp/longjmp implementation. If a continuation that is not an ancestor of current continuation called, all continuation objects lying between the curent and the common ancestor of the destination are invalidated. Calling an invalidated continuation object causes an error.

### 2.3. Macros

The hygienic macros are fully supported. But although the macro expansion engine itself works well and can be expected as R5RS-conformant, its integration into SigScheme is not fully validated yet. It is likely having a problem on identifier references.

### 2.4. Numbers

SigScheme supports only the integer part of the numerical tower.

#### 2.4.1. Literals

SigScheme recognizes only these limited part of numerical forms of "7.1.1 Lexical structure" section of R5RS. Other valid R5RS forms for numbers produce errors.

      <number> --> <num 2>| <num 8>
           | <num 10>| <num 16>

      <num R> --> <prefix R> <complex R>
      <complex R> --> <real R>
      <real R> --> <sign> <ureal R>
      <ureal R> --> <uinteger R>
      <uinteger R> --> <digit R>+ #*   ;; '#' must not occur
      <prefix R> --> <radix R>

      <sign> --> <empty>  | + |  -
      <radix 2> --> #b
      <radix 8> --> #o
      <radix 10> --> <empty> | #d
      <radix 16> --> #x
      <digit 2> --> 0 | 1
      <digit 8> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
      <digit 10> --> <digit>
      <digit 16> --> <digit 10> | a | b | c | d | e | f
      <digit> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

SigScheme accepts only lower case alphabets as radices as follows. But hexadecimal digits can be written as either lower or upper.

      #b11  ==>  3
      #B11  ==>  error
      #xa1  ==>  161
      #Xa1  ==>  error
      #xAb  ==>  171

SigScheme uses a fixed-size buffer for number literals parsing. Due to the implementation, it can accept only one optional 0 prefix for maximum-length binary number literals. Two or more 0 prefixes causes an error as follows.

      ;; storage-compact on ILP32 env

      (greatest-fixnum)                      ==> 2147483647
      #b11111111000000001111111100000000     ==> 4278255360
      #b011111111000000001111111100000000    ==> 4278255360
      #b0011111111000000001111111100000000   ==> error
      #b00011111111000000001111111100000000  ==> error

#### 2.4.2. Optional procedures

The procedures - and / support following optional form.

      6.2.5 Numerical operations

      optional procedure: - z1 z2 ...
      optional procedure: / z1 z2 ...

### 2.5. Characters

All character category-sensitive procedures and predicates (such as char-upcase) work correctly only in ASCII range. i.e. Neither Unicode processing specified in SRFI-75 nor other non-Unicode multibyte character processing are supported in such procedures/predicates.

### 2.6. Case-insensitive character comparison

SigScheme's case-insensitive comparison conforms to the foldcase'ed comparison described in SRFI-75 and SRFI-13, although R5RS does not specify comparison between alphabetic and non-alphabetic char.

See the description in operations.c for further details.

### 2.7. Case-sensitive identifiers

SigScheme does distinguish letter case in indentifiers. Although case insensitivity is required in R5RS as follows, it is hard to accept for the our application.

      2. Lexical conventions

      Upper and lower case forms of a letter are never distinguished except
      within character and string constants. For example, `Foo' is the same
      identifier as `FOO', and #x1AB is the same number as #X1ab.

### 2.8. Constant string

SigScheme treats string literals as constant as specified in R5RS.

Example: constant string

    sscm> (string-set! "foo" 0 #\F)
    Error: in string-set!: attempted to modify immutable string: "foo"

    sscm> (string-set! (string-copy "foo") 0 #\F)
    "Foo"

### 2.9. Constant list

SigScheme inhibits modification of constant list object by default as specified in R5RS, if the storage implementation suports it. storage-fatty supports it, but storage-compact does not due to no bit space for pair object.

The behavior can be changed by `SCM_CONST_LIST_LITERAL`.

      4.1.2 Literal expressions

          `(quote <datum>)' may be abbreviated as '<datum>. The two notations
          are equivalent in all respects.

          'a                                     ==>  a
          '#(a b c)                              ==>  #(a b c)
          '()                                    ==>  ()
          '(+ 1 2)                               ==>  (+ 1 2)
          '(quote a)                             ==>  (quote a)
          ''a                                    ==>  (quote a)

          As noted in section 3.4 Storage model, it is an error to alter a
          constant (i.e. the value of a literal expression) using a mutation
          procedure like `set-car!' or `string-set!'.

      6.3.2 Pairs and lists

      procedure: set-car! pair obj

          Stores obj in the car field of pair. The value returned by `set-car!'
          is unspecified.

          (define (g) '(constant-list))
          (set-car! (g) 3)                       ==>  error

### 2.10. Constant vector

SigScheme inhibits modification of constant vector object by default as specified in R5RS, if the storage implementation suports it. storage-fatty supports it, but storage-compact is not yet.

The behavior can be changed by `SCM_CONST_VECTOR_LITERAL`.

      6.3.6 Vectors

      procedure: vector-set! vector k obj

          (vector-set! '#(0 1 2) 1 "doe")
                    ==>  error  ; constant vector

### 2.11. Quote-less null list

SigScheme allows quote-less null list by default for convenience and performance. But it can be error as specified in R5RS, when `SCM_STRICT_R5RS` is enabled.

Example: SCM_STRICT_R5RS disabled

    sscm> (null? ())
    #t

Example: SCM_STRICT_R5RS enabled

    sscm> (null? ())
    Error: eval: () is not a valid R5RS form. use '() instead

### 2.12. Quote-less vector literal

Sigscheme inhibits quote-less vector literal by default, as specified in R5RS.

The behavior can be changed by `SCM_STRICT_VECTOR_FORM`.

      6.3.6 Vectors

      Vectors are written using the notation #(obj ...). For example, a vector
      of length 3 containing the number zero in element 0, the list `(2 2 2 2)'
      in element 1, and the string `"Anna"' in element 2 can be written as
      following:

      #(0 (2 2 2 2) "Anna")

      Note that this is the external representation of a vector, not an
      expression evaluating to a vector. Like list constants, vector constants
      must be quoted:

      '#(0 (2 2 2 2) "Anna")
                ==>  #(0 (2 2 2 2) "Anna")

Example: vector literals

    sscm> #(1 2 3)
    Error: eval: #() is not a valid R5RS form. use '#() instead
    sscm> '#(1 2 3)
    #(1 2 3)

### 2.13. Environment specifiers

`(null-environment)` and `(scheme-report-environment)` does not return correct environemnt specified in R5RS. Current implementation returns same object of `(interaction-environment)`.

### 2.14. Internal definitions

SigScheme strictly conforms to the internal definitions defined in R5RS (cited below) if `SCM_STRICT_DEFINE_PLACEMENT` is enabled (default). It can be disabled to get the syntax loosen, shrink the footprint and reduce runtime cost.

      5.2.2 Internal definitions

      Definitions may occur at the beginning of a <body> (that is, the body of a
      lambda, let, let*, letrec, let-syntax, or letrec-syntax expression or that of
      a definition of an appropriate form). Such definitions are known as internal
      definitions as opposed to the top level definitions described above.

### 2.15. Superfluous arguments

Superfluous or dotted arguments are strictly rejected as an error if `SCM_STRICT_ARGCHECK` is enabled. Otherwise ignored. Resource-sensitive apprication could disable it.

Example: SCM_STRICT_ARGCHECK enabled

    sscm> (car '(1 2) 3 4)
    Error: in (function call): superfluous argument(s): (3 4)
    sscm> (symbol? 'foo . #t)
    Error: in (function call): improper argument list terminator: #t
    sscm> (+ 3 4 . 5)
    Error: in (reduction): improper argument list terminator: 5

Example: SCM_STRICT_ARGCHECK disabled

    sscm> (car '(1 2) 3 4)
    1
    sscm> (symbol? 'foo . #t)
    #t
    sscm> (+ 3 4 . 5)
    7

### 2.16. Syntaxes/procedures not implemented

Following R5RS syntaxes and procedures are not implemented (yet).

#### 2.16.1. Numbers

- procedure: complex? obj

- procedure: real? obj

- procedure: rational? obj

- procedure: exact? z

- procedure: inexact? z

- library procedure: gcd n1 …

- library procedure: lcm n1 …

- procedure: numerator q

- procedure: denominator q

- procedure: floor x

- procedure: ceiling x

- procedure: truncate x

- procedure: round x

- library procedure: rationalize x y

- procedure: exp z

- procedure: log z

- procedure: sin z

- procedure: cos z

- procedure: tan z

- procedure: asin z

- procedure: acos z

- procedure: atan z

- procedure: atan y x

- procedure: sqrt z

- procedure: expt z1 z2

- procedure: make-rectangular x1 x2

- procedure: make-polar x3 x4

- procedure: real-part z

- procedure: imag-part z

- procedure: magnitude z

- procedure: angle z

- procedure: exact->inexact z

- procedure: inexact->exact z

#### 2.16.2. Promises

- library syntax: delay <expression>

- library procedure: force promise

#### 2.16.3. System interface

- optional procedure: transcript-on filename

- optional procedure: transcript-off

## 3. SRFI conformance

### 3.1. SRFI-1 List Library

Although a C implementation `module-srfi1.c` is existing, it is still broken and should not use for production codes. To get SRFI-1 working with SigScheme, use SLIB version of the library (will be made available after some preparations).

### 3.2. SRFI-22 Running Scheme Scripts on Unix

SigScheme only supports the prelude line interpretation. All options written in the line are applied as same as commandline invocation of sscm. But the `main` procedure invocation is not supported (yet).

Example: Prelude line is interpreted as follows

    #! /usr/bin/env sscm -C UTF-8
    ...

    ==> Character encoding for the file is changed to UTF-8 temporarily.

### 3.3. SRFI-23 Error Reporting Mechanism

If srfi-34 is provided, the `error` procedure throws a SigScheme-specific error object in cooperate with "SRFI-34 Exception Handling for Programs". Otherwise it simply calls scm_fatal_error(). Since the error objects are represented as a list, be careful on catching an exception based on its type. If you want to distinguish the error objects from ordinary lists, use SigScheme-specific `%%error-object?` predicate.

Example: Error objects are also caught as a list

    sscm> (guard (obj ((pair? obj) obj)) (error "reason" 1 2 3))
    #<error "reason" 1 2 3>

Example: Error object internal

    sscm> (define err (guard (err (#t err)) (error "reason" 1 2 3)))
    err
    sscm> err
    #<error "reason" 1 2 3>
    sscm> (pair? err)
    #t
    sscm> (car err)
    (#<undef> . #<undef>)
    sscm> (%%error-object? err)
    #t

### 3.4. SRFI-28 Basic Format Strings

SigScheme fully supports SRFI-28. A directive-less tilde at end of a format string causes an error as same as the reference implementation of SRFI-28.

Example: SigScheme

    (format "~")   ==> error
    (format "a~")  ==> error

### 3.5. SRFI-38 External Representation for Data with Shared Structure

Only `write-with-shared-structure` is implemented and `read-with-shared-structure` is not. The optional alias `write/ss` described in SRFI-38 is also defined. The optional `optarg` argument is simply ignored.

The shared index starts with #1 (not #0).

Example: Shared index starts with #1

    sscm> (define lst (list 'a 'b))
    lst
    sscm> (set-cdr! lst lst)
    #1=(a . #1#)
    sscm> lst
    #1=(a . #1#)

### 3.6. SRFI-48 Intermediate Format Strings

SigScheme fully supports SRFI-48.

The d part of ~w,dF directive is acceptable, but completely ignored on output format. Since SigScheme only supports integer currently, number is always formatted as integer even if the d part is specified.

Example: Proper behavior

    (format "~3F"   3)  ==> "  3"
    (format "~3,2F" 3)  ==> "3.00"

Example: SigScheme

    (format "~3F"   3)  ==> "  3"
    (format "~3,2F" 3)  ==> "  3"

Although the reference implementation of SRFI-48 allows directive-less tilde at end of a format string, SigScheme rejects it as an error since it decreases user-code portability, and is confusable due to that the behavior is different to the reference implementation of SRFI-28.

Example: Reference implementation of SRFI-48

    (format "~")   ==> "~"
    (format "a~")  ==> "a~"

Example: SigScheme

    (format "~")   ==> error
    (format "a~")  ==> error

### 3.7. SRFI-60 Integer as Bits

Only following procedures are implemented.

- Bitwise Operations

  - procedure: logand n1 …

  - procedure: bitwise-and n1 …

  - procedure: logior n1 …

  - procedure: bitwise-ior n1 …

  - procedure: logxor n1 …

  - procedure: bitwise-xor n1 …

  - procedure: lognot n

  - procedure: bitwise-not n

  - procedure: bitwise-if mask n0 n1

  - procedure: bitwise-merge mask n0 n1

  - procedure: logtest j k

  - procedure: any-bits-set? j k

And the others listed below are not.

- Integer Properties

  - procedure: logcount n

  - procedure: bit-count n

  - procedure: integer-length n

  - procedure: log2-binary-factors n

  - procedure: first-set-bit n

- Bit Within Word

  - procedure: logbit? index n

  - procedure: bit-set? index n

  - procedure: copy-bit index from bit

- Field of Bits

  - procedure: bit-field n start end

  - procedure: copy-bit-field to from start end

  - procedure: ash n count

  - procedure: arithmetic-shift n count

  - procedure: rotate-bit-field n count start end

  - procedure: reverse-bit-field n start end

- Bits as Booleans

  - procedure: integer->list k len

  - procedure: integer->list k

  - procedure: list->integer list

  - procedure: booleans->integer bool1 …

### 3.8. SRFI-75 R6RS Unicode data

SRFI-75 is partially implemented. But since SRFI-75 had already been obsoleted, it is not validated deeply. It will be replaced with stable R6RS implementation once the specifications have been stabilized

#### 3.8.1. Current SRFI-75 status

- Supports Unicode character literals such as #\λ

- Supports #xXX, #\uXXXX and #\UXXXXXXXX literals

- Supports Unicode identifiers (lacks character category validation)

- Supports all named chars such as #\backspace, #\esc, and #\nul

- Quoted-symbol by vertical bar (such as '|-symbol|) is not supported

#### 3.8.2. TODOs

- Remove #\uXXXX and #\UXXXXXXXX literals

- Support variable-length #\xXX literal

- Support character category validation for identifiers

- Disable #\newline on R6RS-compatible mode

- Confirm symbol escape syntax (not defined in R6RS yet)

## 4. SIOD compatibility

FIXME: describe them.

- #f and '()

- let and let* bindings

- = predicate