Specifications of SigScheme
===========================


General
-------

64-bit data models
~~~~~~~~~~~~~~~~~~

  - Supports LL64, LLP64, LP64 and ILP64 (storage-fatty)

  - storage-compact does not support any of above (yet)

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.

Integer range
~~~~~~~~~~~~~

Only supports fixnum, and its range is varied by the user-selected
underlying storage implementation. The range can be known via SRFI-77
compatible `(least-fixnum)` and `(greatest-fixnum)`.


R5RS conformance
----------------

Proper tail recursion
~~~~~~~~~~~~~~~~~~~~~

Supported.

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.

Macros
~~~~~~

The hygienic macros are fully supported.

Numbers
~~~~~~~

Only integer part is implemented.

Characters
~~~~~~~~~~

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

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.

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

Constant string
~~~~~~~~~~~~~~~

SigScheme treats string literals as constant as specified in R5RS.

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

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

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

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.

.SCM_STRICT_R5RS disabled
================================================================
    sscm> (null? ())
    #t
================================================================

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

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")
----------------------------------------------------------------

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

Environment specifiers
~~~~~~~~~~~~~~~~~~~~~~

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

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

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.

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

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

Syntaxes/procedures not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

System interface
^^^^^^^^^^^^^^^^

  - *optional procedure:* transcript-on filename
  - *optional procedure:* transcript-off


SRFI conformance
----------------

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 made available after some preparations).


SRFI-23 Error Reporting Mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The `error` procedure throws a SigScheme-specific error object in cooperate
with "SRFI-34 Exception Handling for Programs". 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.

.Error objects are also caught as a list
================================================================
  sscm> (guard (obj ((pair? obj) obj)) (error "reason" 1 2 3))
  #<error "reason" 1 2 3>
================================================================


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

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 shared index starts with #1 (not #0).

.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#)
================================================================

SRFI-48 Intermediate Format Strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

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

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

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

SRFI-75 R6RS Unicode data
~~~~~~~~~~~~~~~~~~~~~~~~~

  - quoted-symbol by vertical bar (|) is not supported yet

FIXME


SIOD compatibility
------------------

  - #f and '()

  - let and let* bindings

  - '=' predicate
