pollen/scribblings/file.scrbl

#lang scribble/manual

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

@(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 seven 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{Markdown}, with file extension @code[(format ".~a" world:markdown-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 @filepath{default.css.pp} would become @filepath{default.css}. Scribble files work differently — the corresponding output file is the source file but with an @filepath{html} extension rather than @filepath{scrbl}. So @filepath["pollen.scrbl"] would become @filepath["pollen.html"].

@deftogether[
(@defproc[
(preproc-source?
[v any/c]) 
boolean?]

@defproc[
(markup-source?
[v any/c]) 
boolean?]

@defproc[
(markdown-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")
(markdown-source? "default.html.pmd")
(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-markdown-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-markdown-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[
(->markdown-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)
(->markdown-source-path name)
(->template-source-path name)
(->scribble-source-path name)
(->null-source-path name)
]


@deftogether[
(@defproc[
(get-preproc-source
[p pathish?]) 
(or/c #f path?)]

@defproc[
(get-markup-source
[p pathish?]) 
(or/c #f path?)]

@defproc[
(get-markdown-source
[p pathish?]) 
(or/c #f path?)]

@defproc[
(get-template-source
[p pathish?]) 
(or/c #f path?)]

@defproc[
(get-null-source
[p pathish?]) 
(or/c #f path?)]

@defproc[
(get-scribble-source
[p pathish?]) 
(or/c #f path?)]
)]
Find an existing source path of the specified type that would produce the output path @racket[_p]. If there is no source of the specified type, return @racket[#f].


@defproc[
(get-source
[p pathish?]) 
(or/c #f path?)]
Find an existing source path that would produce the output path @racket[_p]. Check source formats in this order: @racket[get-markup-source], @racket[get-markdown-source], @racket[get-preproc-source], @racket[get-null-source], and @racket[get-scribble-source]. If there is no corresponding source, return @racket[#f].



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