txexpr/scribblings/tagged-xexpr.scrbl

#lang scribble/manual

@(require scribble/eval (for-label racket "../main.rkt" xml))

@(define my-eval (make-base-eval))
@(my-eval `(require tagged-xexpr xml))


@title{tagged-xexpr}

@author[(author+email "Matthew Butterick" "mb@mbtype.com")]

Convenience functions for working with tagged X-expressions.

@section{Installation}

At the command line:
@verbatim{raco pkg install tagged-xexpr}

After that, you can update the package from the command line:
@verbatim{raco pkg update tagged-xexpr}

@section{What’s a tagged X-expression?}

It's an X-expression with the following grammar:

@racketgrammar[
#:literals (cons list valid-char?)
tagged-xexpr (list symbol (list (list symbol string) ...) xexpr ...)
      (cons symbol (list xexpr ...))
]

A tagged X-expression has a symbol in the first position — the @italic{tag} — followed by a series of other X-expressions. Optionally, a tagged X-expression can have a list of @italic{attributes} in the second position, which are pairs of symbols and strings.

@examples[#:eval my-eval
(tagged-xexpr? '(tag "Brennan" "Dale"))
(tagged-xexpr? '(tag "Brennan" (tag2 "Richard") "Dale"))
(tagged-xexpr? '(tag [[key "value"][key2 "value"]] "Brennan" "Dale"))
(tagged-xexpr? '(tag symbols are fine))
(tagged-xexpr? '("No" "tag" "in front"))
(tagged-xexpr? '(tag [[bad attr-value]] "string")) 
(tagged-xexpr? '(tag [key "value"] "Brennan")) 
   ]
   
Be careful with the last one. Because the key–value pair is not enclosed in a @racket[list], it's interpreted as a nested @racket[_tagged-xexpr] within the first, as you may not find out until you try to read its attributes:

@margin-note{There's no way of eliminating this ambiguity, short of always requiring an attribute list — even empty — in your tagged X-expression. See also @racket[xexpr-drop-empty-attributes].}

@examples[#:eval my-eval
(tagged-xexpr-attr '(tag [key "value"] "Brennan")) 
]

Tagged X-expressions are most commonly seen in XML & HTML documents. Though the notation is different in Racket, the data structure is identical:

@examples[#:eval my-eval
(xexpr->string '(p [[foo "bar"]] "Brennan" (em "Richard") "Dale"))
(string->xexpr "<p foo=\"bar\">Brennan<em>Richard</em>Dale</p>")
   ]

After converting to and from HTML, you get back your original X-expression. Well, not quite. The brackets turned into parentheses — no big deal, since they mean the same thing in Racket. Also true that @racket[string->xexpr] added an empty attribute list after @racket[em]. This is standard procedure, and also benign.

@section{Interface}

@defmodule[tagged-xexpr]

@defproc[
(tagged-xexpr?
[v any/c])
boolean?]
Simple predicate for functions that operate on @racket[tagged-xexpr]s.


@section{License & source code}

This module is licensed under the LGPL.

Source repository at @link["http://github.com/mbutterick/tagged-xexpr"]{http://github.com/mbutterick/tagged-xexpr}. Suggestions & corrections welcome.