Extensions to the standard

[[tags: manual]]

[[toc:]]

== Extensions to the R5RS standard

=== Identifiers

Identifiers may contain special characters if delimited with
{{| ... |}}.

=== Brackets and braces

The brackets {{[ ... ]}} and the braces {{ { ... } }} are
provided as an alternative syntax for {{( ... )}}.  A number of reader
extensions is provided. 

=== Non-standard procedures and syntax

CHICKEN provides numerous non-standard procedures. See the manual
sections on the included library modules ([[Included modules]]) for
more information.  Here we only document {{cond-expand}} because it is
always present in a module, even without imports.

==== cond-expand

<macro>(cond-expand FEATURE-CLAUSE ...)</macro>

Expands by selecting feature clauses. This form is allowed to appear in non-toplevel expressions.

Predefined feature-identifiers are "situation" specific:

; compile : {{chicken}}, {{compiling}}, {{library}}, {{eval}}, {{extras}}, {{regex}}, {{srfi-0}}, {{srfi-2}}, {{srfi-4}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-11}}, {{srfi-12}}, {{srfi-15}}, {{srfi-16}}, {{srfi-17}}, {{srfi-23}}, {{srfi-26}}, {{srfi-28}}, {{srfi-30}}, {{srfi-31}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}

; load : {{chicken}}, {{extras}}, {{srfi-0}}, {{srfi-2}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-12}}, {{srfi-17}}, {{srfi-23}}, {{srfi-28}}, {{srfi-30}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}. {{library}} is implicit.

; eval : {{csi}}, {{chicken}}, {{extras}}, {{srfi-0}}, {{srfi-2}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-11}}, {{srfi-12}}, {{srfi-15}}, {{srfi-16}}, {{srfi-17}}, {{srfi-23}}, {{srfi-26}}, {{srfi-28}}, {{srfi-30}}, {{srfi-31}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}. {{library}} is implicit.

The following feature-identifier classes are available in all situations: {{(machine-byte-order)}}, {{(machine-type)}}, {{(software-type)}}, {{(software-version)}}, where the actual feature-identifier is platform dependent.

In addition the following feature-identifiers may exist: {{cross-chicken}}, {{dload}}, {{manyargs}}, {{ptables}}.

For further information, see the documentation for
[[http://srfi.schemers.org/srfi-0/srfi-0.html|SRFI-0]].


=== User defined character names

User defined character names are supported. See
{{char-name}}. Characters can be given
in hexadecimal notation using the ''#\xXX'' syntax where ''XX'' specifies the 
character code. Character codes above 255 are supported and can be read (and are
written) using the ''#\uXXXX'' and ''#\UXXXXXXXX'' notations.

Non-standard characters names supported are {{#\tab}}, {{#\linefeed}}, {{#\return}}, {{#\alarm}},
{{#\vtab}}, {{#\nul}}, {{#\page}}, {{#\esc}}, {{#\delete}} and {{#\backspace}}.

=== Special characters in strings

CHICKEN supports special characters preceded with
a backslash ''\'' in quoted string
constants. ''\n'' denotes the newline-character,
''\r'' carriage return, ''\b''
backspace, ''\t'' TAB, ''\v'' vertical TAB, ''\a'' alarm, ''\f'' formfeed,
''\xXX'' a character with the code {{XX}} in hex and 
''\uXXXX'' (and ''\UXXXXXXXX'') a unicode character with the code {{XXXX}}.
The latter is encoded in UTF-8 format.

== Non-standard read syntax

=== Escapes in symbols

{{| ... |}} may be used to escape a sequence of characters when reading a symbol.
{{\X}} escapes a single character in a symbols name:

  (symbol->string '|abc def|)       =>   "abc def"
  (symbol->string '|abc||def|)      =>   "abcdef"
  (symbol->string '|abc|xyz|def|)   =>   "abcxyzdef"
  (symbol->string '|abc\|def|)      =>   "abc|def"
  (symbol->string 'abc\ def)        =>   "abc def"

=== Multiline Block Comment

<read>#|</read>

 #| ... |# 

A multiline ''block'' comment. May be nested. Implements [[http://srfi.schemers.org/srfi-30/srfi-30.html|SRFI-30]].

=== Expression Comment

<read>#;</read>

 #;EXPRESSION

Treats {{EXPRESSION}} as a comment.  That is, the comment runs through the whole S-expression, regardless of newlines, which saves you from having to comment out every line, or add a newline in the middle of your parens to make the commenting of the last line work, or other things like that. Implements [[http://srfi.schemers.org/srfi-62/srfi-62.html|SRFI-62]].

=== External Representation

<read>#,</read>

 #,(CONSTRUCTORNAME DATUM ...)

Allows user-defined extension of external representations. (For more information see the documentation for
[[http://srfi.schemers.org/srfi-10/srfi-10.html|SRFI-10]])

=== Location Expression

<read> #$EXPRESSION</read>

An abbreviation for {{(location EXPRESSION)}}.

=== Blob literals

<read>#${</read>

  #${ HEX ... }

Syntax for literal "blobs" (byte-sequences). Expects hexadecimal digits and ignores
any whitespace characters:

  #;1> ,d '#${deadbee f}
  blob of size 4:
     0: de ad be ef                                     ....

=== Keyword

<read>#:</read>

 #:SYMBOL
 SYMBOL:
 :SYMBOL

Syntax for keywords. Keywords are symbols that evaluate to themselves, and as such don't have to be quoted.  Either {{SYMBOL:}} or {{:SYMBOL}} is accepted, depending on the setting of the {{keyword-style}} parameter, but never both.  {{#:SYMBOL}} is always accepted.

=== Multiline String Constant

<read>#<<</read>

 #<<TAG

Specifies a multiline string constant. Anything up to a line equal to {{TAG}} (or end of file) will be returned as a single string:

 (define msg #<<END
  "Hello, world!", she said.
 END
 )

is equivalent to

 (define msg "\"Hello, world!\", she said.")

=== Multiline String Constant with Embedded Expressions

<read>#<#</read>

 #<#TAG

Similar to {{#<<}}, but allows substitution of embedded Scheme expressions prefixed with {{#}} and optionally enclosed in curly brackets. Two consecutive {{#}}s are translated to a single {{#}}:

 (define three 3)
 (display #<#EOF
 This is a simple string with an embedded `##' character
 and substituted expressions: (+ three 99) ==> #(+ three 99)
 (three is "#{three}")
 EOF
 )

prints

 This is a simple string with an embedded `#' character
 and substituted expressions: (+ three 99) ==> 102
 (three is "3")

=== Foreign Declare

<read>#></read>

 #> ... <#

Abbreviation for {{(foreign-declare " ... ")}}.

=== String escape sequences

String-literals may contain the following escape sequences:

<table style="margin-top: 1em; max-width: 40em">
<tr><th>Escape sequence</th><th>Character</th></tr>
<tr><td>{{\n}}</td><td>line feed / newline</td></tr>
<tr><td>{{\t}}</td><td>tab</td></tr>
<tr><td>{{\r}}</td><td>carriage return</td></tr>
<tr><td>{{\b}}</td><td>backspace</td></tr>
<tr><td>{{\a}}</td><td>bell</td></tr>
<tr><td>{{\v}}</td><td>vertical tab</td></tr>
<tr><td>{{\f}}</td><td>form feed</td></tr>
<tr><td>{{\x}}''XX''</td><td>hexadecimal 8-bit character code</td></tr>
<tr><td>{{\u}}''XXXX''</td><td>hexadecimal 16-bit Unicode character code</td></tr>
<tr><td>{{\U}}''XXXXXXXX''</td><td>hexadecimal 32-bit Unicode character code</td></tr>
<tr><td>{{\}}''OOO''</td><td>octal 8-bit character code</td></tr>
<tr><td>{{\|}}   {{\"}}    {{\\}}    {{\'}}</td><td>the escaped character</td></tr>
</table>


=== Bang

<read>#!</read>

 #!... 

Interpretation depends on the directly following characters. Only the following are recognized. Any other case results in a read error.

; Line Comment : If followed by whitespace or a slash, then everything up the end of the current line is ignored

; Eof Object : If followed by the character sequence {{eof}}, then the (self-evaluating) end-of-file object is returned

; DSSSL Formal Parameter List Annotation : If followed by any of the character sequences {{optional}}, {{rest}} or {{key}}, then a symbol with the same name (and prefixed with {{#!}}) is returned

; Read Mark Invocation : If a ''read mark'' with the same name as the token is registered, then its procedure is called and the result of the read-mark procedure will be returned

=== Case Sensitive Expression

<read>#cs</read>

 #cs...

Read the next expression in case-sensitive mode (regardless of the current global setting).

=== Case Insensitive Expression

<read>#ci</read>

 #ci...

Read the next expression in case-insensitive mode (regardless of the current global setting).

=== Conditional Expansion

<read>#+</read>

 #+FEATURE EXPR

Rewrites to

 (cond-expand (FEATURE EXPR) (else))

and performs the feature test at macroexpansion time.  Therefore, it may not
work as expected when used within a macro form.

---
Previous: [[Deviations from the standard]]

Next: [[Debugging]]