From 883a38ecded73aa0709e7d6907cc6066d6af2d86 Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Sun, 31 Aug 2014 23:04:35 +0900 Subject: [PATCH 1/6] move contrib's docs into thir directories --- .gitignore | 1 + CMakeLists.txt | 1 + contrib/10.partcont/docs/doc.rst | 8 +++ contrib/10.pretty-print/docs/doc.rst | 10 ++++ contrib/10.regexp/docs/doc.rst | 19 ++++++ contrib/20.for/docs/doc.rst | 46 +++++++++++++++ docs/CMakeLists.txt | 27 +++++++++ docs/index.rst | 1 + docs/libs.rst | 87 +--------------------------- 9 files changed, 115 insertions(+), 85 deletions(-) create mode 100644 contrib/10.partcont/docs/doc.rst create mode 100644 contrib/10.pretty-print/docs/doc.rst create mode 100644 contrib/10.regexp/docs/doc.rst create mode 100644 contrib/20.for/docs/doc.rst create mode 100644 docs/CMakeLists.txt 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) ------------- From ed1a226aef041f35b6baf95dd00e39ff8479ed33 Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Mon, 1 Sep 2014 20:57:32 +0900 Subject: [PATCH 2/6] grammer fix --- docs/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 422b85f0..cf9bfaa6 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -8,7 +8,7 @@ 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 "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} From 7a0890fbd70b5f275c1df6c0fd5f8f727c3af153 Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Sat, 20 Sep 2014 17:04:19 +0900 Subject: [PATCH 3/6] move docs to contribs --- contrib/05.r7rs/docs/doc.rst | 12 ++++++++ contrib/10.srfi/docs/doc.rst | 43 ++++++++++++++++++++++++++++ docs/libs.rst | 55 ------------------------------------ 3 files changed, 55 insertions(+), 55 deletions(-) create mode 100644 contrib/05.r7rs/docs/doc.rst create mode 100644 contrib/10.srfi/docs/doc.rst 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.srfi/docs/doc.rst b/contrib/10.srfi/docs/doc.rst new file mode 100644 index 00000000..b75ab6bd --- /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/docs/libs.rst b/docs/libs.rst index 03b08b48..26bf3ac4 100644 --- a/docs/libs.rst +++ b/docs/libs.rst @@ -3,61 +3,6 @@ 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) -------------- From 36394c8ebbd5fbd6ca34bea53017cf57922a01ea Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Sat, 20 Sep 2014 17:04:53 +0900 Subject: [PATCH 4/6] fix link --- contrib/10.srfi/docs/doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contrib/10.srfi/docs/doc.rst b/contrib/10.srfi/docs/doc.rst index b75ab6bd..bc95b39f 100644 --- a/contrib/10.srfi/docs/doc.rst +++ b/contrib/10.srfi/docs/doc.rst @@ -2,7 +2,7 @@ SRFI libraries -------------- - `(srfi 1) - `_ + `_ List library. From 629824bf726b723afab599f1637f68dbf997d2a9 Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Thu, 23 Oct 2014 15:59:35 +0900 Subject: [PATCH 5/6] add generated contrib.rst You need to run `make doc` before you commit when you have edited docs under contrib/. --- docs/contrib.rst | 141 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/contrib.rst 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. + + From a561ee53b7eb795be2c656934485a09479447481 Mon Sep 17 00:00:00 2001 From: "Sunrim KIM (keen)" <3han5chou7@gmail.com> Date: Thu, 23 Oct 2014 16:07:08 +0900 Subject: [PATCH 6/6] update .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 7e3e70a0..d13a2485 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ build/* src/load_piclib.c src/init_contrib.c -docs/contrib.rst .dir-locals.el GPATH GRTAGS