5 Module Reference

5 Module Reference🔗

5.1 Core🔗

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.1.1 Elements🔗

(require punct/element)

package: punct-lib

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

procedure
(default-element-function tag
default-attr-kw
default-attr-val ...)
→ (->* () #:rest any/c xexpr?)
  tag : symbol?
  default-attr-kw : keyword?
  default-attr-val : string?

Returns a function which produces a tag custom element. This function takes any number of keyword arguments (which are converted to attributes) and non-keyword arguments (which become the child elements of this returned element).

You can also give keyword/value arguments to default-element-function itself; these will be set as default attributes/values in the custom element returned by the resulting function.

Examples:

> (define aside (default-element-function 'aside))
> (aside "Hello")
'(aside "Hello")
> (define kbd (default-element-function 'kbd #:alt "foo"))
> (kbd "CTRL")
'(kbd ((alt "foo")) "CTRL")
> (kbd "CTRL" #:data-code "1")
'(kbd ((alt "foo") (data-code "1")) "CTRL")

On Mac OS, type ALT+6 to produce § and ALT+7 to produce ¶.

If tag ends in either § or ¶, the resulting function will add a default block attribute of "root" or "single" respectively:

Examples:

> (define info (default-element-function 'info§))
> (info "Note!")
'(info ((block "root")) "Note!")
> (define mypar (default-element-function 'mypar¶))
> (mypar "Walnuts")
'(mypar ((block "single")) "Walnuts")

If tag has a suffix of the form .foo, the resulting function will add a default 'class attribute whose value is set to "foo". Multiple such suffixes will add additional values to the 'class attribute.

Examples:

> (define carton (default-element-function 'carton.xyz.abc))
> (carton "Cashews")
'(carton ((class "xyz abc")) "Cashews")
> (define crate (default-element-function 'crate¶.foo))
> (crate "Pecans")
'(crate ((block "single") (class "foo")) "Pecans")

Added in version 1.3 of package punct-lib.

syntax
(define-element id [default-attr-kw default-attr-val ...])
(define-element id tag [default-attr-kw default-attr-val ...])

default-attr-kw : keyword?
default-attr-val : string?

Shorthand macro for default-element-function.

If tag is supplied, it is used as the tag for the X-expressions generated by the resulting function:

> (define-element bowl container.bowl)
> (bowl "Corn nuts")
'(container ((class "bowl")) "Corn nuts")
> (define-element jar vessel¶ #:type "Glass")
> (jar "Chestnuts")
'(vessel ((type "Glass") (block "single")) "Chestnuts")

If tag is not supplied, the first argument is used both as the identifier for the function and for the tag in generated X-expressions:

> (define-element bag.xyz.abc)
> (bag "Sunflower seeds")
'(ID "Sunflower seeds")
> (define-element packet¶.foo)
> (packet "Raisins")
'(ID "Raisins")

Added in version 1.3 of package punct-lib.

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 ← prev up next →

1	Quick start
2	Writing Punct
3	Document structure
4	Rendering output
5	Module Reference
6	Differences from Pollen

5.1	Core
5.2	Fetch
5.3	Parse