Module reference
1 Cache
(require pollen/cache) | package: pollen |
The slowest part of a render is parsing and decoding the source file. Often, previewing a single source file necessarily means decoding others (for instance templates, or other source files that are linked into the main source file). But usually, only one source file is changing at a time. Therefore, Pollen stores copies of the exports of source files — namely, whatever is stored in doc and metas — in the cache so they can be reused.
parameter
(current-cache) → hash?
(current-cache hash) → void? hash : hash?
= (make-cache)
The cache is a hash table that uses the complete path of a source file as its keys. The value associated with each of these keys is a subcache — another hash table with keys 'doc, 'metas (for storing the exports of the source file) and 'mod-time (for storing the modification time, provided by file-or-directory-modify-seconds).
procedure
(cached-require source-path key) → (or/c txexpr? hash? integer?)
source-path : pathish? key : (or/c 'doc 'metas 'mod-time)
The only keys supported are 'doc, 'metas, and 'mod-time.
If you want the speed benefit of the cache, you should always use cached-require to get data from Pollen source files. That doesn’t mean you can’t still use functions like require, local-require, and dynamic-require. They’ll just be slower.
procedure
(make-cache) → hash?
procedure
(reset-cache) → void?
procedure
(cache-ref source-path) → hash?
source-path : pathish?
2 Decode
(require pollen/decode) | package: pollen |
The doc export of a Pollen markup file is a simple X-expression. Decoding refers to any post-processing of this X-expression. The pollen/decode module provides tools for creating decoders.
The decode step can happen separately from the compilation of the file. But you can also attach a decoder to the markup file’s root node, so the decoding happens automatically when the markup is compiled, and thus automatically incorporated into doc. (Following this approach, you could also attach multiple decoders to different tags within doc.)
You can, of course, embed function calls within Pollen markup. But since markup is optimized for authors, decoding is useful for operations that can or should be moved out of the authoring layer.
One example is presentation and layout. For instance, detect-paragraphs is a decoder function that lets authors mark paragraphs in their source simply by using two carriage returns.
Another example is conversion of output into a particular data format. Most Pollen functions are optimized for HTML output, but one could write a decoder that targets another format.
procedure
(decode tagged-xexpr [ #:txexpr-tag-proc txexpr-tag-proc #:txexpr-attrs-proc txexpr-attrs-proc #:txexpr-elements-proc txexpr-elements-proc #:block-txexpr-proc block-txexpr-proc #:inline-txexpr-proc inline-txexpr-proc #:string-proc string-proc #:symbol-proc symbol-proc #:valid-char-proc valid-char-proc #:cdata-proc cdata-proc #:exclude-tags tags-to-exclude]) → txexpr? tagged-xexpr : txexpr?
txexpr-tag-proc : (txexpr-tag? . -> . txexpr-tag?) = (λ(tag) tag)
txexpr-attrs-proc : (txexpr-attrs? . -> . txexpr-attrs?) = (λ(attrs) attrs)
txexpr-elements-proc : (txexpr-elements? . -> . txexpr-elements?) = (λ(elements) elements) block-txexpr-proc : (block-txexpr? . -> . xexpr?) = (λ(tx) tx) inline-txexpr-proc : (txexpr? . -> . xexpr?) = (λ(tx) tx) string-proc : (string? . -> . xexpr?) = (λ(str) str) symbol-proc : (symbol? . -> . xexpr?) = (λ(sym) sym) valid-char-proc : (valid-char? . -> . xexpr?) = (λ(vc) vc) cdata-proc : (cdata? . -> . xexpr?) = (λ(cdata) cdata) tags-to-exclude : (listof symbol?) = null
This function doesn’t do much on its own. Rather, it provides the hooks upon which harder-working functions can be hung.
Recall from (part "Pollen mechanics") that any tag can have a function attached to it. By default, the tagged-xexpr from a source file is tagged with root. So the typical way to use decode is to attach your decoding functions to it, and then define root to invoke your decode function. Then it will be automatically applied to every doc during compile.
For instance, here’s how decode is attached to root in Butterick’s Practical Typography. There’s not much to it —
(define (root . items) (decode (make-txexpr 'root null items) #:txexpr-elements-proc detect-paragraphs #:block-txexpr-proc (λ(bx) (wrap-hanging-quotes (nonbreaking-last-space bx))) #:string-proc (compose1 smart-quotes smart-dashes)))
This illustrates another important point: even though decode presents an imposing list of arguments, you’re unlikely to use all of them at once. These represent possibilities, not requirements. For instance, let’s see what happens when decode is invoked without any of its optional arguments.
Examples: | |||||
|
Right — nothing. That’s because the default value for the decoding arguments is the identity function, (λ (x) x). So all the input gets passed through intact unless another action is specified.
The *-proc arguments of decode take procedures that are applied to specific categories of elements within txexpr.
The txexpr-tag-proc argument is a procedure that handles X-expression tags.
Examples: | ||||||
|
The txexpr-attrs-proc argument is a procedure that handles lists of X-expression attributes. (The txexpr module, included at no extra charge with Pollen, includes useful helper functions for dealing with these attribute lists.)
Examples: | ||||||
|
Note that txexpr-attrs-proc will change the attributes of every tagged X-expression, even those that don’t have attributes. This is useful, because sometimes you want to add attributes where none existed before. But be careful, because the behavior may make your processing function overinclusive.
Examples: | |||||||||||||||||
|
The txexpr-elements-proc argument is a procedure that operates on the list of elements that represents the content of each tagged X-expression. Note that each element of an X-expression is subject to two passes through the decoder: once now, as a member of the list of elements, and also later, through its type-specific decoder (i.e., string-proc, symbol-proc, and so on).
Examples: | |||||||||||
|
So why do you need txexpr-elements-proc? Because some types of element decoding depend on context, thus it’s necessary to handle the elements as a group. For instance, the doubling function above, though useless, requires handling the element list as a whole, because elements are being added.
A more useful example: paragraph detection. The behavior is not merely a map across each element:
Examples: | ||||||||||||
|
The block-txexpr-proc argument and the inline-txexpr-proc arguments are procedures that operate on tagged X-expressions. If the X-expression meets the block-txexpr? test, it is processed by block-txexpr-proc. Otherwise, it is processed by inline-txexpr-proc. Thus every tagged X-expression will be handled by one or the other. Of course, if you want block and inline elements to be handled the same way, you can set block-txexpr-proc and inline-txexpr-proc to be the same procedure.
Examples: | |||||||||||||||||||
|
The string-proc, symbol-proc, valid-char-proc, and cdata-proc arguments are procedures that operate on X-expressions that are strings, symbols, valid-chars, and CDATA, respectively. Deliberately, the output contracts for these procedures accept any kind of X-expression (meaning, the procedure can change the X-expression type).
Examples: | ||||||||||||||||||||||||
|
Finally, the tags-to-exclude argument is a list of tags that will be exempted from decoding. Though you could get the same result by testing the input within the individual decoding functions, that’s tedious and potentially slower.
Examples: | |||||||
|
The tags-to-exclude argument is useful if you’re decoding source that’s destined to become HTML. According to the HTML spec, material within a <style> or <script> block needs to be preserved literally. In this example, if the CSS and JavaScript blocks are capitalized, they won’t work. So exclude '(style script), and problem solved.
Examples: | ||||||||||||||||||||
|
2.1 Block
Because it’s convenient, Pollen categorizes tagged X-expressions into two categories: block and inline. Why is it convenient? When using decode, you often want to treat the two categories differently. Not that you have to. But this is how you can.
parameter
(project-block-tags) → (listof txexpr-tag?)
(project-block-tags block-tags) → void? block-tags : (listof txexpr-tag?)
= html-block-tags
(address article aside audio blockquote body canvas dd div dl fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 header hgroup noscript ol output p pre section table tfoot ul video)
procedure
(register-block-tag tag) → void?
tag : txexpr-tag?
Pollen tries to do the right thing without being told. But this is the rare case where you have to be explicit. If you introduce a tag into your markup that you want treated as a block, you must use this function to identify it, or you will get spooky behavior later on.
For instance, detect-paragraphs knows that block elements in the markup shouldn’t be wrapped in a p tag. So if you introduce a new block element called bloq without registering it as a block, misbehavior will follow:
Examples: | ||||||
|
But once you register bloq as a block, order is restored:
Examples: | |||||||||
|
If you find the idea of registering block tags unbearable, good news. The project-block-tags include the standard HTML block tags by default. So if you just want to use things like div and p and h1–h6, you’ll get the right behavior for free.
Examples: | |||||
|
procedure
(block-txexpr? v) → boolean?
v : any/c
2.2 Typography
An assortment of typography & layout functions, designed to be used with decode. These aren’t hard to write. So if you like these, use them. If not, make your own.
procedure
(whitespace? v) → boolean?
v : any/c
Examples: | |||||||||||||
|
procedure
(whitespace/nbsp? v) → boolean?
v : any/c
Examples: | |||||||||||||
|
procedure
(smart-quotes str) → string?
str : string?
Examples: | |||||||||||||
|
procedure
(smart-dashes str) → string?
str : string?
Examples: | ||||||||||||
|
procedure
(detect-linebreaks tagged-xexpr-elements [ #:separator linebreak-sep #:insert linebreak]) → txexpr-elements? tagged-xexpr-elements : txexpr-elements? linebreak-sep : string? = world:linebreak-separator linebreak : xexpr? = '(br)
Examples: | ||||
|
procedure
(detect-paragraphs elements [ #:separator paragraph-sep #:tag paragraph-tag #:linebreak-proc linebreak-proc]) → txexpr-elements? elements : txexpr-elements? paragraph-sep : string? = world:paragraph-separator paragraph-tag : symbol? = 'p
linebreak-proc : (txexpr-elements? . -> . txexpr-elements?) = detect-linebreaks
The paragraph-tag argument sets the tag used to wrap paragraphs.
The linebreak-proc argument allows you to use a different linebreaking procedure other than the usual detect-linebreaks.
Examples: | ||||||||||||||
|
3 File
(require pollen/file) | package: pollen |
A utility module that provides functions for working with Pollen source and output files. The tests rely on file extensions specified in pollen/world.
Pollen handles six kinds of source files:
Preprocessor, with file extension .pp.
Markup, with file extension .pm.
Template, with file extension .pt.
Null, with file extension .p.
Scribble, with file extension .scrbl.
For each kind of Pollen source file, the corresponding output file is generated by removing the extension from the name of the source file. So the preprocessor source file default.css.pp would become default.css. Scribble files work differently — the corresponding output file is the source file but with an html extension rather than scrbl. So pollen.scrbl would become pollen.html.
procedure
(preproc-source? v) → boolean?
v : any/c
procedure
(markup-source? v) → boolean?
v : any/c
procedure
(template-source? v) → boolean?
v : any/c
procedure
(null-source? v) → boolean?
v : any/c
procedure
(scribble-source? v) → boolean?
v : any/c
procedure
(pagetree-source? v) → boolean?
v : any/c
Examples: | ||||||||||||
|
procedure
(has-preproc-source? v) → boolean?
v : any/c
procedure
(has-markup-source? v) → boolean?
v : any/c
procedure
(has-template-source? v) → boolean?
v : any/c
procedure
(has-null-source? v) → boolean?
v : any/c
procedure
(has-scribble-source? v) → boolean?
v : any/c
procedure
(has/is-preproc-source? v) → boolean?
v : any/c
procedure
(has/is-markup-source? v) → boolean?
v : any/c
procedure
(has/is-template-source? v) → boolean?
v : any/c
procedure
(has/is-null-source? v) → boolean?
v : any/c
procedure
(has/is-scribble-source? v) → boolean?
v : any/c
procedure
(->preproc-source-path p) → path?
p : pathish?
procedure
(->markup-source-path p) → path?
p : pathish?
procedure
(->template-source-path p) → path?
p : pathish?
procedure
(->null-source-path p) → path?
p : pathish?
procedure
(->scribble-source-path p) → path?
p : pathish?
Examples: | |||||||||||||
|
procedure
(->output-path p) → path?
p : pathish?
Examples: | ||||||||
|
4 Pagetree
(require pollen/pagetree) | package: pollen |
A pagetree is a hierarchical list of Pollen output files. A pagetree source file has the extension .ptree. A pagetree provides a convenient way of separating the structure of the pages from the page sources, and navigating around this structure.
Pagetrees are made of pagenodes. Usually these pagenodes will be names of output files in your project. (If you think it would’ve been more logical to just call them “pages,” perhaps. When I think of a web page, I think of a file on a disk. Whereas pagenodes may — and often do — refer to files that don’t yet exist.)
Books and other long documents are usually organized in a structured way — at minimum they have a sequence of pages, but more often they have sections with subsequences within. Individual Pollen source files don’t know anything about how they’re connected to other files. In theory, you could maintain this information within each source file. This would be a poor use of human energy. Let the pagetree figure it out.
procedure
(pagetree? possible-pagetree) → boolean?
possible-pagetree : any/c
Examples: | ||||||||||||||||
|
procedure
(validate-pagetree possible-pagetree) → pagetree?
possible-pagetree : any/c
Examples: | ||||||
|
procedure
(pagenode? possible-pagenode) → boolean?
possible-pagenode : any/c
Pagenodes are symbols (rather than strings) so that pagetrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.
Examples: | ||||||
|
procedure
(pagenodeish? v) → boolean?
v : any/c
Example: | ||
|
procedure
(->pagenode v) → pagenode?
v : pagenodeish?
Examples: | ||||
|
4.1 Navigation
parameter
(current-pagetree pagetree) → void? pagetree : pagetree?
= #f
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||||||
|
4.2 Utilities
procedure
(pagetree->list pagetree) → list?
pagetree : pagetree?
procedure
(in-pagetree? pagenode [pagetree]) → boolean?
pagenode : pagenode? pagetree : pagetree? = (current-pagetree)
procedure
(path->pagenode p) → pagenode?
p : pathish?
5 Render
(require pollen/render) | package: pollen |
Rendering is how Pollen source files get converted into output.
procedure
(render source-path [template-path]) → bytes?
source-path : complete-path? template-path : (or/c #f complete-path?) = #f
A pollen/pre file is rendered without a template.
A pollen/markup or pollen/markdown file is rendered with a template. If no template is provided with template-path, Pollen finds one using get-template-for.
Be aware that rendering with a template uses include-template within eval. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.
For those panicked at the use of eval, please don’t be. As the author of include-template has already advised, “If you insist on dynamicism” — and yes, I do insist — “there is always eval.”
procedure
(render-to-file source-path [ template-path output-path]) → void? source-path : complete-path? template-path : (or/c #f complete-path?) = #f output-path : (or/c #f complete-path?) = #f
procedure
(render-to-file-if-needed source-path [ template-path output-path #:force force-render?]) → void? source-path : complete-path? template-path : (or/c #f complete-path?) = #f output-path : (or/c #f complete-path?) = #f force-render? : boolean? = #f
The force-render? flag — set with the #:force keyword — is #t.
No file exists at output-path. (Thus, an easy way to force a render of a particular output-path is to delete it.)
Either source-path or template-path have changed since the last trip through render.
One or more of the project requires have changed.
If none of these conditions exist, output-path is deemed to be up to date, and the render is skipped.
procedure
(render-batch source-paths ...) → void?
source-paths : (listof pathish?)
procedure
(render-pagetree pagetree) → void?
pagetree : pagetree? (render-pagetree pagetree-source) → void? pagetree-source : pathish?
procedure
(get-template-for source-path) → (or/c #f complete-path?)
source-path : complete-path?
If the metas for source-path have a key for template, then use the value of this key.
If this key doesn’t exist, or if it points to a nonexistent file, look for a default template in the project directory with the name main.[output extension].pt. Meaning, if source-path is intro.html.pm, the output path would be intro.html, so the default template would be main.html.pt.
If this file doesn’t exist, use the fallback template as a last resort.
This function is called when a template is needed, but a template-path argument is missing (for instance, in render or render-to-file).
6 Template
(require pollen/template) | package: pollen |
Convenience functions for templates. These are automatically imported into the eval environment when rendering with a template (see render).
This module also provides everything from sugar/coerce/value.
procedure
(->html xexpr) → string?
xexpr : xexpr?
Examples: | |||||||
|
Be careful not to pass existing HTML strings into this function, because the angle brackets will be escaped. Fine if that’s what you want, but you probably don’t.
Examples: | |||||||
|
procedure
(select key value-source) → (or/c #f txexpr-element?)
key : symbolish? value-source : (or/c hash? txexpr? pagenode? pathish?)
procedure
(select* key value-source) → (or/c #f (listof txexpr-element?))
key : symbolish? value-source : (or/c hash? txexpr? pagenode? pathish?)
procedure
(select-from-metas key meta-source) → (or/c #f txexpr-element?)
key : symbolish? meta-source : (or/c hash? pagenodeish? pathish?)
Examples: | ||||||||||||||||||
|
procedure
(select-from-doc key doc-source) → (or/c #f txexpr-element?)
key : symbolish? doc-source : (or/c txexpr? pagenodeish? pathish?)
Examples: | ||||||||||||||||||
|
7 Tag
(require pollen/tag) | package: pollen |
Convenience functions for working with tags.
procedure
(make-tag-function id) → (-> txexpr?)
id : txexpr-tag?
Examples: | ||||||||||
|
Entering attributes this way can be cumbersome. So for convenience, a tag function provides an alternative: any symbol + string pairs at the front of your expression will be interpreted as attributes, if the symbols are followed by a colon. If you leave out the colon, the symbols will be interpreted as part of the content of the tag.
Examples: | ||||||||||||||
|
Pollen also uses this function to provide the default behavior for undefined tags. See #%top.
8 Top
(require pollen/top) | package: pollen |
You’ll probably never invoke this module directly. But it’s implicitly imported into every Pollen markup file. And if you don’t know what it does, you might end up surprised by some of the behavior you get.
Examples: | |||||||||
|
In the Pollen markup environment, however, this behavior is annoying. Because when you’re writing X-expressions, you don’t necessarily want to define all your tags ahead of time.
So Pollen redefines #%top. For convenience, Pollen’s version of #%top assumes that an undefined tag should just refer to an X-expression beginning with that tag (and uses make-tag-function to provide this behavior):
Examples: | ||||||||||
|
The good news is that this behavior means you use any tag you want in your markup without defining it in advance. You can still attach a function to the tag later, which will automatically supersede #%top.
Examples: | |||||
|
The bad news is that you’ll never get an “undefined identifier” error. These undefined identifiers will happily sail through and be converted to tags.
Examples: | |||||||||
|
This isn’t a bug. It’s just a natural consequence of how Pollen’s #%top works. It can, however, make debugging difficult sometimes. Let’s suppose my markup depends on very-important-function, which I don’t import correctly.
Examples: | |||||||||||
|
So the undefined-function bug goes unreported. Again, that’s not a bug in Pollen — there’s just no way for it to tell the difference between an identifier that’s deliberately undefined and one that’s inadvertently undefined. If you want to guarantee that you’re invoking a defined identifier, use def/c.
Recall this example from before. In standard Racket, you get an undefined-identifier error.
Examples: | |||||||||
|
But with pollen/top, the issue is not treated as an error.
Examples: | |||||||||||
|
By adding def/c, we restore the usual behavior, guaranteeing that we get the defined version of very-important-function or nothing.
Examples: | ||||||||||||
|
9 World
(require pollen/world) | package: pollen |
A set of global values and parameters that are used throughout the Pollen system. If you don’t like the defaults I’ve picked, change them.
All identifiers are exported with the prefix world:, and are so documented below.
value
world:main-pollen-export : symbol? = 'doc
value
world:meta-pollen-export : symbol? = 'metas
value
world:project-require : string? = "project-require.rkt"
parameter
(world:check-project-requires-in-render?) → boolean?
(world:check-project-requires-in-render? check?) → void? check? : boolean?
= #t
value
world:server-extras-dir : string? = "server-extras"
parameter
(world:current-server-extras-path) → path?
(world:current-server-extras-path dir) → void? dir : path?
= #f
value
world:preproc-source-ext : symbol? = 'pp
value
world:markup-source-ext : symbol? = 'pm
value
world:markdown-source-ext : symbol? = 'pmd
value
world:null-source-ext : symbol? = 'p
value
world:pagetree-source-ext : symbol? = 'ptree
value
world:template-source-ext : symbol? = 'pt
value
world:scribble-source-ext : symbol? = 'scrbl
value
world:decodable-extensions : (listof symbol?)
= (list world:markup-source-ext world:pagetree-source-ext)
value
world:mode-auto : symbol? = 'auto
value
world:mode-preproc : symbol? = 'pre
value
world:mode-markup : symbol? = 'markup
value
world:mode-markdown : symbol? = 'markdown
value
world:mode-pagetree : symbol? = 'ptree
value
world:default-pagetree : string? = "index.ptree"
value
world:pagetree-root-node : symbol? = 'pagetree-root
value
world:command-marker : char? = #\◊
value
world:default-template-prefix : string? = "main"
value
world:fallback-template : string? = "fallback.html.pt"
value
world:template-meta-key : symbol? = 'template
value
world:newline : string? = "\n"
value
world:linebreak-separator : string? = world:newline
value
world:paragraph-separator : string? = "\n\n"
value
world:dashboard-css : string? = "poldash.css"
value
world:paths-excluded-from-dashboard : (listof path?)
= (map string->path (list "poldash.css" "compiled"))