source: project/wiki/hart @ 8592

Last change on this file since 8592 was 8592, checked in by graham, 12 years ago

updated hart docs

File size: 3.5 KB
Line 
1
2[[tags:eggs]]
3[[toc:]]
4
5== Introduction
6
7The {{hart}} egg provides an SXML-inspired syntax for HTML generation.
8
9== Authors
10
11[[Graham Fawcett]]
12
13== Requirements
14
15* [[http://www.call-with-current-continuation.org/eggs/vector-lib.html|vector-lib]]
16
17== Examples
18
19<enscript highlight=scheme>
20(use hart)
21(define people '((Fred fred@example.net 25) (Mary mary@example.net 33)))
22(hart (html (head (title "People"))
23            (body (h1 (fmt: "A list of ~a people" (length people)))
24                  (if: (null? people)
25                       (h2 "No people!")
26                       (ol (for: ((name email age) people)
27                             (li (a (@ (href (conc "mailto:" email)))
28                                    (text: name))
29                                 (fmt: ", who is ~a years old." age))))))))
30</enscript>
31
32which produces
33
34<enscript highlight=html>
35<html><head><title>People</title></head><body>
36<h1>A list of 2 people</h1>
37<ol><li><a href="mailto:fred@example.net">Fred</a>, who is 25 years old.</li>
38<li><a href="mailto:mary@example.net">Mary</a>, who is 33 years old.</li>
39</ol></body></html>
40</enscript>
41
42
43== Syntax
44
45 [syntax] (hart hart-expr ...)
46 [syntax] (hart->string hart-expr ...)
47
48Compiles hart-expr, an expression in the Hart syntax. In short, Hart is SXML syntax plus a set of "keyword expressions" which handle flow-control, iteration, escaping, etc.
49
50(hart) outputs to (current-output-port) and returns an undefined value. (hart->string) returns a string value.
51
52Multiple expressions can be passed to (hart) and (hart->string): there is an implicit (let: () ...) enclosing the expressions (see let: below).
53
54=== Keyword expressions
55
56 [syntax] (if: expr hart-true hart-false)
57 [syntax] (when: expr hart-true*)
58 [syntax] (unless: expr hart-false*)
59
60These are like their Scheme counterparts, except hart-true and hart-false are expressions in Hart syntax.
61
62 [syntax] (for: (iter-expr list-or-vec) . hart-body)
63
64A looping construct. The iter-expr is a match-expression which is matched to each successive value in list-or-vec. Hart-body is a list of Hart expressions, evaluated for each value of iter-expr.
65
66 [syntax] (let: let-forms . hart-body)
67 [syntax] (let*: let-forms . hart-body)
68 [syntax] (letrec: let-forms . hart-body)
69
70Like a (let ...) expression, but hart-body is a list of Hart expressions.
71
72=== Formatting keywords
73
74 [syntax] (raw: . expr)
75
76The Scheme expressions (not Hart!) are evaluated to strings and outputted, without HTML/XML escaping.
77
78 [syntax] (text: . exprs) or (t: . exprs)
79
80The Scheme expressions are evaluated to strings, HTML-escaped, and outputted.
81
82 [syntax] (fmt: format-string . args)
83
84The result of (apply format format-string args) is HTML-escaped and outputted.
85
86 [syntax] (scheme: . exprs)
87
88The Scheme expressions are evaluated. If they produce output, that output will be inserted into the HTML.
89
90== Attributes
91
92Note that attributes (such as the "href" in an A tag) are of the form (name value), where "name" is a string or symbol, and "value" is a Scheme expression (literal or otherwise). No escaping is done on these expressions at the current time.
93=== Optional Attributes
94
95An attribute whose value evaluates to #f will be omitted from the HTML output. This provides a mechanism for specifying optional attributes.
96
97== Utility functions
98
99 [procedure] (hart-html-escape string)
100
101A fast, basic HTML-escaping routine.
102
103== History
104
105Version 1.2 (2008-02-20): bugfix in hart.setup; added -O1 optimization
106Version 1.1.2 (February 2008): bugfix releae
107
108== License
109
110{{hart}} is licensed under the BSD License. Copyright (C) 2008 Graham Fawcett <graham.fawcett@gmail.com>
Note: See TracBrowser for help on using the repository browser.