The following is the list of modules provided by this library. The stylesheet and the script that present this chapter in a browser are written beside it, as dokgen.css and dokgen.js; the manual says how a build points at them.
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
#<procedure 7f2d6f4f1f28 at orgwebalchemy/html.scm:662:18 _>
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Default value:
()
Return the ‘id’ attributes for a heading whose title is text. The id is exactly the anchor an Org ‘*Heading’ link points at, so a heading and the links to it agree by construction. A title with nothing anchor-worthy in it (an empty one, or one made only of punctuation) gets no id at all.
Convert an inline Org AST into an HTML string.
Convert an inline Org AST into a list of SXML nodes.
Construct an SXML attribute node if classes or extra attributes exist.
Convert an Org-mode string into an HTML string.
Convert an Org-mode string into SXML.
Convert a document Org AST into an HTML string.
Convert a document Org AST into a list of SXML block nodes.
Render an SXML tree or list of SXML nodes to an HTML string, preserving raw HTML nodes.
The AST as JSON: the tree the renderers walk, written down as data another language can read. The shape is the contract and there are only three rules:
- a document is always a JSON array of nodes, so one element and ten elements arrive the same way; - a node is always ‘{"type": "<tag>", "children": [...]}’, with the tag spelling the node of the vocabulary, so no node needs a rule of its own; - everything else is a JSON string.
Prose is resolved first: a ‘line-content’, a ‘desc-key’, a ‘table-cell’ and the fields that carry markup inside markup become the inline nodes the renderers see, because a caller that has to reimplement the inline grammar has not been given the tree.
Guile’s standard library has no JSON writer and this library has no runtime dependency beyond Guile, so the writer is here: three rules is little enough to write down, and nothing else is needed to serialise the vocabulary.
(define-module (orgwebalchemy json) #:declarative? #t #:use-module (ice-9 format) #:use-module (orgwebalchemy peg) #:export (org->json org-ast->json inline-org->json json-string))
===================================================================== Strings =====================================================================
(define json-short-escapes ;; The five whitespace characters JSON has a name for. A character with a ;; name reads better in a diff than the same character numbered. ’((#\newline . "\\n") (#\return . "\\r") (#\tab . "\\t") (#\backspace . "\\b") (#\page . "\\f")))
(define (json-string str) "Return str as a JSON string literal, quotes included. A quote, a backslash and a character below U+0020 are escaped as JSON requires; everything else, non-ASCII included, is written as the UTF-8 text it is." (call-with-output-string (lambda (port) (write-char #\" port) (string-for-each (lambda (c) (let ((escape (assv c json-short-escapes))) (cond ((char=? c #\") (display "\\\"" port)) ((char=? c #\\) (display "\\\\" port)) (escape (display (cdr escape) port)) ((char<? c #\space) (format port "\\u~4,’0x" (char->integer c))) (else (write-char c port))))) str) (write-char #\" port))))
===================================================================== The Tree =====================================================================
(define prose-fields ;; The nodes whose one child is Org text rather than plain text: the fields ;; the renderers hand to the inline parser before they write anything. A ;; field that is not here is literal – a source block’s contents, a ;; keyword’s value – and reaches JSON exactly as it was written. ’(line-content desc-key table-cell inline-bold-content inline-italic-content inline-underline-content inline-strike-content inline-superscript-content inline-subscript-content link-description-content footnote-content))
(define (resolve-prose node) "Return node with every prose field replaced by the nodes it parses to. The inline parser is the renderers’ own, so the tree this gives a foreign language is the tree this library renders from." (cond ((string? node) node) ((and (pair? node) (symbol? (car node))) (if (and (memq (car node) prose-fields) (pair? (cdr node)) (string? (cadr node))) (cons (car node) (map resolve-prose (inline-nodes (inline-org->ast (cadr node))))) (cons (car node) (map resolve-prose (cdr node))))) ((pair? node) (map resolve-prose node)) (else node)))
(define (write-array nodes port) "Write the list nodes to port as a JSON array." (display "[" port) (let loop ((nodes nodes) (rest? #f)) (when (pair? nodes) (when rest? (display "," port)) (write-value (car nodes) port) (loop (cdr nodes) #t))) (display "]" port))
(define (write-value node port) "Write one value of the tree node to port. A string is a JSON string and a node is an object of a type and its children, which is every value an AST holds; anything else is an error rather than a ‘null’ nobody can explain later. A node with no children arrives as the bare tag symbol, because an empty match collapses to it in the tree, so a symbol is a node with an empty child list rather than a gap." (cond ((string? node) (display (json-string node) port)) ((and (pair? node) (symbol? (car node))) (write-object (car node) (cdr node) port)) ((symbol? node) (write-object node ’() port)) ((list? node) (write-array node port)) (else (error "orgwebalchemy json: a string or a node was expected, got" node))))
(define (write-object type children port) "Write the node type with children to port as an object." (display "{\"type\":" port) (display (json-string (symbol->string type)) port) (display ",\"children\":" port) (write-array children port) (display "}" port))
===================================================================== Entry Points =====================================================================
(define (org-ast->json ast) "Return the document AST ast as a JSON array of nodes. The document’s own ‘#+NAME:’ targets are in scope while it is written, so a bare ‘[[name]]’ link is serialised as the fragment the renderers give it." (parameterize ((element-names (document-names ast))) (call-with-output-string (lambda (port) (write-array (map resolve-prose (inline-nodes ast)) port)))))
(define (org->json str) "Parse the Org document str and return its tree as JSON text." (org-ast->json (org->ast str)))
(define (inline-org->json str) "Parse the inline Org markup str and return its nodes as JSON text." (call-with-output-string (lambda (port) (write-array (map resolve-prose (inline-nodes (inline-org->ast str))) port))))
Parse the inline Org markup str and return its nodes as JSON text.
Return str as a JSON string literal, quotes included. A quote, a backslash and a character below U+0020 are escaped as JSON requires; everything else, non-ASCII included, is written as the UTF-8 text it is.
Parse the Org document str and return its tree as JSON text.
Return the document AST ast as a JSON array of nodes. The document’s own ‘#+NAME:’ targets are in scope while it is written, so a bare ‘[[name]]’ link is serialised as the fragment the renderers give it.
Convert an inline Org AST ast into a Markdown string.
Convert an Org-mode string str into a Markdown string.
Convert a document Org AST ast into a Markdown string. The document’s own ‘#+NAME:’ targets are in scope while it renders, so a bare ‘[[name]]’ link is parsed as the cross-reference it is.
The grammar and the two entry points every renderer reads through: a whole Org document becomes a tree with ‘org->ast’, and a string of inline Org markup becomes a tree with ‘inline-org->ast’. Nothing here renders: the module knows the language, the renderers know the output.
Mermaid diagram, as source:
flowchart LR org["Org text"] --> doc["org->ast<br/>block grammar"] inline["inline text"] --> inline-ast["inline-org->ast<br/>inline grammar"] doc --> tree["an AST of tagged lists"] inline-ast --> tree tree --> html["(orgwebalchemy html)"] tree --> markdown["(orgwebalchemy markdown)"] tree --> json["(orgwebalchemy json)"]
The links, figures and named elements are classified once, here, so the renderers cannot disagree about what a target means.
(name caption target description) for the figure
node.
(todo priority tags text) for the children of a heading.
unordered, ordered,
(name element) for the named element node.
#t when the Org link target should render as an
image.
#f.
Default value:
()
Default value:
()
Return the names the elements of the parsed document nodes carry.
Return (name caption target description) for the figure
node. Every part the figure does not have comes back as
#f.
Group consecutive items of the same kind into (kind .
items) runs, preserving their original order. One Org list may mix
unordered, ordered and description items, so each run becomes a list
element of its own.
Return (todo priority tags text) for the children of a heading. A
heading is split into these by process-ast; anything it does not
have comes back as #f, except the tags, which are the empty list.
Return ast as a list of nodes, whatever shape it came in. A parser hands back one node, a list of nodes or nothing at all, depending on what it matched; this is the one place that shape is flattened.
Parse inline Org-mode markup from text. Applies the
inline-content PEG pattern to process bold, italic, raw URLs,
inline code, and links, returning the resulting AST. A link whose bare
target names an element of the document being rendered resolves to that
element; see element-names.
Return the kind of a list item: unordered, ordered,
description or other.
Return (name element) for the named element node.
Parse an entire Org-mode document string str into an Abstract
Syntax Tree. This is the main entry point for the parser. It matches
the org-doc PEG pattern and then applies process-ast to
resolve hierarchical constructs like nested lists, folds ‘#+NAME:’ and
‘#+CAPTION:’ keywords into the elements they describe, and resolves a
link whose bare target names an element of the document. A single
top-level element comes back as that element’s node; several come back
as a list of nodes.
Return a URL-fragment-safe anchor for text. Lower-case letters
and digits survive, every run of anything else becomes a single dash,
and leading or trailing dashes are dropped: ‘My First Section’ becomes
my-first-section. Headings carry this as their id and
‘*Heading’ links point at it, so the two agree by construction.
Return #t when the Org link target should render as an
image. A ‘file:’ link (or a bare path) whose extension is one of
org-image-extensions counts, as does a data:image/... URI.
Return the text Org shows for a link target that has no description. An internal or heading link shows its id or title, a file link its path, and a link with a scheme of its own the full URL. A target a resolver rewrote shows what the document wrote instead, because ‘[[yt:dQw4w9WgXcQ]]’ says exactly that, and the href is where the resolution belongs.
Return the href an Org link target should point at. A resolver
bound in link-protocols decides first, for any protocol. On its
own, a file link gives its path, ‘#custom-id’ and ‘*Heading’ links give
a local fragment, and a link with a scheme of its own keeps it.
Split the Org link target into (protocol . path).
protocol is a symbol:
http, https, mailto, data and friends, for a
link that carries a URL scheme of its own;
file for a file: link and for a bare path such as
notes.org;
internal for a #custom-id link;
heading for a *Heading link.
path is target with its prefix removed and with any
‘::search’ suffix dropped, so it is ready to be used as an href or a
file name. org-link-search returns that suffix separately.
Return the path of the Org link target, without protocol or search part.
Return the protocol symbol of the Org link target. See
org-link-parts for the possible values.
Return the ‘::search’ part of the Org link target, or #f.
This is the *Heading' or #anchor that a file link points
inside the linked document; it is not something the renderers act on
yet.
Return (state . rest) when text starts with an Org
checkbox. state is #t for ‘[X] ’/‘[x] ’ and #f for
‘[ ] ’; rest is the item text with the checkbox removed. Returns
#f when text is not a checkbox item.
Return str without leading or trailing spaces and tabs.