You are looking at historical revision 39572 of this page. It may differ significantly from its current revision.
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.
hahn-utils
Translates in-source documentation from hahn into wiki.
Introduction
Hahn-utils is mainly interesting because it provides the hahn program that takes code documented with hahn and converts it into documentation.
Hahn-utils is a soft-dependency and shouldn't be included in depends.
Invocation
Hahn-utils is normally invoked from a .setup file; see this example:
(use hahn setup-helper-mod) (setup-shared-extension-module 'landauer (extension-version "0.0.1") compile-options: '(-X hahn)) (run-hahn -o landauer.wiki landauer.scm landauer-core.scm)
It can also be run from the command line:
hahn -o landauer.wiki landauer.scm landauer-core.scm
See hahn --help for details.
Documentation
hahn-utils
[module] hahn-utils
The hahn-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
- Hahn-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/hahn-utils
License
BSD
Dependencies
- alist-lib
- args
- hahn
- 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
- Refactor as hahn-utils.
Colophon
Documented by hahn.