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

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 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-meta doc key [default]) → any/c

  doc : document?
  key : symbol?
  default : failure-result/c
   = (lambda () (raise (make-exn:fail ....)))
Returns the value of key in the document-metas of doc. The value of default is used if the key does not exist: if it is a value, that value will be returned instead; if it is a thunk, the thunk will be called.

Changed in version 1.1 of package punct-lib: Removed get-doc-ref and replaced with get-meta

procedure

(meta-ref doc key) → any/c

  doc : document?
  key : symbol?
Equivalent to (get-meta doc key #f). Provided for compatibility.

5.3 Parse🔗

 (require punct/parse) package: punct-lib

procedure

(parse-markup-elements metas 
  elements 
  #:extract-inline? extract? 
  #:parse-footnotes? parse-fn?) 
 → (or/c document? (listof xexpr?))
  metas : hash-eq?
  elements : list
  extract? : #t
  parse-fn? : #f
Parses elements into a Punct AST by serializing everything as strings, 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 elements inside the paragraph are returned as a list (the paragraph is “shucked”). 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    up