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.
TOC »
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
- current-docexprparameter
Enables communication with the parsing @-reader
(define current-docexpr (make-parameter #f))
docexpr
- docexprrecord
Composite documentation and adherent expression
- doc
- Documentation for the expression
- expr
- Expression surrounding the documentation
(define-record-and-printer docexpr doc expr)
parse-files
- parse-files #!rest filesprocedure
Parse 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
- with-working-directory directory thunkprocedure
Change 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
- write-example data description expressionsprocedure
Renders 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
- wiki-write-docexprs docexprsprocedure
- wiki-write-docexprs docexprs metafileprocedure
- wiki-write-docexprs docexprs metafile repoprocedure
- wiki-write-docexprs docexprs metafile repo fragment?procedure
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
- tex-write-docexprs docexprsprocedure
- tex-write-docexprs docexprs metafileprocedure
- tex-write-docexprs docexprs metafile repoprocedure
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.