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). For a full introduction to metas, see Inserting metas.
syntax
(define-meta name value)
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 ...)
> (module splicer pollen/markup '(div "one" (@ "two" "three") "four")) > (require 'splicer) > doc '(root (div "one" "two" "three" "four"))
The splicing tag is useful when you want to return a list of X-expressions in a situation where you can only return one. For instance, Tag functions can only return one X-expression. But if we wrap the list of X-expressions in a splicing tag, they behave like a single X-expression. Later, Pollen will merge the list elements into the surrounding expression (as shown above).
> (require pollen/tag) ; wrong: function returns a list of X-expressions
> (define-tag-function (multi attrs elems) '("foo" "bar")) ; right: function returns a list of X-expressions ; as elements inside a splicing tag
> (define-tag-function (multi2 attrs elems) '(@ "foo" "bar"))
Though the splicing tag is cosmetically identical to the abbreviated notation of @ for unquote-splicing, and has a similar purpose, it’s not the same thing. The splicing tag isn’t a variable — it’s just a symbol that Pollen treats specially when generating output.
syntax
(when/splice condition pollen-args)
◊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)
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.
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.
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
key : symbolish? value-source : (or/c hash? txexpr? pagenode? pathish?)
procedure
key : symbolish? value-source : (or/c hash? txexpr? pagenode? pathish?)
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).
> (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?)
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).
> (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?)
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).
> (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
(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.