From 2fb2db191d37036023d7ca6a5603d27089533890 Mon Sep 17 00:00:00 2001 From: Alex Shinn Date: Fri, 8 Apr 2011 01:04:35 +0900 Subject: [PATCH] doc improvements --- doc/chibi-scheme.1 | 5 ++- doc/chibi.scrbl | 93 +++++++++++++++++++++++++++++++++++++++------- 2 files changed, 84 insertions(+), 14 deletions(-) diff --git a/doc/chibi-scheme.1 b/doc/chibi-scheme.1 index 4dc23233..a55520cf 100644 --- a/doc/chibi-scheme.1 +++ b/doc/chibi-scheme.1 @@ -6,7 +6,7 @@ chibi-scheme \- a tiny Scheme interpreter .SH SYNOPSIS .B chibi-scheme -[-qV] +[-qfV] [-I .I path ] @@ -68,6 +68,9 @@ Don't load the initialization file. The resulting environment will only contain the core syntactic forms and primitives coded in C. .TP +.BI -f +Change the reader to case-fold symbols as in R5RS. +.TP .BI -h size[/max_size] Specifies the initial size of the heap, in bytes, optionally followed by the maximum size the heap can diff --git a/doc/chibi.scrbl b/doc/chibi.scrbl index 8a623030..f2bf69f7 100755 --- a/doc/chibi.scrbl +++ b/doc/chibi.scrbl @@ -191,16 +191,16 @@ primitive type constructors: (register-simple-type ) => -(make-type-predicate ) +(make-type-predicate ) => ; takes 1 arg, returns #t iff that arg is of the type -(make-constructor ) +(make-constructor ) => ; takes 0 args, returns a newly allocated instance of type -(make-getter ) +(make-getter ) => ; takes 1 args, retrieves the field located at the index -(make-setter ) +(make-setter ) => ; takes 2 args, sets the field located at the index } @@ -718,25 +718,87 @@ and idioms, such as return values passed in actual parameters. Writing C by hand is still possible, and several of the core modules provide C interfaces directly without using the stubber. +@subsection{Includes and Initializations} + +@itemlist[ +@item{@scheme{(c-include header)} - includes the file @var{header}} +@item{@scheme{(c-system-include header)} - includes the system file @var{header}} +@item{@scheme{(c-declare args ...)} - outputs @var{args} directly in the top-level C source} +@item{@scheme{(c-init args ...)} - evaluates @var{args} as C code after all other library initializations have been performed, with @cvar{ctx} and @cvar{env} in scope} +] + @subsection{Struct Interface} +C structs can be bound as Scheme types with the +@scheme{define-c-struct} form: + @schemeblock{ -(define-c-struct struct-name +(define-c-struct struct_name [predicate: predicate-name] [constructor: constructor-name] [finalizer: c_finalizer_name] (type c_field_name getter-name setter-name) ...) } +@var{struct_name} should be the name of a C struct type. If provided, +@var{predicate-name} is bound to a procedure which takes one object +and returns @scheme{#t} iff the object is of type @var{struct_name}. + +If provided, @var{constructor-name} is bound to a procedure of zero +arguments which creates and returns a newly allocated instance of the +type. + +If a finalizer is provided, @var{c_finalizer_name} must be a C +function which takes one argument, a pointer to the struct, and +performs any cleanup or freeing of resources necessary. + +The remaining slots are similar to the SRFI-9 syntax, except they are +prefixed with a C type (described below). The @var{c_field_name} +should be a field name of @var{struct_name}. @var{getter-name} will +then be bound to a procedure of one argument, a @{struct_name} type, +which returns the given field. If provided, @var{setter-name} will be +bound to a procedure of two arguments to mutate the given field. + +The variants @scheme{define-c-class} and @scheme{define-c-union} take +the same syntax but define types with the @ccode{class} and +@ccode{union} keywords respectively. @scheme{define-c-type} just +defines accessors to an opaque type without any specific struct-like +keyword. + +@schemeblock{ +;; Example: the struct addrinfo returned by getaddrinfo. + +(c-system-include "netdb.h") + +(define-c-struct addrinfo + finalizer: freeaddrinfo + predicate: address-info? + (int ai_family address-info-family) + (int ai_socktype address-info-socket-type) + (int ai_protocol address-info-protocol) + ((link sockaddr) ai_addr address-info-address) + (size_t ai_addrlen address-info-address-length) + ((link addrinfo) ai_next address-info-next)) +} + @subsection{Function Interface} +C functions are defined with: + @scheme{(define-c return-type name-spec (arg-type ...))} -where name-space is either a symbol name, or a list of -(scheme-name c_name). If just a symbol, the C name is taken -to be the same with -'s replaced by _'s. +where @var{name-space} is either a symbol name, or a list of +@scheme{(scheme-name c_name)}. If just a symbol is used, the C name +is generated automatically by replacing any dashes (-) in the Scheme +name with underscores (_). -@var{arg-type} is a type suitable for input validation and conversion. +Each @var{arg-type} is a type suitable for input validation and +conversion as discussed below. + +@schemeblock{ +;; Example: define connect(2) in Scheme +(define-c int connect (int sockaddr int)) +} @subsection{C Types} @@ -794,9 +856,9 @@ to be the same with -'s replaced by _'s. @subsubsection{Struct Types} Struct types are by default just referred to by the bare -struct-name from define-c-struct, and it is assumed you want a -pointer to that type. To refer to the full struct, use the struct -modifier, as in (struct struct-name). +@var{struct_name} from @scheme{define-c-struct}, and it is assumed you +want a pointer to that type. To refer to the full struct, use the +struct modifier, as in @scheme{(struct struct-name)}. @subsubsection{Type modifiers} @@ -949,7 +1011,8 @@ pattern matching syntax. @subsection{RFC2045 MIME} -The @scheme{(chibi mime)} module +The @scheme{(chibi mime)} module provides utilities for parsing MIME +files into an SXML format. @subsection{Module Introspection} @@ -994,6 +1057,10 @@ current user information. The @scheme{(chibi term edit-line)} provides an @scheme{edit-line} procedure for interactive line editing. +@subsection{Testing} + +The @scheme{(chibi test)} provides a simple unit testing framework. + @subsection{Times and Dates} The @scheme{(chibi time)} provides an interface to the current system time.