diff --git a/.gitignore b/.gitignore index d13a2485..7e3e70a0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ build/* src/load_piclib.c src/init_contrib.c +docs/contrib.rst .dir-locals.el GPATH GRTAGS diff --git a/CMakeLists.txt b/CMakeLists.txt index 2ee8e462..3a32be84 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -33,6 +33,7 @@ include(piclib/CMakeLists.txt) include(contrib/CMakeLists.txt) include(src/CMakeLists.txt) include(tools/CMakeLists.txt) +include(docs/CMakeLists.txt) # ---- 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/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..422b85f0 --- /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 nitro\\\)" > ${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/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 1dec0954..6c82afaa 100644 --- a/docs/libs.rst +++ b/docs/libs.rst @@ -1,5 +1,5 @@ -Libraries -========= +Standard Libraries +================== Picrin's all built-in libraries are described below. @@ -73,79 +73,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) -------------- @@ -257,16 +184,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) -------------