pollen/scribblings/file.scrbl

184 lines
4.0 KiB
Plaintext

#lang scribble/manual
@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world sugar))
@(define my-eval (make-base-eval))
@(my-eval `(require pollen pollen/file))
@title[#:tag "file-types"]{File}
@defmodule[pollen/file]
A utility module that provides functions for working with Pollen source and output files. The tests rely on file extensions specified in @racket[pollen/world].
Pollen handles six kinds of source files:
@bold{Preprocessor}, with file extension @code[(format ".~a" world:preproc-source-ext)].
@bold{Markup}, with file extension @code[(format ".~a" world:markup-source-ext)].
@bold{Template}, with file extension @code[(format ".~a" world:template-source-ext)].
@bold{Null}, with file extension @code[(format ".~a" world:null-source-ext)].
@bold{Scribble}, with file extension @code[(format ".~a" world:scribble-source-ext)].
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 @code["default.css.pp"] would become @code["default.css"]. Scribble files work differently — the corresponding output file is the source file but with an @racket[html] extension rather than @racket[scrbl]. So @code["pollen.scrbl"] would become @code["pollen.html"].
@deftogether[
(@defproc[
(preproc-source?
[v any/c])
boolean?]
@defproc[
(markup-source?
[v any/c])
boolean?]
@defproc[
(template-source?
[v any/c])
boolean?]
@defproc[
(null-source?
[v any/c])
boolean?]
@defproc[
(scribble-source?
[v any/c])
boolean?]
@defproc[
(pagetree-source?
[v any/c])
boolean?]
)]
Test whether @racket[_v] is a path representing a source file of the specified type, based on file extension.
@examples[#:eval my-eval
(preproc-source? "main.css.pp")
(markup-source? "default.html.pm")
(template-source? "main.html.pt")
(null-source? "index.html.p")
(scribble-source? "file.scrbl")
(pagetree-source? "index.ptree")
]
@deftogether[
(@defproc[
(has-preproc-source?
[v any/c])
boolean?]
@defproc[
(has-markup-source?
[v any/c])
boolean?]
@defproc[
(has-template-source?
[v any/c])
boolean?]
@defproc[
(has-null-source?
[v any/c])
boolean?]
@defproc[
(has-scribble-source?
[v any/c])
boolean?]
)]
Test whether @racket[_v] is the output path for an existing source file of the specified type.
@deftogether[
(@defproc[
(has/is-preproc-source?
[v any/c])
boolean?]
@defproc[
(has/is-markup-source?
[v any/c])
boolean?]
@defproc[
(has/is-template-source?
[v any/c])
boolean?]
@defproc[
(has/is-null-source?
[v any/c])
boolean?]
@defproc[
(has/is-scribble-source?
[v any/c])
boolean?]
)]
Test whether @racket[_v] is a path representing a source file of the specified type, or is the output path for an existing source file of the specified type. In other words, @racket[has/is-preproc-source?] is equivalent to @racket[(or (preproc-source? v) (has-preproc-source? v))].
@deftogether[
(@defproc[
(->preproc-source-path
[p pathish?])
path?]
@defproc[
(->markup-source-path
[p pathish?])
path?]
@defproc[
(->template-source-path
[p pathish?])
path?]
@defproc[
(->null-source-path
[p pathish?])
path?]
@defproc[
(->scribble-source-path
[p pathish?])
path?]
)]
Convert an output path @racket[_p] into the source path of the specified type that would produce this output path. This function simply generates a path for a file — it does not ask whether the file exists.
@examples[#:eval my-eval
(define name "default.html")
(->preproc-source-path name)
(->markup-source-path name)
(->template-source-path name)
(->scribble-source-path name)
(->null-source-path name)
]
@defproc[
(->output-path
[p pathish?])
path?]
Convert a source path @racket[_p] into its corresponding output path. This function simply generates a path for a file — it does not ask whether the file exists.
@examples[#:eval my-eval
(->output-path "main.css.pp")
(->output-path "default.html.pm")
(->output-path "index.html.p")
(->output-path "file.scrbl")
]