14 Module reference
14.1 Cache
14.2 Core
14.3 Decode
14.4 File
14.5 Pagetree
14.6 Render
14.7 Setup
14.8 Tag
14.9 Template
14.10 Top
14.2 Core
On this page:
14.2.1 Metas
define-meta
14.2.2 Splicing
@
when/  splice
for/  splice
for*/  splice
14.2.3 Data helpers
get-doc
get-metas
select
select*
select-from-doc
select-from-metas
14.2.4 Parameters
current-metas
6.12

14.2 Core

 (require pollen/core) package: pollen

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

14.2.1 Metas

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 Inserting metas.

14.2.2 Splicing

syntax

(@ arg ...)

Splicing tag: signals that a list should be merged into its containing expression. You can use something other than @ by overriding setup: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.

syntax

(for/splice (for-clause ...) body-or-break ... body)

syntax

(for*/splice (for-clause ...) body-or-break ... body)

Like for/list and for*/list, but the resulting list is spliced into the document.

14.2.3 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 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 setup: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 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 setup: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 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 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 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

14.2.4 Parameters

parameter

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

(current-metas hash)  void?
  hash : (or/c #f hash?)
 = #f
Holds the metas of the current Pollen source. In tag functions, rather than pass metas as an argument, you can refer to (current-metas) within the body of the function. Likewise, if your tag function calls other tag functions, they can all invoke (current-metas) instead of passing the value around.

(current-metas) will also work in templates, holding the metas of the source currently being rendered into the template.

Note that the default value is #f. This indicates that no metas value is available. It is up to you to code your tag functions to do something sensible if this circumstance arises.