The slowest part of a @racket[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 @code[(format "~a" world:main-pollen-export)] and @code[(format "~a" world:meta-pollen-export)] —in the cache so they can be reused.
The slowest part of a @racket[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 @code[(format "~a" world:main-export)] and @code[(format "~a" world:meta-export)] —in the cache so they can be reused.
@defparam[current-cache hash hash?]{A parameter that refers to the current cache. It is initialized with @racket[make-cache].
@ -331,7 +331,7 @@ But within a template, we need to tell Pollen how we want to convert the X-expre
Third, we need to include the content from our source file. By convention, every Pollen source file makes its output available through an exported variable named @code{doc}. A source file in preprocessor mode puts its text result in @code{doc}. And a source file in authoring mode puts its X-expression result in @code{doc}. So we put the variable @code{doc} inside the @code{body} tag.
@margin-note{You can change the name to something other than @code{doc} by changing @racket[world:main-pollen-export].}
@margin-note{You can change the name to something other than @code{doc} by changing @racket[world:main-export].}
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.
Global values that are used throughout the Pollen system.
All identifiers are exported with the prefix @racket[world:], and are so documented below.
@section{Parameters}
I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize].
@defthing[world:default-port integer?]
@defparam[world:current-server-port port integer?]{
A parameter that sets the HTTP port for the project server. Initialized to @racket[world:default-port], which defaults to 8080.}
A parameter that sets the HTTP port for the project server. Initialized to @racket[world:default-port].}
@deftogether[(
@defthing[world:main-pollen-export symbol?]
@defthing[world:meta-pollen-export symbol?]
)]
The two exports from a compiled Pollen source file. Initialized to @racket['doc] and @racket['metas], respectively.
@defparam[world:current-project-root port path?]{
A parameter that holds the root directory of the current project (e.g., the directory where you launched @code{raco pollen start}).}
@defparam[world:current-server-extras-path dir path?]{
A parameter that reports the path to the directory of support files for the project server. Initialized to @racket[#f], but set to a proper value when the server runs.}
@(defthing world:directory-require string?)
File implicitly required into every Pollen source file from its directory. Initialized to @filepath{directory-require.rkt}.
A parameter that determines whether the @racket[world:directory-require] file is checked for changes on every pass through @racket[render]. (Can be faster to turn this off if you don't need it.) Initialized to @racket[#t].}
@defthing[world:server-extras-dir string?]
Name of directory where server support files live. Initialized to @tt{server-extras}.
@defparam[world:current-server-extras-path dir path?]{
A parameter that reports the path to the directory of support files for the project server. Initialized to @racket[#f], but set to a proper value when the server runs.}
@section{Values that can be overwritten with @racket[local:]}
These values can be changed by overriding them in your @racket["directory-require.rkt"] source file. Use @racket[define] to make a variable with the same name as the one in @racket[pollen/world], but with the prefix @racket[local:] instead of @racket[world:]. Assign it whatever value you like. When Pollen runs, these definitions will supersede those in @racket[pollen/world].
For instance, suppose you wanted the main export of every Pollen source file to be called @racket[van-halen] rather than @racket[doc], the extension of Pollen markup files to be @racket[rock] rather than @racket[pm], and the command character to be @litchar{🎸} instead of @litchar{◊}. Your @racket["directory-require.rkt"] would include these defintions:
@fileblock["directory-require.rkt"
@codeblock{
#lang racket/base
(provide (all-defined-out))
(define local:main-export 'van-halen)
(define local:markup-source-ext 'rock)
(define local:command-char #\🎸)
}]
Though any of the values below can be overridden, it may not always be wise to do so. For instance, if you redefined @racket[world:fallback-template-prefix], you would simply break the fallback-template mechanism, because it would look for files that don't exist. But we don't live in a nanny state, so you are entrusted to say what you mean and accept the consequences.
Of course, you can restore the defaults simply by deleting these defined values from @racket["directory-require.rkt"].
These overridable values also come with a corresponding @racket[get-] function that will return the @racket[local:] value if it exists, otherwise the @racket[world:] value. In the example above, @racket[world:command-char] would be @litchar{◊} no matter what, but @racket[world:get-command-char] would return @litchar{🎸}.
@defoverridable[default-port integer?]{
Determines the default HTTP port for the project server. Initialized to @racket[8080].}
@defoverridable[main-export symbol?]{The main X-expression exported from a compiled Pollen source file. Initialized to @racket[doc].}
@defoverridable[meta-export symbol?]{The meta hashtable exported from a compiled Pollen source file. Initialized to @racket[metas].}
@defoverridable[world:meta-tag-name symbol?]{Name of the tag used to mark metas within Pollen source.}
@defoverridable[world:directory-require string?]{File implicitly required into every Pollen source file from its directory. Initialized to @filepath{directory-require.rkt}.}
@defoverridable[world:server-extras-dir string?]{Name of directory where server support files live. Initialized to @tt{server-extras}.}
@deftogether[(
@defthing[world:preproc-source-ext symbol?]
@defthing[world:markup-source-ext symbol?]
@defthing[world:markdown-source-ext symbol?]
@defthing[world:null-source-ext symbol?]
@defthing[world:pagetree-source-ext symbol?]
@defthing[world:template-source-ext symbol?]
@defthing[world:scribble-source-ext symbol?]
@defoverridable[preproc-source-ext symbol?]
@defoverridable[markup-source-ext symbol?]
@defoverridable[markdown-source-ext symbol?]
@defoverridable[null-source-ext symbol?]
@defoverridable[pagetree-source-ext symbol?]
@defoverridable[template-source-ext symbol?]
@defoverridable[scribble-source-ext symbol?]
)]
File extensions for Pollen source files, initialized to the following values:
@ -58,53 +91,32 @@ File extensions for Pollen source files, initialized to the following values:
@defoverridable[pagetree-root-node symbol?]{Name of the root node in a decoded pagetree. It's ignored by the code, so its only role is to clue you in that you're looking at something that came out of the pagetree decoder. Initialized to @code{'pagetree-root}.}
@defthing[world:default-pagetree string?]
Pagetree that Pollen dashboard loads by default in each directory. Initialized to @filepath{index.ptree}.
@defthing[world:pagetree-root-node symbol?]
Name of the root node in a decoded pagetree. It's ignored by the code, so its only role is to clue you in that you're looking at something that came out of the pagetree decoder. Initialized to @code{'pagetree-root}.
@defoverridable[command-char char?]{The magic character that indicates a Pollen command, function, or variable. Initialized to @racket[#\◊].}
@defoverridable[default-template-prefix string?]{Prefix of the default template. Initialized to @code{"template"}.}
@defthing[world:command-marker char?]
The magic character that indicates a Pollen command, function, or variable. Initialized to @racket[#\◊].
@defthing[world:default-template-prefix string?]
Prefix of the default template. Initialized to @code{"template"}.
@defoverridable[fallback-template-prefix string?]{Used to generate the name of the fallback template (i.e., the template used to render a Pollen markup file when no other template can be found). Prefix is combined with the output suffix of the source file. Initialized to @code{"fallback"}.}
@defthing[world:fallback-template-prefix string?]
Used to generate the name of the fallback template (i.e., the template used to render a Pollen markup file when no other template can be found). Prefix is combined with the output suffix of the source file. Initialized to @code{"fallback"}.
@defthing[world:template-meta-key symbol?]
Meta key used to store a template name for that particular source file. Initialized to @racket['template].
@defoverridable[template-meta-key symbol?]{Meta key used to store a template name for that particular source file. Initialized to @racket['template].}
