14.7 Setup

7.7

top ← prev up next →

14.7 Setup

(require pollen/setup)

package: pollen

14.7.1 How to override setup values

The values below can be changed by overriding them in your "pollen.rkt" source file:

Within this file, create a submodule called setup.
Within this submodule, use define to make a variable with the same name as the one in pollen/setup, but without the setup: prefix.
Assign it whatever value you like.
Repeat as needed.
(Don’t forget to provide the variables from within your setup submodule.)

When Pollen runs, these definitions will supersede those in pollen/setup.

For instance, suppose you wanted the main export of every Pollen source file to be called van-halen rather than doc, the extension of Pollen markup files to be .rock rather than .pm, and the command character to be 🎸 instead of ◊. Your "pollen.rkt" would look like this:

"pollen.rkt"

#lang racket/base

;; ... the usual definitions and tag functions ...

(module setup racket/base
  (provide (all-defined-out))
  (define main-export 'van-halen)
  (define markup-source-ext 'rock)
  (define command-char #\🎸))

Of course, you can restore the defaults simply by removing these defined values from "pollen.rkt".

Every setup:name function will resolve the current value of that variable: it will return the value from the setup submodule (if name was defined there), otherwise it will return the default value (which is directly available from default-name). For instance, default-command-char will always be ◊, but in the example above, (setup:command-char) would return 🎸.

14.7.2 Values

procedure
(setup:project-server-port) → integer?
value
default-project-server-port : integer? = 8080

Determines the default HTTP port for the project server.

procedure
(setup:main-export) → symbol?
value
default-main-export : symbol? = 'doc

The main X-expression exported from a compiled Pollen source file.

procedure
(setup:meta-export) → symbol?
value
default-meta-export : symbol? = 'metas

The meta hashtable exported from a compiled Pollen source file.

procedure
(setup:extension-escape-char) → char?
value
default-extension-escape-char : char? = #\_

Character for escaping output-file extensions within source-file names.

procedure
(setup:preproc-source-ext) → symbol?
value
default-preproc-source-ext : symbol? = 'pp
procedure
(setup:markup-source-ext) → symbol?
value
default-markup-source-ext : symbol? = 'pm
procedure
(setup:markdown-source-ext) → symbol?
value
default-markdown-source-ext : symbol? = 'pmd
procedure
(setup:null-source-ext) → symbol?
value
default-null-source-ext : symbol? = 'p
procedure
(setup:pagetree-source-ext) → symbol?
value
default-pagetree-source-ext : symbol? = 'ptree
procedure
(setup:template-source-ext) → symbol?
value
default-template-source-ext : symbol? = 'pt
procedure
(setup:scribble-source-ext) → symbol?
value
default-scribble-source-ext : symbol? = 'scrbl

File extensions for Pollen source files.

procedure
(setup:main-pagetree) → string?
value
default-main-pagetree : string? = "index.ptree"

Pagetree that Pollen dashboard loads by default in each directory.

procedure
(setup:main-root-node) → symbol?
value
default-main-root-node : symbol? = 'root

Name of the root node in a decoded doc.

procedure
(setup:block-tags) → (listof symbol?)
value
default-block-tags : (listof symbol?) = '(see below)

Tags that are treated as blocks by block-txexpr?. Initialized to the block-level elements in HTML5, namely:

address article aside blockquote body canvas dd div dl fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 header hgroup hr li main nav noscript ol output p pre section table tfoot ul video

... plus setup:main-root-node.

procedure
(setup:command-char) → char?
value
default-command-char : char? = #\◊

The magic character that indicates a Pollen command, function, or variable.

procedure
(setup:template-prefix) → string?
value
default-template-prefix : string? = "template"

Prefix of the default template.

procedure
(setup:newline) → string?
value
default-newline : string? = "\n"
procedure
(setup:linebreak-separator) → string?
value
default-linebreak-separator : string? = "\n"
procedure
(setup:paragraph-separator) → string?
value
default-paragraph-separator : string? = "\n\n"

Default separators used in decoding.

procedure
(setup:render-cache-active) → boolean?
value
default-render-cache-active : boolean? = #t

Whether the render cache, which speeds up interactive sessions by reusing rendered versions of Pollen output files, is active.

procedure
(setup:compile-cache-active) → boolean?
value
default-compile-cache-active : boolean? = #t

Whether the compile cache, which speeds up interactive sessions by saving compiled versions of Pollen source files, is active.

procedure
(setup:compile-cache-max-size) → exact-positive-integer?
value
default-compile-cache-max-size : exact-positive-integer?
= 10485760

Maximum size of the compile cache.

procedure
(setup:cache-watchlist) → (listof (or/c path? path-string?))
value
default-cache-watchlist : (listof (or/c path? path-string?))
= '()

List of extra files that the cache (= render cache + compile cache, collectively) watches during a project-server session. If one of the files on the watchlist changes, the cache is invalidated (just as it would be if "pollen.rkt" changed).

If the cache can’t find a certain file on the watchlist, no error will arise. The file will simply be ignored. Therefore, to avoid unexpected behavior, the best policy is to use complete paths (or path strings). One way to generate a complete path to a local file is with define-runtime-path. Another way, if you’re using a module that’s already installed as part of a package, is with resolve-module-path:

"pollen.rkt"

(module+ setup
  (provide (all-defined-out))
  (require racket/runtime-path syntax/modresolve)
  (define-runtime-path my-local-mod "my-module.rkt")
  (define my-installed-mod (resolve-module-path 'package/my-other-module))
  (define cache-watchlist (list my-local-mod my-installed-mod)))

Added in version 1.4 of package pollen.

procedure
(setup:envvar-watchlist) → (listof string?)
value
default-envvar-watchlist : (listof string?) = '()

List of extra environment variables that are used in cache keys. Separate caches will be maintained for each distinct value of an environment variable. The POLLEN environment variable is always used, regardless of how this value is set.

Both the names and the values of environment variables are case-insensitive, so "PUB" and "pub" and "pUb" are all treated the same.

Added in version 2.1 of package pollen.

procedure
(setup:publish-directory)
→ (or/c path-string? path-for-some-system?)
value
default-publish-directory
: (or/c path-string? path-for-some-system?)
= "publish"

Default target for raco pollen publish. A complete path is used as is; a relative path is published to the desktop..

Added in version 1.1 of package pollen.

procedure
(setup:unpublished-path?) → (path? . -> . boolean?)
value
default-unpublished-path? : (path? . -> . boolean?)
= (λ (path) #f)

Changed in version 1.1 of package pollen: Deprecated. Please use setup:omitted-path?.

procedure
(setup:omitted-path?) → (path? . -> . boolean?)
value
default-omitted-path? : (path? . -> . boolean?) = (λ (path) #f)

Predicate that determines whether a path is omitted from raco pollen render and raco pollen publish operations. If the predicate evaluated to #t, then the path is omitted.

Added in version 1.1 of package pollen.

procedure
(setup:extra-published-path?) → (path? . -> . boolean?)
value
default-extra-published-path? : (path? . -> . boolean?)
= (λ (path) #f)

Changed in version 1.1 of package pollen: Deprecated. Please use setup:extra-path?.

procedure
(setup:extra-path?) → (path? . -> . boolean?)
value
default-extra-path? : (path? . -> . boolean?) = (λ (path) #f)

Predicate that determines if path is rendered & published, overriding (setup:omitted-path?) above, and Pollen’s default publish settings. For instance, Pollen automatically omits files with a .rkt extension. If you wanted to force a .rkt file to be published, you could include it here.

Added in version 1.1 of package pollen.

procedure
(setup:splicing-tag) → symbol?
value
default-splicing-tag : symbol? = '@

Key used to signal that an X-expression should be spliced into its containing X-expression.

procedure
(setup:poly-source-ext) → symbol?
value
default-poly-source-ext : symbol? = 'poly

Extension that indicates a source file can target multiple output types.

procedure
(setup:poly-targets) → (listof symbol?)
value
default-poly-targets : (listof symbol?) = '(html)

List of symbols that denotes the possible targets of a 'poly source file.

procedure
(setup:index-pages) → (listof string?)
value
default-index-pages : (listof string?) = '("index.html")

List of strings that the project server will use as directory default pages, in order of priority. Has no effect on command-line rendering operations. Also has no effect on your live web server (usually that’s a setting you need to make in an .htaccess configuration file). But with this setting, you can simulate the behavior of your live server, so that internal index-page URLs work correctly.

procedure
(setup:trim-whitespace?) → boolean?
value
default-trim-whitespace? : boolean? = #t

Predicate that controls whether the Pollen source reader trims whitespace from the beginning of a doc export. You might set this to #false if you’re using Pollen as a preprocessor for another programming language and you want to preserve leading whitespace accurately.

Added in version 1.5 of package pollen.

procedure
(setup:allow-unbound-ids?) → boolean?
value
default-allow-unbound-ids? : boolean? = #t

Predicate that controls whether Pollen converts unbound identifiers into default tags by altering the behavior of #%top in pollen/top.

Added in version 2.0 of package pollen.

procedure
(setup:here-path-key) → 'symbol
value
default-here-path-key : 'symbol = 'here-path

Key used to store the path of the source file in its metas table. No idea why you’d want to change this.

14.7.3 Parameters

I mean parameters in the Racket sense, i.e. values that can be fed to parameterize.

parameter
(current-server-port) → integer?
(current-server-port port) → void?
port : integer?
= default-project-server-port

A parameter that sets the HTTP port for the project server.

parameter
(current-project-root) → path?
(current-project-root path) → void?
path : path?

A parameter that holds the root directory of the current project (e.g., the directory where you launched raco pollen start).

parameter
(current-server-extras-path) → path?
(current-server-extras-path dir) → void?
dir : path?
= #f

A parameter that reports the path to the directory of support files for the project server.

parameter
(current-poly-target) → symbol?
(current-poly-target target) → void?
target : symbol?
= 'html

A parameter that reports the current rendering target for poly source files.

top ← prev up next →

1	Installation
2	Quick tour
3	Backstory
4	The big picture
5	First tutorial: the project server & preprocessor
6	Second tutorial: Markdown, templates, & pagetrees
7	Third tutorial: Pollen markup & tag functions
8	Fourth tutorial: multiple output targets
9	Mini tutorials
10	Using raco pollen
11	File formats
12	Pollen command syntax
13	Programming Pollen
14	Module reference
15	Unstable module reference
16	Getting more help
17	Acknowledgments
18	License & source code
19	Version notes (2.2.2469.586)
	Index

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.7.1	How to override setup values
14.7.2	Values
14.7.3	Parameters