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
7.7

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

The only key that’s automatically defined in every meta table is 'here-path, which holds the absolute path to the source file. For instance, you could retrieve this value with (select-from-metas 'here-path metas). You can use something other than 'here-path as the key by overriding setup:here-path-key.

For a full introduction to metas, see Inserting 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).

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.

Added in version 1.4 of package pollen.

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)  any/c

  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 val)  void?
  val : (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.

The default value is #f. This means that no metas value is available. It’s your responsibility to handle this circumstance sensibly.

Added in version 1.4 of package pollen.