{"size": 10084, "ext": "scrbl", "max_stars_repo_path": "doc/sagittarius-ref.scrbl", "max_stars_repo_name": "david135/sagittarius-scheme", "max_stars_repo_stars_event_min_datetime": null, "max_stars_repo_stars_event_max_datetime": null, "max_issues_repo_path": "doc/sagittarius-ref.scrbl", "max_issues_repo_name": "david135/sagittarius-scheme", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "doc/sagittarius-ref.scrbl", "max_forks_repo_name": "david135/sagittarius-scheme", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": null, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 36.0142857143, "max_line_length": 80, "alphanum_fraction": 0.7583300278}
@; -*- mode:scribble; coding: utf-8 -*-
@title{Sagittarius Users' Reference}

This document is a manual for Sagittarius, an R6RS Scheme implementation.
This is for version @eval{(sagittarius-version)}.

@table-of-contents[:id "table-of-contents"]

@section{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.

This manual only deals with Scheme side of things. Sagittarius has another face,
a C interface. Details of it will be discussed in a separate document yet to be
written. Those who wants to use Sagittarius as an embedded language, or wants to
write an extension, need that volume.

@subsection{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 @b{Mostly}
conforms the language standard "Revised^6 Report on the Algorithmic Language
Scheme" (R6RS), and supports various common libraries defined in 
"Scheme Requests for Implementation" (SRFI)s.

There are a lot of Scheme implementations and it has different strong and weak
point. 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 but it makes not to conform the
requirements. That's why it is Mostly R6RS.

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

@dl-list[]{
@dl-item["Reader"]{
 Basically reader has 2 modes. One is R6RS mode and other one is compatible
 mode. Although, user can modify reader with reader macro. For more details, see
 @secref["lib.sagittarius.reader.predefined"]{Predefined reader macros}.
}
@dl-item["Macro expansion"]{
 On R6RS requires explicit macro expansion phase, however Sagittarius does
 not have it. A macro is expanded when programs are compiled.}
@dl-item["Unbound symbol"]{
 If you write unbound symbol in your code, however Sagittarius won't raise
 error until it really called. R6RS does not allow this behaviour. And also
 exported symbol. If you do not define exported symbol, Sagittarius, then, won't
 raise error until it will be called. I'm not sure if this is convenient or not.
 So this behaviour may be changed.}
@dl-item["Toplevel"]{
 Sagittarius does not require toplevel expression which is specified in R6RS.}
@dl-item["Miscellaneous"]{
 Redefinition of exported values are allowed. The value which imported at the
 last will be used.}
}

@subsection{Notations}

In this manual, each entry is represented like this.

@define[Category]{@name{foo} @args{arg1 arg2}}
@desc{[spec] Description foo @dots{}}

@var{Category} denotes category of the entry @b{foo}. The following category
will appear in this manual.

@dl-list[
@dl-item["Program"]{A command line program}
@dl-item["Function"]{A Scheme function}
@dl-item["Syntax"]{A syntax}
@dl-item["Auxiliary Syntax"]{A auxiliary syntax}
@dl-item["Macro"]{A macro}
@dl-item["Auxiliary Macro"]{A auxiliary macro}
@dl-item["Library"]{A library}
@dl-item["Condition Type"]{A condition type}
@dl-item["Reader Macro"]{A reader macro}
@dl-item["Class"]{A CLOS class}
@dl-item["Generic"]{A generic function}
@dl-item["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.

@dl-list[
@dl-item[@var{arg @dots{}}]{Indicates zero or more arguments}
@dl-itemx[2 @var{:optional x y z} 
	    @var{: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 and y. This is either builtin functions or closures which
defined with define-optional macro.}
]

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:

@dl-list[
@dl-itemx[2 "[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.}
@dl-item["[R7RS]"]{
The entry works as specified in "Revised^7 Report on the Algorithmic Language
Scheme."(draft 5).}
@dl-itemx[2 "[SRFI-n]" "[SRFI-n+]"]{The entry works as specified in SRFI-n. If
it is marked as "[SRFI-n+]", the entry has additional functionality.}
]

@section{Programming in Sagittarius}

@subsection{Invoking sash}

Sagittarius can be used either as an independent Schame interpreter or an
embedded Scheme library. The interpreter which comes with Sagittarius
destribution is a program named sash.

@define[Program]{@name{sash} @args{[options] scheme-file arg @dots{}}}
@desc{Invoking sash. If @var{scheme-file} is not given, it runs with interactive
mode.
Detail options are given with option @code{"-h"}.}

@subsection{Writing Scheme scripts}

When a Scheme file is given to @code{sash}, it bounds an internal variable to
list of the remaining command-line arguments which you can get with the 
@code{command-line} procedure, then loads the Scheme program. If the first line
of scheme-file begins with @code{"#!"}, then sash 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:

@code{#!/usr/local/bin/sash}

or

@code{#!/bin/env sash}

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

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

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

@codeblock{
#!/usr/local/bin/sash
(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)
}
@subsection{Working on REPL}

If @code{sash} 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 @code{(rnrs)}.

If @code{.sashrc} file is located in the directory indicated @code{HOME} or
@code{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: @code{.sashrc} is only for REPL, it is developers duty to load all
libraries on script file.

@subsection{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 @code{library}
syntax please see the R6RS document described in bellow sections.
@codeblock{
(library (foo)
  (export bar)
  (import (rnrs))

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

If you want to write portable code, then you can write implementation specific
code separately using @code{.sagittarius.scm}, @code{.sagittarius.ss} or
@code{.sagittarius.sls} extensions.

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;
@codeblock{
(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 @code{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 codes some implementation do not allow you to write this style.

@subsection{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:
@itemlist[
  @item{@code{SAGITTARIUS_CACHE_DIR}}
  @item{@code{HOME}}
]

For Windows environment:
@itemlist[
  @item{@code{SAGITTARIUS_CACHE_DIR}}
  @item{@code{TEMP}}
  @item{@code{TMP}}
]

Sagittarius will use the variables respectively, so if the
@code{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 @code{-c} option with @code{sash}, then
it will wipe all cache files. If you don't want to use it, pass @code{-d} option
then Sagittarius won't use it.

@subsubsection{Precompiling cache file}

Users can provide own library with precompile script. The script looks like
this;

@codeblock{
(import (the-library-1) (the-library-2))
}

When this script is run, then the libraries will be cached in the cache
directory.

Note: The cache files are stored with the names converted from original library
files' absolute path. So it is important that users' libraries are already
installed before precompiling, otherwise Sagittarius won't use the precompiled
cache files.

@include-section["r6rs.scrbl"]
@include-section["r7rs.scrbl"]
@include-section["clos.scrbl"]
@include-section["sagittarius.scrbl"]
@include-section["utils.scrbl"]
@include-section["ported.scrbl"]
@include-section["srfi.scrbl"]
@section[:appendix "A" :tag "index"]{Index}

@index-table[:id "index-table"]
@author["Takashi Kato"]