▼Punct:   Common  Mark +   Racket
►5 Module Reference
On this page:
5.1 Core
current-metas
set-meta
?
5.2 Doc
document
5.3 Fetch
get-doc
get-doc-ref
5.4 Parse
parse-markup-elements
    contents  ← prev  up  next → 

5 Module Reference

5.1 Core

 (require punct/core) package: punct-lib

parameter

(current-metas) → (or/c hash-eq? #f)

(current-metas metas) → void?
  metas : (or/c hash-eq? #f)
A parameter that, during compilation of a Punct source, holds the metadata hash table for that file. The final value of this parameter becomes the value of document-metas for that file’s doc as well as its metas export.

The only key automatically defined in every metadata table is 'here-path, which holds the absolute path to the source file.

If no Punct file is currently being compiled, this parameter will hold #f by default. In particular, this parameter is not automatically set to a Punct file’s metas during the rendering phase (e.g., doc->html).

procedure

(set-meta key val) → void?

  key : symbol?
  val : (not/c procedure?)
Set the value of key in current-metas to val. If there are no current metas, an ugly exception is thrown.

syntax

(? key val-expr ...)

Within a Punct file, this macro can be used as shorthand for set-meta. Each key is given as a bare identifier (i.e., without using quote).

#lang punct
 
•?[title "Example Title" author "Me"]
 
...

5.2 Doc

 (require punct/doc) package: punct-lib

The bindings provided by this module are also provided by punct/core.

struct

(struct document (metas body footnotes)
    #:extra-constructor-name make-document
    #:prefab)
  metas : hash-eq?
  body : (listof xexpr?)
  footnotes : (listof xexpr?)
A parsed Punct document.

Changed in version 1.0 of package punct-lib: body and footnotes now guaranteed to be valid X-expressions and not simply lists.

5.3 Fetch

 (require punct/fetch) package: punct-lib

procedure

(get-doc src) → document?

  src : path-string?
Returns the doc binding from src. No caching is used; this function is basically a thin wrapper around dynamic-require. If src does not exist, you will get a friendly error message. If any other kind of problem arises, you will get an ugly error.

procedure

(get-doc-ref src key) → any/c

  src : path-string?
  key : symbol?
Returns the value of key in the metas hash table provided by src, or #f if the key does not exist in that hash table. If src does not exist, you will get a friendly error message. If any other kind of problem arises, you will get an ugly error.

5.4 Parse

 (require punct/parse) package: punct-lib

procedure

(parse-markup-elements metas 
  elements 
  #:extract-inline? extract? 
  #:parse-footnotes? parse-fn?) 
 → (or/c document? list?)
  metas : hash-eq?
  elements : list?
  extract? : #t
  parse-fn? : #f
Parses elements into a Punct AST by serializing everything as a string, sending the string through the commonmark parser, and then converting the result into a Punct document, reconstituting any custom elements in the process.

If #:extract-inline? is #true, and if the parsed document contains only a single paragraph element at the root level, then the inline content of the paragraph is returned as a list. Otherwise, the entire result is returned as a document.

The #:parse-footnotes? argument determines whether the commonmark parser will parse Markdown-style footnote references and definitions in elements.

Examples:
> (define elems
    '("# Title\n\nA paragraph with *italic* text, and "
      1
      (custom "custom element")))
> (parse-markup-elements (hasheq) elems)

'#s(document

    #hasheq()

    ((heading ((level "1")) "Title")

     (paragraph

      "A paragraph with "

      (italic "italic")

      " text, and 1"

      (custom "custom element")))

    ())

    contents  ← prev  up  next →