diff --git a/scribblings/cache.scrbl b/scribblings/cache.scrbl index 48b6166..b1bf4ad 100644 --- a/scribblings/cache.scrbl +++ b/scribblings/cache.scrbl @@ -19,7 +19,7 @@ The slowest part of a @racket[render] is parsing and decoding the source file. O (or/c txexpr? hash? integer?)] Similar to @racket[(dynamic-require _source-path _key)], except that it first tries to retrieve the requested value out of the cache. If it's not there, or out of date, @racket[dynamic-require] is used to update the value. -The only keys supported are @racket['doc] and @racket['metas]. +The only keys supported are @racket[doc] and @racket[metas] (or more precisely, the values of @racket[world:current-main-export] and @racket[world:current-meta-export], which default to @racket[doc] and @racket[metas]). If you want the speed benefit of the cache, you should @bold{always} use @racket[cached-require] to get data from Pollen source files. That doesn't mean you can't still use functions like @racket[require], @racket[local-require], and @racket[dynamic-require]. They'll just be slower. diff --git a/scribblings/command.scrbl b/scribblings/command.scrbl index dac1497..eb7f758 100644 --- a/scribblings/command.scrbl +++ b/scribblings/command.scrbl @@ -593,6 +593,58 @@ In this case, though there are two metas named @racket[dog] (and they use differ The @racket[metas] submodule is useful because it gives you access to the @racket[metas] hashtable @italic{without} compiling the rest of the file. So if you need to collect metas from a set of source files — for instance, page titles (for a table of contents) or categories — getting the metas through the submodule is likely to be faster. +@;-------------------------------------------------------------------- +@subsubsection{Retrieving metas} + +The @racket[metas] hashtable is available immediately within the body of your source file. You can use @racket[hash-ref] to get values out of @racket[metas]. + +@codeblock{ +#lang pollen +◊(define-meta dog "Roxy") +◊(hash-ref metas 'dog) +} + +@terminal{ +Roxy +} + + +Because the metas are collected first, you can actually invoke a meta before you define it: + +@codeblock{ +#lang pollen +◊(hash-ref metas 'dog) +◊(define-meta dog "Roxy") +◊(define-meta dog "Spooky") +} + +@terminal{ +Spooky +} + +This can be useful for setting up fields that you want to include in @racket[metas] but also have visible in the body of a document, like a title. + +@codeblock{ +#lang pollen/markup +◊(define-meta title "The Amazing Truth") +◊h1{◊(hash-ref metas 'title)} +} + +The result of this file will be: + +@terminal{ +'(root (h1 "The Amazing Truth")) +} + +And the metas: +@terminal{ +> metas +'#hash((title . "The Amazing Truth") (here-path . "unsaved-editor")) +} +You cannot, however, use @racket[hash-set!] or other similar functions, because @racket[metas] is an immutable hash. + + + @;-------------------------------------------------------------------- @subsubsection{Inserting a comment} diff --git a/scribblings/formats.scrbl b/scribblings/formats.scrbl index 1432662..ea98b66 100644 --- a/scribblings/formats.scrbl +++ b/scribblings/formats.scrbl @@ -40,9 +40,13 @@ There are no undefined commands in Pollen. If a command has not already been def By default, every Pollen source file exports two identifiers, which you can access by using the source file with @racket[require]: -@racket[doc] contains the output of the file. The type of output depends on the source format (documented below). +The main export, @racket[doc], contains the output of the file. The type of output depends on the source format (documented below). -@racket[metas] is a hash of key–value pairs with extra information that is extracted from the source. These @racket[metas] will always contain the key @racket['here-path], which returns a string representation of the full path to the source file. Beyond that, the only @racket[metas] are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas). +The second export, @racket[metas], is a hashtable of key–value pairs with extra information that is extracted from the source. These @racket[metas] will always contain the key @racket['here-path], which returns a string representation of the full path to the source file. Beyond that, the only @racket[metas] are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas). + +Pollen source files also make the @racket[metas] hashtable available through a submodule, also called @racket[metas]. So rather than importing a source file with @racket[(require "source.html.pm")], you would @racket[(require (submod "source.html.pm" metas))]. Accessing the metas this way avoids fully compiling the source file, and thus will usually be faster. + +The names @racket[doc] and @racket[metas] can be changed for a project by overriding @racket[world:main-export] and @racket[world:meta-export]. @margin-note{The Pollen rendering system relies on these two identifiers, but otherwise doesn't care how they're generated. Meaning, the code inside your Pollen source file could be @tt{#lang racket} or @tt{#lang whatever}. As long as you manually @racket[provide] those two identifiers and follow the usual file-naming convention, your source file will be usable.} diff --git a/scribblings/render.scrbl b/scribblings/render.scrbl index 8bc596f..ce393d5 100644 --- a/scribblings/render.scrbl +++ b/scribblings/render.scrbl @@ -77,7 +77,7 @@ Note that @racket[_pagetree] or @racket[_pagetree_source] is used strictly as a Find a template file for @racket[_source-path], with the following priority: @itemlist[#:style 'ordered -@item{If the metas for @racket[_source-path] have a key for @code[(format "~a" world:template-meta-key)], then use the value of this key.} +@item{If the @racket[metas] for @racket[_source-path] have a key for @code[(format "~a" world:template-meta-key)], then use the value of this key.} @item{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 @code[(format "~a.[output extension]" world:default-template-prefix)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the output path would be @code["intro.html"], so the default template would be @code[(format "~a.html" world:default-template-prefix)].}