Core

6.4.0.4

Core

package: pollen

These functions are automatically imported into every Pollen source file (meaning, as if they had been included in your "pollen.rkt").

1 Syntactic forms

syntax
(define-meta name value)

Add value to the metas of the current document, using name as the key.

You can retrieve a meta value — even in the same document where you define it — with (select-from-metas name metas).

For an introduction to metas, see (part "Inserting_metas").

syntax
(@ arg ...)

Splicing tag: signals that a list should be merged into its containing expression. You can use something other than @ by overriding world:current-splicing-tag.

Examples:

> (module splicer pollen/markup
'(div "one" (@ "two" "three") "four"))
> (require 'splicer)
> doc
'(root (div "one" "two" "three" "four"))

syntax
(when/splice condition pollen-args)

If condition is true, put the pollen-args into the document. Within a template file, usually invoked like so:

◊when/splice[condition]{The text to insert.}

The inserted text can contain its own nested Pollen commands.

when/splice can be more convenient than when, because when will only use the last argument between the curly braces. when/splice, by contrast, treats everything between the curly braces as a block.

2 Data helpers

Functions for retrieving data out of Pollen source files. These are not the only options – you can, of course, use any of the usual Racket functions.

procedure
(get-doc doc-source) → (or/c txexpr? string?)
doc-source : (or/c pagenode? pathish?)

Retrieve the doc export from doc-source, which can be either a path, path string, or pagenode that can be resolved into a source path. If doc-source cannot be resolved, raise an error.

If doc-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

If world:current-main-export has been overridden with a project-specific value, then that is retrieved instead.

procedure
(get-metas meta-source) → hash?
meta-source : (or/c pagenode? pathish?)

Retrieve the metas export from meta-source, which can be either a path, path string, or pagenode that can be resolved into a source path. If meta-source cannot be resolved, raise an error.

If meta-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

If world:current-meta-export has been overridden with a project-specific value, then that is retrieved instead.

procedure
(select key value-source) → (or/c #f xexpr?)
  key : symbolish?
  value-source : (or/c hash? txexpr? pagenode? pathish?)
procedure
(select* key value-source) → (or/c #f (listof xexpr?))
  key : symbolish?
  value-source : (or/c hash? txexpr? pagenode? pathish?)

Find matches for key in value-source. The value-source can be 1) a hashtable of metas, 2) a tagged X-expression representing a doc, or 3) a pagenode or path that identifies a source file that provides metas and doc. In that case, first look for key in metas (using select-from-metas) and then in doc (using select-from-doc).

With select, you get the first result; with select*, you get them all.

In both cases, you get #f if there are no matches.

Note that if value-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (module nut-butters pollen/markup
  '(div (question "Flavor?")
    (answer "Cashew") (answer "Almond")))
; Import doc from 'nut-butters submodule
> (require 'nut-butters)
> (select 'question  doc)
"Flavor?"
> (select 'answer  doc)
"Cashew"
> (select* 'answer  doc)
'("Cashew" "Almond")
> (select 'nonexistent-key doc)
#f
> (select* 'nonexistent-key doc)
#f

procedure
(select-from-doc key doc-source) → (or/c #f (listof xexpr?))
key : symbolish?
doc-source : (or/c txexpr? pagenodeish? pathish?)

Look up the value of key in doc-source. The doc-source argument can be either 1) a tagged X-expression representing a doc or 2) a pagenode or source path that identifies a source file that provides doc. If no value exists for key, you get #f.

Note that if doc-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (module gelato pollen/markup
  '(div (question "Flavor?")
    (answer "Nocciola") (answer "Pistachio")))
; Import doc from 'gelato submodule
> (require 'gelato)
> (select-from-doc 'question  doc)
'("Flavor?")
> ('answer . select-from-doc . doc)
'("Nocciola" "Pistachio")
> (select-from-doc 'nonexistent-key doc)
#f

procedure
(select-from-metas key meta-source) → (or/c #f xexpr?)
key : symbolish?
meta-source : (or/c hash? pagenodeish? pathish?)

Look up the value of key in meta-source. The meta-source argument can be either 1) a hashtable representing metas or 2) a pagenode or source path that identifies a source file that provides metas. If no value exists for key, you get #f.

Note that if meta-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (define metas (hash 'template "sub.xml.pp" 'target "print"))
> (select-from-metas 'template metas)
"sub.xml.pp"
> ('target . select-from-metas . metas)
"print"
> (select-from-metas 'nonexistent-key metas)
#f