source: project/wiki/eggref/4/cock-utils @ 32368

Last change on this file since 32368 was 32368, checked in by Peter Danenberg, 6 years ago

graphviz, aima, R, heap, call-with-environment-variables, define-record-and-printer, combinatorics, debug, alist-lib, twilio, animation, sicp: Use hahn and hahn-utils.

File size: 10.4 KB
Line 
1== cock-utils
2
3Translates in-source documentation from cock into wiki:
4deprecated for hahn-utils
5[[toc:]]
6=== Deprecation
7{{Cock-utils}} has been deprecated for [[egg/hahn-utils|hahn-utils]].
8
9
10=== Introduction
11{{Cock-utils}} is mainly interesting because it provides the {{cock}}
12program that takes code documented with [[cock]] and converts
13it into documentation.
14
15
16{{Cock-utils}} is a soft-dependency and shouldn't be included
17in {{depends}}.
18
19
20=== Invocation
21{{Cock-utils}} is normally invoked from a {{.setup}} file;
22see [[https://wiki.call-cc.org/eggref/4/cock#the-setupfile|this
23example]]:
24
25
26<enscript highlight="scheme">(use cock setup-helper-mod)
27(setup-shared-extension-module
28  'landauer
29  (extension-version "0.0.1")
30  compile-options:
31  '(-X cock))
32(run-cock -o landauer.wiki landauer.scm landauer-core.scm)
33</enscript>
34It can also be run from the command line:
35  cock -o landauer.wiki landauer.scm landauer-core.scm
36
37
38See {{cock --help}} for details.
39
40
41=== Documentation
42==== {{cock-utils}}
43'''[module]''' {{cock-utils}}
44
45The cock-parse module is responsible for the heavy lifting:
46creating docexprs (see below) from documented sources code; the
47drivers then write docexprs as e.g. wiki, LaTeX.
48* [[#parse-files]]
49* [[#tex-write-docexprs]]
50* [[#wiki-write-docexprs]]
51* [[#with-working-directory]]
52* [[#version<=?]]
53==== {{current-docexpr}}
54<parameter>current-docexpr → #f</parameter>
55Enables communication with the parsing @-reader
56<enscript highlight="scheme">(define current-docexpr (make-parameter #f))
57</enscript>
58==== {{docexpr}}
59<record>docexpr</record>
60Composite documentation and adherent expression
61; {{doc}} : Documentation for the expression
62; {{expr}} : Expression surrounding the documentation
63<enscript highlight="scheme">(define-record-and-printer docexpr doc expr)
64</enscript>
65==== {{parse-files}}
66<procedure>(parse-files . files) → Resultant docexprs</procedure>
67Parse files into docexprs.
68; {{files}} : Cock-documented files to be parsed
69<enscript highlight="scheme">(define (parse-files . files)
70  (parameterize
71    ((docexprs (make-stack)))
72    (for-each
73      (lambda (file)
74        (with-input-from-file
75          file
76          (lambda ()
77            (let read-next ((expression (read)))
78              (if (not (eof-object? expression))
79                (begin
80                  (if (current-docexpr)
81                    (docexpr-expr-set! (stack-peek (docexprs)) expression))
82                  (current-docexpr #f)
83                  (read-next (read))))))))
84      files)
85    (docexprs)))
86</enscript>
87==== {{with-working-directory}}
88<procedure>(with-working-directory directory thunk) → object</procedure>
89Change to the {{directory}}, execute {{thunk}}, change back;
90returns the value of executing {{thunk}}.
91; {{directory}} : The directory to switch to
92; {{thunk}} : The thunk to execute
93<enscript highlight="scheme">(define (with-working-directory directory thunk)
94  (let ((original-directory (current-directory)))
95    (dynamic-wind
96      (lambda () (current-directory directory))
97      thunk
98      (lambda () (current-directory original-directory)))))
99</enscript>
100==== {{write-example}}
101<procedure>(write-example data description expressions) → unspecified</procedure>
102Renders an example, evaluating the expressions; attempts
103to {{require-extension}} all modules seen so far.
104
105<enscript highlight="scheme">(define (write-example data description expressions)
106  (display description)
107  (newline)
108  (let ((env (interaction-environment))
109        (modules (hash-table-ref/default data 'modules '())))
110    (for-each
111      (lambda (module) (eval `(require-extension ,module) env))
112      modules)
113    (for-each
114      (lambda (expression)
115        (fmt #t (columnar " " (with-width 78 (pretty expression))))
116        (fmt #t
117             (columnar "  => " (with-width 74 (pretty (eval expression env))))
118             " "
119             nl))
120      expressions)))
121</enscript>
122==== {{wiki-write-docexprs}}
123<procedure>(wiki-write-docexprs docexprs) → unspecified</procedure>
124<procedure>(wiki-write-docexprs docexprs metafile) → unspecified</procedure>
125<procedure>(wiki-write-docexprs docexprs metafile repo) → unspecified</procedure>
126<procedure>(wiki-write-docexprs docexprs metafile repo fragment?) → unspecified</procedure>
127Write the source-derived docexprs as svnwiki.
128; {{docexprs}} : The parsed docexprs
129; {{metafile}} : The egg's .meta file
130; {{repo}} : The e.g. git-repo
131; {{fragment?}} : Whether to produce a document-fragment as opposed to a whole document (useful for debugging)
132<enscript highlight="scheme">(define wiki-write-docexprs
133  (case-lambda
134    ((docexprs) (wiki-write-docexprs docexprs #f))
135    ((docexprs metafile) (wiki-write-docexprs docexprs #f #f))
136    ((docexprs metafile repo) (wiki-write-docexprs docexprs #f #f #f))
137    ((docexprs metafile repo fragment?)
138     (let* ((document (make-document (make-hash-table) (make-stack)))
139            (parsed-docexprs (wiki-parse-docexprs document docexprs)))
140       (let ((data (hash-table-merge
141                     (hash-table-merge
142                       (document-data document)
143                       (parse-metafile metafile))
144                     (repo-metadata repo))))
145         (let ((author (hash-table-ref/default data 'author (default-author)))
146               (username
147                 (or (hash-table-ref/default data 'username #f)
148                     (hash-table-ref/default data 'user #f)
149                     (default-user)))
150               (email (hash-table-ref/default data 'email (default-email)))
151               (repository
152                 (or (hash-table-ref/default data 'repository #f)
153                     (hash-table-ref/default data 'repo #f)))
154               (title (let ((title (hash-table-ref/default data 'title #f))
155                            (egg (hash-table-ref/default data 'egg #f)))
156                        (or title egg (default-title))))
157               (description
158                 (or (hash-table-ref/default data 'description #f)
159                     (hash-table-ref/default data 'synopsis #f)
160                     (default-synopsis)))
161               (dependencies
162                 (or (hash-table-ref/default data 'depends #f)
163                     (hash-table-ref/default data 'needs #f)
164                     '()))
165               (license (hash-table-ref/default data 'license #f))
166               (versions (hash-table-ref/default data 'versions '())))
167           (unless fragment? (display (wiki-preamble title description)))
168           (stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))
169           (unless
170             fragment?
171             (display
172               (wiki-postamble
173                 author
174                 username
175                 license
176                 repository
177                 dependencies
178                 versions)))))))))
179</enscript>
180==== {{tex-write-docexprs}}
181<procedure>(tex-write-docexprs docexprs) → unspecified</procedure>
182<procedure>(tex-write-docexprs docexprs metafile) → unspecified</procedure>
183<procedure>(tex-write-docexprs docexprs metafile repo) → unspecified</procedure>
184Write the source-derived docexprs as LaTeX.
185; {{docexprs}} : The parsed docexprs
186<enscript highlight="scheme">(define tex-write-docexprs
187  (case-lambda
188    ((docexprs) (tex-write-docexprs docexprs #f))
189    ((docexprs metafile) (tex-write-docexprs docexprs #f #f))
190    ((docexprs metafile repo)
191     (let* ((document (make-document (make-hash-table) (make-stack)))
192            (parsed-docexprs (tex-parse-docexprs document docexprs)))
193       (let ((data (document-data document)))
194         (write-template
195           tex-preamble
196           `((author unquote (hash-table-ref/default data 'author "Anonymous"))
197             (email unquote
198                    (hash-table-ref/default
199                      data
200                      'email
201                      "anonymous@example.org"))
202             (title unquote
203                    (hash-table-ref/default data 'title "Documentation")))))
204       (stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))
205       (display tex-footer)))))
206</enscript>
207=== About this egg
208
209==== Author
210
211[[/users/(anonymous)|Peter Danenberg]]
212==== Repository
213[[https://github.com/klutometis/cock-utils]]
214==== License
215BSD
216==== Dependencies
217* [[alist-lib]]
218* [[args]]
219* [[cock]]
220* [[debug]]
221* [[define-record-and-printer]]
222* [[fmt]]
223* [[git]]
224* [[matchable]]
225* [[miscmacros]]
226* [[shell]]
227* [[srfi-95]]
228* [[stack]]
229* [[usage]]
230
231==== Versions
232; [[https://github.com/klutometis/cock-utils/releases/tag/0.1.1|0.1.1]] : Add dependencies.
233; [[https://github.com/klutometis/cock-utils/releases/tag/0.1.2|0.1.2]] : Remove circular dependency on cock; use string->symbol to evade reader.
234; [[https://github.com/klutometis/cock-utils/releases/tag/0.2|0.2]] : @internal, @example, @noop, &c.
235; [[https://github.com/klutometis/cock-utils/releases/tag/0.2.1|0.2.1]] : Do string->symbol on @egg.
236; [[https://github.com/klutometis/cock-utils/releases/tag/0.2.2|0.2.2]] : Width-specifiers, noop.
237; [[https://github.com/klutometis/cock-utils/releases/tag/0.2.3|0.2.3]] : @example-no-eval
238; [[https://github.com/klutometis/cock-utils/releases/tag/0.2.4|0.2.4]] : Add @no-source.
239; [[https://github.com/klutometis/cock-utils/releases/tag/0.3|0.3]] : Read egg- and repo-metadata.
240; [[https://github.com/klutometis/cock-utils/releases/tag/0.3.1|0.3.1]] : Fix the case of #f versions.
241; [[https://github.com/klutometis/cock-utils/releases/tag/0.4|0.4]] : Setup-helper-like thing: run-cock
242; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.1|0.4.1]] : Add version<=?.
243; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.2|0.4.2]] : Move to setup-helper-cock.
244; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.3|0.4.3]] : Fix the version-sorting mechanism.
245; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.4|0.4.4]] : Add links to releases.
246; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.5|0.4.5]] : Actually fix the versioning order.
247; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.6|0.4.6]] : Use setup-helper-mod.
248; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.7|0.4.7]] : Remove debug.
249; [[https://github.com/klutometis/cock-utils/releases/tag/0.4.8|0.4.8]] : Legitimately tag a release.
250; [[https://github.com/klutometis/cock-utils/releases/tag/0.5|0.5]] : Fix evaluation of examples; make testable.
251; [[https://github.com/klutometis/cock-utils/releases/tag/0.5.1|0.5.1]] : Document; allow multiple expressions in source.
252; [[https://github.com/klutometis/cock-utils/releases/tag/0.5.2|0.5.2]] : Deprecate this for hahn-utils.
253==== Colophon
254
255Documented by [[/egg/cock|cock]].
Note: See TracBrowser for help on using the repository browser.