From e30040e2d7375fc35be87c2ea7a51cc313ec4234 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 25 Mar 2021 22:55:56 -0400 Subject: [PATCH] Update documentation --- docs/API.md | 106 +++++++++++++++++-------------- docs/api/cyclone/foreign.md | 9 +++ docs/api/scheme/cyclone/match.md | 5 ++ docs/api/scheme/cyclone/test.md | 5 ++ docs/api/scheme/cyclone/util.md | 2 +- 5 files changed, 78 insertions(+), 49 deletions(-) diff --git a/docs/API.md b/docs/API.md index f8684ba9..43b3d6ce 100644 --- a/docs/API.md +++ b/docs/API.md @@ -17,67 +17,77 @@ title: API This section of the Cyclone API is based on the [R7RS Scheme Specification](r7rs.pdf): -- [Primitives](api/primitives) -- [`scheme base`](api/scheme/base) -- [`scheme case-lambda`](api/scheme/case-lambda) -- [`scheme char`](api/scheme/char) -- [`scheme complex`](api/scheme/complex) -- [`scheme cxr`](api/scheme/cxr) -- [`scheme eval`](api/scheme/eval) -- [`scheme file`](api/scheme/file) -- [`scheme inexact`](api/scheme/inexact) -- [`scheme lazy`](api/scheme/lazy) -- [`scheme load`](api/scheme/load) -- [`scheme process-context`](api/scheme/process-context) -- [`scheme read`](api/scheme/read) -- [`scheme repl`](api/scheme/repl) -- [`scheme time`](api/scheme/time) -- [`scheme write`](api/scheme/write) +Library Name | Description +---------------------------------------------------------- | ----------- +[Primitives](api/primitives) | This is not actually a library but rather a summary of all of the built-in functions (AKA primitives). +[`scheme base`](api/scheme/base) | The R7RS base library. This is quite extensive and will be required by most programs. +[`scheme case-lambda`](api/scheme/case-lambda) | +[`scheme char`](api/scheme/char) | +[`scheme complex`](api/scheme/complex) | +[`scheme cxr`](api/scheme/cxr) | +[`scheme eval`](api/scheme/eval) | +[`scheme file`](api/scheme/file) | +[`scheme inexact`](api/scheme/inexact) | +[`scheme lazy`](api/scheme/lazy) | +[`scheme load`](api/scheme/load) | +[`scheme process-context`](api/scheme/process-context) | +[`scheme read`](api/scheme/read) | +[`scheme repl`](api/scheme/repl) | +[`scheme time`](api/scheme/time) | +[`scheme write`](api/scheme/write) | # SRFI Libraries -Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http://srfi.schemers.org/) libraries. Detailed information is available in the linked SRFI page as well as the provided Cyclone API: +Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http://srfi.schemers.org/) libraries. Detailed information is available in the linked SRFI page as well as the provided Cyclone API. -- [`srfi 1`](api/srfi/1) - [List library](http://srfi.schemers.org/srfi-1/srfi-1.html) -- [`srfi 2`](api/srfi/2) - [`and-let*`](http://srfi.schemers.org/srfi-2/srfi-2.html) -- [`srfi 8`](api/srfi/8) - [`receive`: Binding to multiple values](http://srfi.schemers.org/srfi-8/srfi-8.html) - Included as part of `scheme base`. -- [`srfi 18`](api/srfi/18) - [Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html) -- [`srfi 27`](api/srfi/27) - [Sources of random bits](http://srfi.schemers.org/srfi-27/srfi-27.html) -- [`srfi 28`](api/srfi/28) - [Basic format strings](http://srfi.schemers.org/srfi-28/srfi-28.html) -- [`srfi 60`](api/srfi/60) - [Integers as bits](http://srfi.schemers.org/srfi-60/srfi-60.html) -- [`srfi 69`](api/srfi/69) - [Basic hash tables](http://srfi.schemers.org/srfi-69/srfi-69.html) -- [`srfi 106`](api/srfi/106) - [Basic socket interface](http://srfi.schemers.org/srfi-106/srfi-106.html) -- [`srfi 111`](api/srfi/111) - [Boxes](http://srfi.schemers.org/srfi-111/srfi-111.html) -- [`srfi 113`](api/srfi/113) - [Sets and bags](http://srfi.schemers.org/srfi-113/srfi-113.html) -- [`srfi 117`](api/srfi/117) - [Mutable queues](http://srfi.schemers.org/srfi-117/srfi-117.html) -- [`srfi 121`](api/srfi/121) - [Generators](http://srfi.schemers.org/srfi-121/srfi-121.html) -- [`srfi 128`](api/srfi/128) - [Comparators](http://srfi.schemers.org/srfi-128/srfi-128.html) -- [`srfi 132`](api/srfi/132) - [Sort libraries](http://srfi.schemers.org/srfi-132/srfi-132.html) -- [`srfi 133`](api/srfi/133) - [Vector library (R7RS-compatible)](http://srfi.schemers.org/srfi-133/srfi-133.html) -- [`srfi 143`](api/srfi/143) - [Fixnums](http://srfi.schemers.org/srfi-143/srfi-143.html) +Note that these libraries may be imported using either the SRFI number (EG: `(srfi 1)` or a descriptive name (EG: `(scheme list)`). These descriptive names follow the recommendations from R7RS Large where available. + +Library Name | SRFI Number | Description | External Documentation +--------------------------------------- | ----------- | ----------- | ---------------------- +[`scheme list`](api/srfi/1) | [`srfi 1`](api/srfi/1) | List library | [Link](http://srfi.schemers.org/srfi-1/srfi-1.html) +[`cyclone and-let*`](api/srfi/2) | [`srfi 2`](api/srfi/2) | `AND-LET*`: an `AND` with local bindings, a guarded `LET*` special form | [Link](http://srfi.schemers.org/srfi-2/srfi-2.html) + N/A | [`srfi 8`](api/srfi/8) | Binding to multiple values - Included as part of `scheme base`. | [Link](http://srfi.schemers.org/srfi-8/srfi-8.html) +[`cyclone threads`](api/srfi/18) | [`srfi 18`](api/srfi/18) | Multithreading support | [Link](http://srfi.schemers.org/srfi-18/srfi-18.html) +[`cyclone random`](api/srfi/27) | [`srfi 27`](api/srfi/27) | Sources of random bits | [Link](http://srfi.schemers.org/srfi-27/srfi-27.html) +[`cyclone format`](api/srfi/28) | [`srfi 28`](api/srfi/28) | Basic format strings | [Link](http://srfi.schemers.org/srfi-28/srfi-28.html) +[`cyclone integer-bits`](api/srfi/60)| [`srfi 60`](api/srfi/60) | Integers as bits | [Link](http://srfi.schemers.org/srfi-60/srfi-60.html) +[`scheme hash-table`](api/srfi/69) | [`srfi 69`](api/srfi/69) | Basic hash tables | [Link](http://srfi.schemers.org/srfi-69/srfi-69.html) +[`cyclone socket`](api/srfi/106) | [`srfi 106`](api/srfi/106) | Basic socket interface | [Link](http://srfi.schemers.org/srfi-106/srfi-106.html) +[`scheme box`](api/srfi/111) | [`srfi 111`](api/srfi/111) | Boxes | [Link](http://srfi.schemers.org/srfi-111/srfi-111.html) +[`scheme set`](api/srfi/113) | [`srfi 113`](api/srfi/113) | Sets and bags | [Link](http://srfi.schemers.org/srfi-113/srfi-113.html) +[`scheme list-queue`](api/srfi/117) | [`srfi 117`](api/srfi/117) | Mutable queues | [Link](http://srfi.schemers.org/srfi-117/srfi-117.html) +[`scheme generator`](api/srfi/121) | [`srfi 121`](api/srfi/121) | Generators | [Link](http://srfi.schemers.org/srfi-121/srfi-121.html) +[`scheme comparator`](api/srfi/128) | [`srfi 128`](api/srfi/128) | Comparators | [Link](http://srfi.schemers.org/srfi-128/srfi-128.html) +[`scheme sort`](api/srfi/132) | [`srfi 132`](api/srfi/132) | Sort libraries | [Link](http://srfi.schemers.org/srfi-132/srfi-132.html) +[`scheme vector`](api/srfi/133) | [`srfi 133`](api/srfi/133) | Vector library (R7RS-compatible) | [Link](http://srfi.schemers.org/srfi-133/srfi-133.html) +[`cyclone fixnum`](api/srfi/143) | [`srfi 143`](api/srfi/143) | Fixnums | [Link](http://srfi.schemers.org/srfi-143/srfi-143.html) # Cyclone Libraries -These libraries are provided by Cyclone with a stable API that is unlikely to change: +These libraries are provided as Cyclone-specific extensions: -- [`cyclone concurrent`](api/cyclone/concurrent) - A helper library for writing concurrent code. -- [`cyclone foreign`](api/cyclone/foreign) - Provides a convenient interface for integrating with C code. -- [`cyclone match`](api/cyclone/match) - A hygienic pattern matcher based on Alex Shinn's portable `match.scm`. -- [`cyclone test`](api/cyclone/test) - A unit testing framework ported from `(chibi test)`. -- [`scheme cyclone pretty-print`](api/scheme/cyclone/pretty-print) - A pretty printer. +Library Name | Description +------------ | ----------- +[`cyclone concurrent`](api/cyclone/concurrent) | A helper library for writing concurrent code. +[`cyclone foreign`](api/cyclone/foreign) | Provides a convenient interface for integrating with C code. It is recommended to use this library if possible rather than our lower-level FFI. +[`cyclone match`](api/cyclone/match) | A hygienic pattern matcher based on Alex Shinn's portable `match.scm`. +[`cyclone test`](api/cyclone/test) | A unit testing framework ported from `(chibi test)`. +[`scheme cyclone pretty-print`](api/scheme/cyclone/pretty-print) | A pretty printer. # Internal Compiler API These libraries are used by the Cyclone compiler. Some of these are stable and unlikely to change, whereas others could change as the compiler evolves. -- [`scheme cyclone ast`](api/scheme/cyclone/ast) -- [`scheme cyclone cgen`](api/scheme/cyclone/cgen) -- [`scheme cyclone common`](api/scheme/cyclone/common) -- [`scheme cyclone cps-optimizations`](api/scheme/cyclone/cps-optimizations) -- [`scheme cyclone libraries`](api/scheme/cyclone/libraries) -- [`scheme cyclone primitives`](api/scheme/cyclone/primitives) -- [`scheme cyclone transforms`](api/scheme/cyclone/transforms) -- [`scheme cyclone util`](api/scheme/cyclone/util) +Library Name | Description +----------------------------------------------------------------------------- | ----------- +[`scheme cyclone ast`](api/scheme/cyclone/ast) | Abstract syntax tree types used during compilation. +[`scheme cyclone cgen`](api/scheme/cyclone/cgen) | C code generation +[`scheme cyclone common`](api/scheme/cyclone/common) | Mostly version numbers and header comments +[`scheme cyclone cps-optimizations`](api/scheme/cyclone/cps-optimizations) | Compiler optimizations, analysis, and related transformations +[`scheme cyclone libraries`](api/scheme/cyclone/libraries) | Compiler support for R7RS libraries +[`scheme cyclone primitives`](api/scheme/cyclone/primitives) | Compiler support for primitives +[`scheme cyclone transforms`](api/scheme/cyclone/transforms) | Various Scheme-to-Scheme transformations of the intermediate code +[`scheme cyclone util`](api/scheme/cyclone/util) | Utility functions used internally by the compiler # C API diff --git a/docs/api/cyclone/foreign.md b/docs/api/cyclone/foreign.md index 1b608095..30f4211b 100644 --- a/docs/api/cyclone/foreign.md +++ b/docs/api/cyclone/foreign.md @@ -75,4 +75,13 @@ Scheme | C `bignum` | `mp_int` `opaque` | `void *` `c-void` | `void` +`thread-data` | `gc_thread_data *` + +Useful notes: +- Use `opaque` if you need to handle any kind of C pointer. +- Use `string` to handle C `const char*` (`symbol` is strictly used to represent Scheme symbols). +- `thread-data` is a special type used to pass the current thread's `gc_thread_data` instance to a C function. These objects are passed implicitly when making a Scheme function call. For example: + + (c-define sub-big-nums bignum "sub_big_nums" thread-data bignum bignum) + (sub-big-nums 999999999999999999999999 222222222222222222222222)) diff --git a/docs/api/scheme/cyclone/match.md b/docs/api/scheme/cyclone/match.md index cd7ab13b..96e6ff1b 100644 --- a/docs/api/scheme/cyclone/match.md +++ b/docs/api/scheme/cyclone/match.md @@ -8,6 +8,11 @@ layout: main title: API --- +--- +layout: main +title: API +--- + # Match Library The `(scheme cyclone match)` library provides a hygienic pattern matcher, based on Alex Shinn's portable `match.scm`. diff --git a/docs/api/scheme/cyclone/test.md b/docs/api/scheme/cyclone/test.md index 59464525..caa940cd 100644 --- a/docs/api/scheme/cyclone/test.md +++ b/docs/api/scheme/cyclone/test.md @@ -8,6 +8,11 @@ layout: main title: API --- +--- +layout: main +title: API +--- + # Test Library The `(scheme cyclone test)` library contains a testing framework ported from `(chibi test)` which in turn was ported from CHICKEN. diff --git a/docs/api/scheme/cyclone/util.md b/docs/api/scheme/cyclone/util.md index 6f4aee12..d4d31922 100644 --- a/docs/api/scheme/cyclone/util.md +++ b/docs/api/scheme/cyclone/util.md @@ -5,7 +5,7 @@ title: API # Util Library -The `(scheme cyclone util`) library contains various utility functions. +The `(scheme cyclone util`) library contains various utility functions used internally the compiler. - [`Cyc-er-compare? `](#cyc-er-compare) - [`Cyc-er-rename `](#cyc-er-rename)