#lang scribble/manual
@; Copyright (c) 2019 Joel Dueck
@;
@; Copying and distribution of this file, with or without modification,
@; are permitted in any medium without royalty provided the copyright
@; notice and this notice are preserved. This file is offered as-is,
@; without any warranty.
@(require "scribble-helpers.rkt"
scribble/example)
@(require (for-label "../pollen.rkt"
"../dust.rkt"
racket/base
txexpr
sugar/coerce
pollen/tag
pollen/setup
pollen/core))
@(define dust-eval (make-base-eval))
@(dust-eval '(require "dust.rkt"))
@title{@filepath{dust.rkt}}
@defmodule["dust.rkt" #:packages ()]
This is where I put constants and helper functions that are needed pretty much everywhere in the
project. In a simpler project these would go in @filepath{pollen.rkt} but here I have other modules
sitting “behind” that one in the @tt{require} chain.
@section{Constants}
@defthing[default-authorname string? #:value "Joel Dueck"]
Used as the default author name for @code{note}s, and (possibly in the future) for articles
generally.
@defthing[series-path/ path-string? #:value "series/"]
The path of the folder that contains the Pollen documents defining Series, relative to the project’s
document root.
@section{Metas and @code{txexpr}s}
@defproc[(attr-present? [name symbol?] [attrs (listof pair?)]) boolean?]
Shortsightedly redundant to @code{attrs-have-key?}. Returns @code{#t} if @racket[_name] is one of
the attributes present in @racket[_attrs], otherwise returns @code{#f}.
@defproc[(maybe-attr [key symbol?] [attrs txexpr-attrs?] [missing-expr any/c ""]) any/c]
Find the value of @racket[_key] in the supplied list of attributes, returning the value of
@racket[_missing-expr] if it’s not there.
I had to write this because @racket[attr-ref] wants a whole tagged X-expression (not just the
attributes); also, by default it raises an exception when @racket[_key] is missing, rather than
returning an empty string.
@defproc[(maybe-meta [key symbolish?] [missing-expr any/c ""]) any/c]
Look up a value in @code{(current-metas)} that may or may not be present, returning the value of
@racket[_missing-expr] if it’s not there.
@defproc[(tx-strs [tx txexpr?]) string?]
Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and concatenates them together.
@examples[#:eval dust-eval
(tx-strs '(p [[class "intro"]]
(em "I’m not opening the safe") ", Wilson remembers thinking."))]
@defproc[(first-words [str string?] [n exact-nonnegative-integer?]) string?]
Returns a string containing the first @racket[_n] words of @racket[_str], removing any trailing
punctuation. It will trip on opening punctuation or punctuation surrounded by spaces.
@examples[#:eval dust-eval
(first-words "Another time, perhaps." 2)
(first-words "‘One problem’ – it don’t always do punctuation right." 3)]
@section{Article parsers and helpers}
@defproc[(default-title [date string?]) string?]
Titles are not required for articles, but there are contexts where you need something that
serves as a title if one is not present, and that’s what this function supplies.
@examples[#:eval dust-eval
(default-title "2018-02-19")]
@defproc[(series-pagenode) pagenode?]
If @code{(current-metas)} has the key @racket['series], converts its value to the pagenode pointing to
that series, otherwise returns @racket['||].
@defproc[(series-noun) string?]
If @code{(current-metas)} has the key @racket['series], and if the corresponding series defines a meta
value for @racket['noun-singular], then return it, otherwise return @racket[""].
@defproc[(series-title) string?]
If @code{(current-metas)} has the key @racket['series], and if the corresponding series defines a meta
value for @racket['title], then return it, otherwise return @racket[""].
@defproc[(disposition-values [str string?]) any]
Given a string @racket[_str], returns two values: the portion of the string coming before the first
space, and the rest of the string.
@examples[#:eval dust-eval
(disposition-values "* thoroughly recanted")]
@defproc[(build-note-id [tx txexpr?]) non-empty-string?]
Given a @code{note} tagged X-expression, returns an identifier string to uniquely identify that note
within an article. This identifier is used as an anchor link in the note’s HTML, and as part of the
note’s primary key in the SQLite cache database.
@examples[#:eval dust-eval
(build-note-id '(note [[date "2018-02-19"]] "This is an example note"))
(build-note-id '(note [[date "2018-03-19"] [author "Dean"]] "Different author!"))
]
@defproc[(notes->last-disposition-values [txprs (listof txexpr?)]) any]
Given a list of tagged X-expressions (ideally a list of @code{note}s), returns two values: the value
of the @racket['disposition] attribute for the last note that contains one, and the ID of that note.
@examples[#:eval dust-eval
(define notelist
(list
'(note [[date "2018-02-19"] [disposition "* problematic"]] "First note")
'(note [[date "2018-03-19"]] "Second note")
'(note [[date "2018-04-19"] [disposition "† recanted"]] "Third note")))
(notes->last-disposition-values notelist)]
@section{Date formatters}
@defproc[(ymd->english [ymd-string string?]) string?]
Converts a date-string of the form @code{"YYYY-MM-DD"} to a string of the form @code{"Monthname D,
YYYY"}.
If the day number is missing from @racket[_ymd-string], the first day of the month is assumed. If
the month number is also missing, January is asssumed. If the string cannot otherwise be parsed as
a date, an exception is raised.
If any spaces are present in @racket[_ymd-string], everything after the first space is ignored.
@defproc[(ymd->dateformat [ymd_string string?] [dateformat string?]) string?]
Converts a date-string of the form @code{"YYYY-MM-DD"} to another string with the same date
formatted according to @racket[_dateformat]. The
@ext-link["http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table"]{pattern syntax
of the date format} comes from the Unicode CLDR.
