pollen/scribblings/file.scrbl

#lang scribble/manual

@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world pollen/file sugar/coerce/value))

@(define my-eval (make-base-eval))
@(my-eval `(require pollen pollen/file))

@section{Files}

@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[
(ptree-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")
(ptree-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")
]