Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
cock-utils
Translates in-source documentation from cock into wiki: deprecated for hahn-utils
Deprecation
Cock-utils has been deprecated for hahn-utils.
Introduction
Cock-utils is mainly interesting because it provides the cock program that takes code documented with cock and converts it into documentation.
Cock-utils is a soft-dependency and shouldn't be included in depends.
Invocation
Cock-utils is normally invoked from a .setup file; see this example:
(use cock setup-helper-mod) (setup-shared-extension-module 'landauer (extension-version "0.0.1") compile-options: '(-X cock)) (run-cock -o landauer.wiki landauer.scm landauer-core.scm)
It can also be run from the command line:
cock -o landauer.wiki landauer.scm landauer-core.scm
See cock --help for details.
Documentation
cock-utils
[module] cock-utils
The cock-parse module is responsible for the heavy lifting: creating docexprs (see below) from documented sources code; the drivers then write docexprs as e.g. wiki, LaTeX.
current-docexpr
[parameter] current-docexpr → #fEnables communication with the parsing @-reader
(define current-docexpr (make-parameter #f))
docexpr
[record] docexprComposite documentation and adherent expression
- doc
- Documentation for the expression
- expr
- Expression surrounding the documentation
(define-record-and-printer docexpr doc expr)
parse-files
[procedure] (parse-files . files) → Resultant docexprsParse files into docexprs.
- files
- Cock-documented files to be parsed
(define (parse-files . files)
(parameterize
((docexprs (make-stack)))
(for-each
(lambda (file)
(with-input-from-file
file
(lambda ()
(let read-next ((expression (read)))
(if (not (eof-object? expression))
(begin
(if (current-docexpr)
(docexpr-expr-set! (stack-peek (docexprs)) expression))
(current-docexpr #f)
(read-next (read))))))))
files)
(docexprs)))
with-working-directory
[procedure] (with-working-directory directory thunk) → objectChange to the directory, execute thunk, change back; returns the value of executing thunk.
- directory
- The directory to switch to
- thunk
- The thunk to execute
(define (with-working-directory directory thunk)
(let ((original-directory (current-directory)))
(dynamic-wind
(lambda () (current-directory directory))
thunk
(lambda () (current-directory original-directory)))))
write-example
[procedure] (write-example data description expressions) → unspecifiedRenders an example, evaluating the expressions; attempts to require-extension all modules seen so far.
(define (write-example data description expressions)
(display description)
(newline)
(let ((env (interaction-environment))
(modules (hash-table-ref/default data 'modules '())))
(for-each
(lambda (module) (eval `(require-extension ,module) env))
modules)
(for-each
(lambda (expression)
(fmt #t (columnar " " (with-width 78 (pretty expression))))
(fmt #t
(columnar " => " (with-width 74 (pretty (eval expression env))))
" "
nl))
expressions)))
wiki-write-docexprs
[procedure] (wiki-write-docexprs docexprs) → unspecified[procedure] (wiki-write-docexprs docexprs metafile) → unspecified
[procedure] (wiki-write-docexprs docexprs metafile repo) → unspecified
[procedure] (wiki-write-docexprs docexprs metafile repo fragment?) → unspecified
Write the source-derived docexprs as svnwiki.
- docexprs
- The parsed docexprs
- metafile
- The egg's .meta file
- repo
- The e.g. git-repo
- fragment?
- Whether to produce a document-fragment as opposed to a whole document (useful for debugging)
(define wiki-write-docexprs
(case-lambda
((docexprs) (wiki-write-docexprs docexprs #f))
((docexprs metafile) (wiki-write-docexprs docexprs #f #f))
((docexprs metafile repo) (wiki-write-docexprs docexprs #f #f #f))
((docexprs metafile repo fragment?)
(let* ((document (make-document (make-hash-table) (make-stack)))
(parsed-docexprs (wiki-parse-docexprs document docexprs)))
(let ((data (hash-table-merge
(hash-table-merge
(document-data document)
(parse-metafile metafile))
(repo-metadata repo))))
(let ((author (hash-table-ref/default data 'author (default-author)))
(username
(or (hash-table-ref/default data 'username #f)
(hash-table-ref/default data 'user #f)
(default-user)))
(email (hash-table-ref/default data 'email (default-email)))
(repository
(or (hash-table-ref/default data 'repository #f)
(hash-table-ref/default data 'repo #f)))
(title (let ((title (hash-table-ref/default data 'title #f))
(egg (hash-table-ref/default data 'egg #f)))
(or title egg (default-title))))
(description
(or (hash-table-ref/default data 'description #f)
(hash-table-ref/default data 'synopsis #f)
(default-synopsis)))
(dependencies
(or (hash-table-ref/default data 'depends #f)
(hash-table-ref/default data 'needs #f)
'()))
(license (hash-table-ref/default data 'license #f))
(versions (hash-table-ref/default data 'versions '())))
(unless fragment? (display (wiki-preamble title description)))
(stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))
(unless
fragment?
(display
(wiki-postamble
author
username
license
repository
dependencies
versions)))))))))
tex-write-docexprs
[procedure] (tex-write-docexprs docexprs) → unspecified[procedure] (tex-write-docexprs docexprs metafile) → unspecified
[procedure] (tex-write-docexprs docexprs metafile repo) → unspecified
Write the source-derived docexprs as LaTeX.
- docexprs
- The parsed docexprs
(define tex-write-docexprs
(case-lambda
((docexprs) (tex-write-docexprs docexprs #f))
((docexprs metafile) (tex-write-docexprs docexprs #f #f))
((docexprs metafile repo)
(let* ((document (make-document (make-hash-table) (make-stack)))
(parsed-docexprs (tex-parse-docexprs document docexprs)))
(let ((data (document-data document)))
(write-template
tex-preamble
`((author unquote (hash-table-ref/default data 'author "Anonymous"))
(email unquote
(hash-table-ref/default
data
'email
"anonymous@example.org"))
(title unquote
(hash-table-ref/default data 'title "Documentation")))))
(stack-for-each parsed-docexprs (lambda (docexpr) (docexpr)))
(display tex-footer)))))
About this egg
Author
Repository
https://github.com/klutometis/cock-utils
License
BSD
Dependencies
- alist-lib
- args
- cock
- debug
- define-record-and-printer
- fmt
- git
- matchable
- miscmacros
- shell
- srfi-95
- stack
- usage
Versions
- 0.1.1
- Add dependencies.
- 0.1.2
- Remove circular dependency on cock; use string->symbol to evade reader.
- 0.2
- @internal, @example, @noop, &c.
- 0.2.1
- Do string->symbol on @egg.
- 0.2.2
- Width-specifiers, noop.
- 0.2.3
- @example-no-eval
- 0.2.4
- Add @no-source.
- 0.3
- Read egg- and repo-metadata.
- 0.3.1
- Fix the case of #f versions.
- 0.4
- Setup-helper-like thing: run-cock
- 0.4.1
- Add version<=?.
- 0.4.2
- Move to setup-helper-cock.
- 0.4.3
- Fix the version-sorting mechanism.
- 0.4.4
- Add links to releases.
- 0.4.5
- Actually fix the versioning order.
- 0.4.6
- Use setup-helper-mod.
- 0.4.7
- Remove debug.
- 0.4.8
- Legitimately tag a release.
- 0.5
- Fix evaluation of examples; make testable.
- 0.5.1
- Document; allow multiple expressions in source.
- 0.5.2
- Deprecate this for hahn-utils.
Colophon
Documented by cock.