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 → #f

Enables communication with the parsing @-reader

(define current-docexpr (make-parameter #f))

docexpr

[record] docexpr

Composite 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 docexprs

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

[procedure] (with-working-directory directory thunk) → object

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

[procedure] (write-example data description expressions) → unspecified

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

[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

Peter Danenberg

Repository

https://github.com/klutometis/hahn-utils

License

BSD

Dependencies

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.