diff --git a/CMakeLists.txt b/CMakeLists.txt index a3dfda58..6deba96f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -36,6 +36,7 @@ include_directories(extlib/benz/include) include(piclib/CMakeLists.txt) include(contrib/CMakeLists.txt) include(src/CMakeLists.txt) +include(docs/CMakeLists.txt) # ---- diff --git a/contrib/05.r7rs/docs/doc.rst b/contrib/05.r7rs/docs/doc.rst new file mode 100644 index 00000000..8891cc22 --- /dev/null +++ b/contrib/05.r7rs/docs/doc.rst @@ -0,0 +1,12 @@ +Scheme standard libraries +------------------------- + +- (scheme write) +- (scheme cxr) +- (scheme file) +- (scheme inexact) +- (scheme time) +- (scheme process-context) +- (scheme load) +- (scheme lazy) + diff --git a/contrib/10.partcont/docs/doc.rst b/contrib/10.partcont/docs/doc.rst new file mode 100644 index 00000000..08355948 --- /dev/null +++ b/contrib/10.partcont/docs/doc.rst @@ -0,0 +1,8 @@ +(picrin control) +---------------- + +Delimited control operators. + +- **(reset h)** +- **(shift k)** + diff --git a/contrib/10.pretty-print/docs/doc.rst b/contrib/10.pretty-print/docs/doc.rst new file mode 100644 index 00000000..2aa6102a --- /dev/null +++ b/contrib/10.pretty-print/docs/doc.rst @@ -0,0 +1,10 @@ +(picrin pretty-print) +--------------------- + +Pretty-printer. + +- **(pretty-print obj)** + + Prints obj with human-readable indention to current-output-port. + + diff --git a/contrib/10.regexp/docs/doc.rst b/contrib/10.regexp/docs/doc.rst new file mode 100644 index 00000000..a8e3f61a --- /dev/null +++ b/contrib/10.regexp/docs/doc.rst @@ -0,0 +1,19 @@ +(picrin regexp) +--------------- + +- **(regexp ptrn [flags])** + + Compiles pattern string into a regexp object. A string flags may contain any of #\g, #\i, #\m. + +- **(regexp? obj)** + + Judges if obj is a regexp object or not. + +- **(regexp-match re input)** + + Returns two values: a list of match strings, and a list of match indeces. + +- **(regexp-replace re input txt)** +- **(regexp-split re input)** + + diff --git a/contrib/10.srfi/docs/doc.rst b/contrib/10.srfi/docs/doc.rst new file mode 100644 index 00000000..bc95b39f --- /dev/null +++ b/contrib/10.srfi/docs/doc.rst @@ -0,0 +1,43 @@ +SRFI libraries +-------------- + +- `(srfi 1) + `_ + + List library. + +- `(srfi 8) + `_ + + ``receive`` macro. + +- `(srfi 17) + `_ + + Generalized set! + +- `(srfi 26) + `_ + + Cut/cute macros. + +- `(srfi 43) + `_ + + Vector library. + +- `(srfi 60) + `_ + + Bitwise operations. + +- `(srfi 95) + `_ + + Sorting and Marging. + +- `(srfi 111) + `_ + + Boxes + diff --git a/contrib/20.for/docs/doc.rst b/contrib/20.for/docs/doc.rst new file mode 100644 index 00000000..198b2299 --- /dev/null +++ b/contrib/20.for/docs/doc.rst @@ -0,0 +1,46 @@ +(picrin control list) +--------------------- + +Monadic list operators. + +The triple of for/in/yield enables you to write a list operation in a very easy and simple code. One of the best examples is list composition:: + + (for (let ((a (in '(1 2 3))) + (b (in '(2 3 4)))) + (yield (+ a b)))) + + ;=> (5 6 7 6 7 8 7 8 9) + +All monadic operations are done in *for* macro. In this example, *in* operators choose an element from the given lists, a and b are bound here, then *yielding* the sum of them. Because a and b are values moving around in the list elements, the expression (+ a b) can become every possible result. *yield* operator is a operator that gathers the possibilities into a list, so *for* macro returns a list of 3 * 3 results in total. Since expression inside *for* macro is a normal expression, you can write everything that you can write elsewhere. The code below has perfectly the same effect to above one:: + + (for (yield (+ (in '(1 2 3)) + (in '(4 5 6))))) + +The second best exmaple is filtering. In the next case, we show that you can do something depending on the condition of chosen elements:: + + (for (let ((x (in (iota 10)))) + (if (even? x) + (yield x) + (null)))) + + ;=> (0 2 4 6 8) + +This expression is equivalent to ``(filter even? (iota 10))`` but it is more procedual and non-magical. + +- **(for expr)** + + [Macro] Executes expr in a list monad context. + +- **(in list)** + + Choose a value from list. *in* function must only appear in *for* macro. The delimited continuation from the position of *in* function to the outside *for* macro is executed for each element in list. If list contains no values, that is ``(in '())``, the continuation is discarded. + +- **(yield value)** + + Yields value from the monad context. The result of *for* will be a list of yielded values. + +- **(null . value)** + + Returns ``()`` whatever value is given. The identity element of list composition. This operator corresponds to Haskell's fail method of Monad class. + + diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 00000000..cf9bfaa6 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,27 @@ +# contribs +file(GLOB PICRIN_CONTRIB_DOCS ${PROJECT_SOURCE_DIR}/contrib/*/docs/*.rst) +file(GLOB PICRIN_DOCS ${PROJECT_SOURCE_DIR}/docs/*.rst) +list(SORT PICRIN_CONTRIB_DOCS) + +set(PICRIN_CONTRIBS_DOC ${PROJECT_SOURCE_DIR}/docs/contrib.rst) +set(PICRIN_DOC_OUTPUT_DIRECTORY doc) + +add_custom_command( + OUTPUT ${PICRIN_CONTRIBS_DOC} + COMMAND echo "Contrib Libraries \\\(a.k.a nitros\\\)" > ${PICRIN_CONTRIBS_DOC} + COMMAND echo "===============================" >> ${PICRIN_CONTRIBS_DOC} + COMMAND echo "" >> ${PICRIN_CONTRIBS_DOC} + COMMAND cat ${PICRIN_CONTRIB_DOCS} >> ${PICRIN_CONTRIBS_DOC} + DEPENDS ${PICRIN_CONTRIB_DOCS} + ) + +add_custom_target(doc + COMMAND make -C ${PROJECT_SOURCE_DIR}/docs html + DEPENDS ${PICRIN_CONTRIBS_DOC} + ) + +add_custom_command( + TARGET doc POST_BUILD + COMMAND mkdir -p ${PICRIN_DOC_OUTPUT_DIRECTORY} + COMMAND cp -uR ${PROJECT_SOURCE_DIR}/docs/_build/* -t ${PICRIN_DOC_OUTPUT_DIRECTORY}/ + ) \ No newline at end of file diff --git a/docs/contrib.rst b/docs/contrib.rst new file mode 100644 index 00000000..f8b47417 --- /dev/null +++ b/docs/contrib.rst @@ -0,0 +1,141 @@ +Contrib Libraries (a.k.a nitros) +=============================== + +Scheme standard libraries +------------------------- + +- (scheme write) +- (scheme cxr) +- (scheme file) +- (scheme inexact) +- (scheme time) +- (scheme process-context) +- (scheme load) +- (scheme lazy) + +(picrin control) +---------------- + +Delimited control operators. + +- **(reset h)** +- **(shift k)** + +(picrin pretty-print) +--------------------- + +Pretty-printer. + +- **(pretty-print obj)** + + Prints obj with human-readable indention to current-output-port. + + +(picrin regexp) +--------------- + +- **(regexp ptrn [flags])** + + Compiles pattern string into a regexp object. A string flags may contain any of #\g, #\i, #\m. + +- **(regexp? obj)** + + Judges if obj is a regexp object or not. + +- **(regexp-match re input)** + + Returns two values: a list of match strings, and a list of match indeces. + +- **(regexp-replace re input txt)** +- **(regexp-split re input)** + + +SRFI libraries +-------------- + +- `(srfi 1) + `_ + + List library. + +- `(srfi 8) + `_ + + ``receive`` macro. + +- `(srfi 17) + `_ + + Generalized set! + +- `(srfi 26) + `_ + + Cut/cute macros. + +- `(srfi 43) + `_ + + Vector library. + +- `(srfi 60) + `_ + + Bitwise operations. + +- `(srfi 95) + `_ + + Sorting and Marging. + +- `(srfi 111) + `_ + + Boxes + +(picrin control list) +--------------------- + +Monadic list operators. + +The triple of for/in/yield enables you to write a list operation in a very easy and simple code. One of the best examples is list composition:: + + (for (let ((a (in '(1 2 3))) + (b (in '(2 3 4)))) + (yield (+ a b)))) + + ;=> (5 6 7 6 7 8 7 8 9) + +All monadic operations are done in *for* macro. In this example, *in* operators choose an element from the given lists, a and b are bound here, then *yielding* the sum of them. Because a and b are values moving around in the list elements, the expression (+ a b) can become every possible result. *yield* operator is a operator that gathers the possibilities into a list, so *for* macro returns a list of 3 * 3 results in total. Since expression inside *for* macro is a normal expression, you can write everything that you can write elsewhere. The code below has perfectly the same effect to above one:: + + (for (yield (+ (in '(1 2 3)) + (in '(4 5 6))))) + +The second best exmaple is filtering. In the next case, we show that you can do something depending on the condition of chosen elements:: + + (for (let ((x (in (iota 10)))) + (if (even? x) + (yield x) + (null)))) + + ;=> (0 2 4 6 8) + +This expression is equivalent to ``(filter even? (iota 10))`` but it is more procedual and non-magical. + +- **(for expr)** + + [Macro] Executes expr in a list monad context. + +- **(in list)** + + Choose a value from list. *in* function must only appear in *for* macro. The delimited continuation from the position of *in* function to the outside *for* macro is executed for each element in list. If list contains no values, that is ``(in '())``, the continuation is discarded. + +- **(yield value)** + + Yields value from the monad context. The result of *for* will be a list of yielded values. + +- **(null . value)** + + Returns ``()`` whatever value is given. The identity element of list composition. This operator corresponds to Haskell's fail method of Monad class. + + diff --git a/docs/index.rst b/docs/index.rst index 5c620a0d..be1a32b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Contents: deploy.rst lang.rst libs.rst + contrib.rst capi.rst Indices and tables diff --git a/docs/libs.rst b/docs/libs.rst index 5227e265..fb3b265a 100644 --- a/docs/libs.rst +++ b/docs/libs.rst @@ -1,63 +1,8 @@ -Libraries -========= +Standard Libraries +================== Picrin's all built-in libraries are described below. -Scheme standard libraries -------------------------- - -- (scheme write) -- (scheme cxr) -- (scheme file) -- (scheme inexact) -- (scheme time) -- (scheme process-context) -- (scheme load) -- (scheme lazy) - -SRFI libraries --------------- - -- `(srfi 1) - `_ - - List library. - -- `(srfi 8) - `_ - - ``receive`` macro. - -- `(srfi 17) - `_ - - Generalized set! - -- `(srfi 26) - `_ - - Cut/cute macros. - -- `(srfi 43) - `_ - - Vector library. - -- `(srfi 60) - `_ - - Bitwise operations. - -- `(srfi 95) - `_ - - Sorting and Marging. - -- `(srfi 111) - `_ - - Boxes - (picrin macro) -------------- @@ -89,79 +34,6 @@ Syntactic closures. Explicit renaming macro family. -(picrin regexp) ---------------- - -- **(regexp ptrn [flags])** - - Compiles pattern string into a regexp object. A string flags may contain any of #\g, #\i, #\m. - -- **(regexp? obj)** - - Judges if obj is a regexp object or not. - -- **(regexp-match re input)** - - Returns two values: a list of match strings, and a list of match indeces. - -- **(regexp-replace re input txt)** -- **(regexp-split re input)** - - -(picrin control) ----------------- - -Delimited control operators. - -- **(reset h)** -- **(shift k)** - -(picrin control list) ---------------------- - -Monadic list operators. - -The triple of for/in/yield enables you to write a list operation in a very easy and simple code. One of the best examples is list composition:: - - (for (let ((a (in '(1 2 3))) - (b (in '(2 3 4)))) - (yield (+ a b)))) - - ;=> (5 6 7 6 7 8 7 8 9) - -All monadic operations are done in *for* macro. In this example, *in* operators choose an element from the given lists, a and b are bound here, then *yielding* the sum of them. Because a and b are values moving around in the list elements, the expression (+ a b) can become every possible result. *yield* operator is a operator that gathers the possibilities into a list, so *for* macro returns a list of 3 * 3 results in total. Since expression inside *for* macro is a normal expression, you can write everything that you can write elsewhere. The code below has perfectly the same effect to above one:: - - (for (yield (+ (in '(1 2 3)) - (in '(4 5 6))))) - -The second best exmaple is filtering. In the next case, we show that you can do something depending on the condition of chosen elements:: - - (for (let ((x (in (iota 10)))) - (if (even? x) - (yield x) - (null)))) - - ;=> (0 2 4 6 8) - -This expression is equivalent to ``(filter even? (iota 10))`` but it is more procedual and non-magical. - -- **(for expr)** - - [Macro] Executes expr in a list monad context. - -- **(in list)** - - Choose a value from list. *in* function must only appear in *for* macro. The delimited continuation from the position of *in* function to the outside *for* macro is executed for each element in list. If list contains no values, that is ``(in '())``, the continuation is discarded. - -- **(yield value)** - - Yields value from the monad context. The result of *for* will be a list of yielded values. - -- **(null . value)** - - Returns ``()`` whatever value is given. The identity element of list composition. This operator corresponds to Haskell's fail method of Monad class. - - (picrin array) -------------- @@ -277,16 +149,6 @@ Note that dictionary is not a weak map; if you are going to make a highly memory Conversion between dictionary and alist/plist. -(picrin pretty-print) ---------------------- - -Pretty-printer. - -- **(pretty-print obj)** - - Prints obj with human-readable indention to current-output-port. - - (picrin user) -------------