source: project/release/3/stacktor/trunk/stacktor-eggdoc.scm @ 8560

Last change on this file since 8560 was 8560, checked in by mfredrickson, 12 years ago

Initial checkin of the Stacktor egg. Stacktor is a stack based DSL, based on Factor.

Stacktor allows programmers to use stack based programming next to more familiar styles of
programming such as functional, imperative, object-oriented, etc. In stack programming,
arguments are taken from the stack, and return values are pushed back on to the stack. Literal
values are automatically pushed on to the stack. Stack operations (such as dropping the top
element of the stack) allow programmers to shuffle order of arguments, duplicate arguments, and
otherwise modify the stack as needed.

File size: 7.5 KB
Line 
1;;;; stack-eggdoc.scm
2
3(use eggdoc)
4
5(define license #<<EOF
6Copyright (c) 2008, Mark Fredrickson.  All rights reserved.
7
8Permission is hereby granted, free of charge, to any person obtaining a
9copy of this software and associated documentation files (the Software),
10to deal in the Software without restriction, including without limitation
11the rights to use, copy, modify, merge, publish, distribute, sublicense,
12and/or sell copies of the Software, and to permit persons to whom the
13Software is furnished to do so, subject to the following conditions:
14
15The above copyright notice and this permission notice shall be included
16in all copies or substantial portions of the Software.
17
18THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24OTHER DEALINGS IN THE SOFTWARE.
25EOF
26)
27
28(define example1 #<<EOF
29  (begin-stack
30    9
31    '(1 2 3 4 5)
32    (push (lambda (x) (* x x)))
33    map
34    stk-swap
35    (lambda (x) (lambda (y) (> y x))) ;; returns a function that will be pushed on the stack
36    filter
37    )
38=> (stack 16 25)
39EOF
40)
41
42(define example2 #<<EOF
43  ;; words are easy to create by cut and paste!
44  (define-word map-square-greater-filter
45    (push (lambda (x) (* x x)))
46    map
47    stk-swap
48    (lambda (x) (lambda (y) (> y x)))
49    filter)
50
51  (begin-stack
52    9
53    '(1 2 3 4 5)
54    map-square-greater-filter)
55=> (stack 16 25)
56EOF
57)
58
59(define doc `(
60        (eggdoc:begin
61                (name "stacktor")
62                (description (p "A stack based programming DSL, inspired by " (url "http://factorcode.org/" "Factor")))
63                (author (url "http://chicken.wiki.br/mark-fredrickson" "Mark Fredrickson"))
64                (history
65                        (version "0.5" "Initial release"))
66
67                (usage)
68                (download "stacktor.egg")
69
70                (documentation
71                        (p "Stacktor allows programmers to use stack based programming next to more familiar styles of "
72      "programming such as functional, imperative, object-oriented, etc. In stack programming, "
73      "arguments are taken from the stack, and return values are pushed back on to the stack. Literal "
74      "values are automatically pushed on to the stack. Stack operations (such as dropping the top "
75      "element of the stack) allow programmers to shuffle order of arguments, duplicate arguments, and "
76      "otherwise modify the stack as needed.")
77
78      (p "Stacktor was inspired by " (url "http://factorcode.org/" "Factor") ", \"a practical stack language.\" Factor programs are composed of "
79      "\"words\" and literals. Words are actions that occur on the stack. For example, the \"dup\" word "
80      "takes the top of the stack and pushes an additional copy back on the stack. Words can also be "
81      "composed of a series of other words, allowing the creation of richer levels of abstraction.")
82
83      (p "In Stacktor you can define words using the (define-word ...) form; however, Stacktor will "
84      "convert any Scheme procedure into a word automatically. Therefore, you can use existing Scheme "
85      "procedures right inside of stack actions. When a procedure is found in a word or begin-stack "
86      "form, Stacktor will pop the correct number of arguments (not including \"rest\" arguments) and "
87      "apply the procedure to those arguments. The return value will be pushed onto the stack. Future "
88      "versions of Stactor may push multiple return values onto the stack, though I haven't decided if "
89      "that is a good idea yet.")
90
91      (p "To begin using stack based programming in your code, use the (begin-stack ...) form. Each item "
92      "in the form will be inspected at runtime to see if it is a literal value, a procedure, or a "
93      "Stacktor \"word.\" This form will return a stack object, which you can convert to a list or "
94      "process any other way you choose."
95      )
96
97                        (group
98
99                                (macro "(begin-stack WORD ...)"
100                                        (p "Returns a stack after operating with the supplied words. Words may be literal values (which are "
101                                           "pushed onto the stack), " (tt "word") " record types (typically created elsewhere), or procedures "
102                                           "(which are converted to words at runtime)."))
103
104                                (procedure "(push DATUM)"
105                                        (p "Within the " (tt "begin-stack") " form, you can force pushing items onto the stack. This is most "
106                                           "useful when you want to push a procedure onto the stack, which would usually be converted to a word.")
107                                        (pre "Example: (begin-stack '(1 2 3 4 5) (push (lambda (x) (* x x))) map) => (stack (1 4 9 16 25))")
108                                        (p (i "This keyword may be come a keyword in future releases. Do not count on it remaining a procedure.")))
109                                       
110                          (macro "(begin-with-stack STACK WORD ...)"
111                            (p "Identical to " (tt "begin-stack") " but also pasing in a stack, instead of creating a new one. Mostly "
112                               "useful when defining an usual words, but even then consider other options."))
113                           
114                          (record "word"
115                            (p "The word record is used to mark special procedures. Abstractly, word is a procedure with the signature of " 
116                               (tt "STACK -> STACK") ". For convenience, these procedures are wrapped in a special record type. You "
117                               "can certianly create words directly, but it is recommended you use the included word macros."))
118                          (macro "(word WORD ...)"
119                            (p "Takes one or more words and creates a " (tt "word") " record/procedure.")
120                            (pre "Expands to: (make-word (lambda (stk) (begin-with-stack stk WORD ...)))"))
121                           
122                          (macro "(define-word NAME WORD ...)"
123                            (p "Creates a new word record with name. Basically a convenice macro that in turn wraps " (tt "(word ...)"))
124                            (pre "Expands to: (define NAME (word WORD ...))"))
125                        )
126                       
127                        (subsection "Predefined Words"
128                          (p "By including the " (tt "stacktor-words") " unit, you can pick up some useful predfined words. The following are "
129                              "taken from the " (url "http://factorcode.org/responder/help/show-help?topic=shuffle-words"  "Factor documentation") 
130                              ". They use the Factor documentation style of defining the necessary input stack and the resulting stack. "
131                              "All stack operations have been prefixed with " (tt "stk-") " to prevent name clashes.")
132                          (symbol-table
133                            (describe "stk-drop" "( x -- )")
134          (describe "stk-2drop" "( x y -- )")
135          (describe "stk-3drop" "( x y z -- )")
136          (describe "stk-nip" "( x y -- y )")
137          (describe "stk-2nip" "( x y z -- z )")
138          (describe "stk-dup" "( x -- x x )")
139          (describe "stk-2dup" "( x y -- x y x y )")
140          (describe "stk-3dup" "( x y z -- x y z x y z )")
141          (describe "stk-dupd" "( x y -- x x y )")
142          (describe "stk-over" "( x y -- x y x )")
143          (describe "stk-pick" "( x y z -- x y z x )")
144          (describe "stk-tuck" "( x y -- y x y )")
145          (describe "stk-swap" "( x y -- y x )")
146          (describe "stk-swapd" "( x y z -- y x z )")
147          (describe "stk-rot" "( x y z -- y z x )")
148          (describe "stk--rot" "( x y z -- z x y )")
149          (describe "stk-roll" "( x y z t -- y z t x )")
150          (describe "stk--roll" "( x y z t -- t x y z )"))) ; end symbol table, subsection
151         
152                )
153                (section "Examples"
154                  (subsection "Find the squares of a list greater than a given value"
155                    (pre ,example1))
156                  (subsection "Turn the previous example into a word"
157                    (pre ,example2)))
158                (section "License" (pre ,license))
159        )
160))
161
162(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.