html.tem

(page "HTML operations"
(import "docs/html0.html")
(newtable "Generating HTML"
(def br "[n]" "Prints <code>n</code> break tags." (htmltests (br)))
(def br2 "" "Prints two break tags." (htmltests (br2)))
(mac center "[body ...]" "Prints <code>body</code> in a <code>center</code> tag." (htmltests (show center (pr "hello"))))
(mac underline "[body ...]" "Prints <code>body</code> in an underline tag." (htmltests (show underline (pr "hello ") (pr "world"))))
(mac prbold "[arg ...]" "Prints a bold (<code>b</code>) tag around <code>arg</code>." (htmltests (show prbold "hello")))
(def para "[arg ...]" "Prints a paragraph (<code>p</code>) tag followed by the args." (htmltests (show para "hello " "world")))

(mac whitepage "[body ...]" "Creates a white page containing the body." (htmltests (whitepage (prn "hello"))))
(def errpage "[arg ...]" "Prints a white page containing the args." (htmltests (errpage "hello " "world")))
(mac new-hspace "n" "Prints a horizonal spacer using <code>span</code>." (htmltests (new-hspace 3)))
(def blank-url "" "Returns path to a blank spacer GIF (<code>s.gif</code>)." (tests (blank-url)))
(def hspace "w" "Prints a horizontal spacer image of width <code>w</code>." (htmltests (hspace 3)))
(def vspace "h" "Prints a vertical spacer image of height <code>h</code>." (htmltests (vspace 3)))
(def vhspace "h w" "Prints a spacer image of height <code>h</code> and width <code>w</code>." (htmltests (vhspace 3 5)))
(def nbsp "" "Prints a non-breaking space." (htmltests (nbsp)))
(def link "text [href [color]]" "Prints an HTML link." (htmltests (show link "click here" "http://arcfn.com" orange)))
(def underlink "text [dest]" "Prints an HTML link with explicitly underlined text." (htmltests (show underlink "click here" "http://arcfn.com")))
(def shortlink "url" "Prints a link to <code>url</code> with <code>http://</code> removed from the text." (htmltests (show shortlink "http://arcfn.com")))
(def parafy "str" "Returns <code>str</code> with paragraph tags.  A <code>p</code> tag is inserted after each blank line." (tests (parafy "hello\n\nworld\npeople")))
(mac spanclass "classname [body ...]" "Prints <code>body</code> in a <code>span</code> tag." (htmltests (spanclass myclass (pr "hello ") (pr "world"))))
(def pagemessage "text" "Prints <code>text</code> followed by two breaks, if it is not <code>nil</code>." (htmltests (pagemessage "hello") (pagemessage nil)))
)
(newtable "Table operations"
(mac tab "[body ...]" "Prints <code>body</code> in a <code>table</code> tag." (htmltests (tab (pr "hello"))))
(mac sptab "[body ...]" "Prints <code>body</code> in a table tag with 0 border, 0 cellpadding, and 7 cellspacing." (htmltests (show sptab (prrow "foo" 1))))
(mac widtable "w [body ...]" "Prints a single-cell table containing <code>body</code>.  The table has width <code>w</code>." (htmltests (show widtable "30%" (pr "hello"))))
(mac zerotable "[body ...]" "Prints <code>body</code> in a table tag with 0 border, cellpadding, and cellspacing." (htmltests (show zerotable (pr "hello"))))
(mac tr "[body ...]" "Prints <code>body</code> in a <code>tr</code> tag." (htmltests (prn "hello")))
(mac row "[arg ...]" "Prints a table row.  Prints a <code>td</code> tag around each <code>arg</code>, and a <code>tr</code> tag around the whole output." (htmltests (row 1 "a" 'b)))
(mac prrow "[arg ...]" "Prints a <code>td</code> tag around each <code>arg</code>, and a <code>tr</code> tag around the whole output.  Each <code>arg</code> that is a number is right-justified." (htmltests (prrow 1 "a" 'b)))
(def spacerow "h" "Prints a spacer table row of height <code>h</code>." (htmltests (spacerow 10)))
(mac spanrow "colspan [body ...]" "Prints <code>body</code> in a <code>tr</code> and <code>td</code> tag with the given <code>colspan</code>." (htmltests (spanrow 3 (pr "hello"))))
(mac trtd "[body ...]" "Prints <code>body</code> in <code>tr</code> and <code>td</code> tags. <code>body</code> can be atoms."
(htmltests (trtd (prn "hello")) (trtd "hello " "world")))
(mac td "[body ...]" "Prints <code>body</code> in a <code>td</code> tag. <code>body</code> can be atoms." (htmltests (td (prn "hello")) (td "hello " "world")))
(mac tdr "[body ...]" "Prints <code>body</code> in a <code>td</code> tag with alignment set to the right. <code>body</code> can be atoms.  Renamed from tdright in arc3."
(htmltests (tdr (prn "hello")) (tdright "world")))
(mac tdcolor "color [body ...]" "Prints <code>body</code> in a <code>td</code> tag with the specified <code>bgcolor</code>. <code>body</code> can be atoms."
(htmltests (tdcolor orange (prn 1)) (tdcolor orange 1 "world")))
(def cellpr "content" "Prints content or &amp;nbsp; if the content is <code>nil</code>" (htmltests (cellpr 42) (cellpr nil)))
)
(newtable "Forms"
(mac form "action [body ...]" "Prints <code>body</code> in a <code>form</code> tag." (htmltests (form "http://arcfn.com" (pr "hello"))))
(def submit "[value]" "Prints a <code>submit</code> tag." (htmltests (show submit "hello")))
(def but "[value [name]]" "Prints a <code>submit</code> button tag." (htmltests (show but "foo" "bar")))
(def buts "name [text ...]" "Prints multiple <code>submit</code> button tags, one for each <code>text</code>." (htmltests (show buts "foo" "bar" "baz")))
(mac textarea "name rows cols [body ...]" "Prints <code>body</code> in a <code>textarea</code> tag." (htmltests (show textarea "foo" 1 40 (pr "Contents"))))
(def menu "name itemlist [sel]" "Prints a menu with <code>select</code> and </code>option</code>.  Each element of <code>itemlist</code> becomes an option.  If <code>sel</code> is an item in <code>itemlist</code>, that item is marked as selected." (htmltests (show menu "foo" '(item1 item2 item3) 'item2)))
(def input "name [val [size ]]" "Prints an <code>input</code> tag." (htmltests (show input "foo" "bar" 10)))
(mac inputs "[name label size value ...]" "Prints a table of labelled text rows.  If <code>size</code> is an atom, a text input of the specified size is generated.  If <code>size</code> is a list <code>(rows cols)</code>, then a textarea of the specified size is generated.  If the label is <code>password</code> a password input is generated. The label is followed by a colon." (htmltests (show "(inputs i1 \"Foo\" 10 \"contents\"
  p1 password 10 \"pw\"
  i2 \"Bar\" '(2 5) \"stuff\")")))
(def single-input "label name size buttontext [password]" "Prints a text or password input prefixed with <code>label</code> followed by a submit button." (htmltests (show single-input "Secret" 'i1 5 "Submit" 'password)))
)
(newtable "Other operations"
(mac attribute "tag attribute f" "Defines that <code>tag</code> can have <code>attribute</code>.  <code>f</code> is on of the <code>op...</code> functions, defining the type of <code>attribute</code>." (tests (attribute a class opsym)))
(def color "r g b" "Creates a color object with the specified red, green, and blue components (0 to 255)" (tests (color 255 0 128)))
(def hex>color "str" "Converts a string of length 6 representing a <a href='http://en.wikipedia.org/wiki/Web_colors#Hex_triplet'>hex triplet</a> into a color object. Returns <code>nil</code> on failure." (tests (hex>color "ff00cc")))
(def gray "n" "Creates a color object representing a gray level. <code>n</code> is between 0 and 255." (tests (gray 100)))
(variable white "" "Color object representing white." (tests white))
(variable black "" "Color object representing black." (tests black))
(variable linkblue "" "Color object representing blue." (tests linkblue))
(variable orange "" "Color object representing orange." (tests orange))
(variable darkred "" "Color object representing dark red.  New in arc3." (tests darkred))
(variable darkblue "" "Color object representing dark blue.  New in arc3." (tests darkblue))
(def hexrep "color" "Converts a color object to a hex triplet string." (tests (hexrep orange)))
(def dehex "str" "Converts <code>str</code> from hex to integer. Returns <code>nil</code> if the conversion fails." (tests (dehex "40") (dehex "0x12")))
(mac gentag "tag [attribute value ...]" "Prints the tag." (htmltests (gentag img src "foo.gif")))
(mac tag "spec [body ...]" "Prints <code>body</code> surrounded by the tag specified by <code>spec</code>." (htmltests (show gentag a href "/index.html") (pr "click")))
(mac tag-if "test spec [body ...]" "If <code>test</code> is true, <code>body</code> is wrapped in the tag <code>spec</code>.  Otherwise, <code>body</code> is printed without the tag." (htmltests (tag-if t (underline) (pr "hi")) (tag-if nil (underline) (pr "hi"))))
(def pr-escaped "str" "Prints <code>str</code> with <, >, \", and & HTML-escaped." (htmltests (pr-escaped "abc< > \" \' &" )))
(def eschtml "str" "Returns a string that is <code>str</code> with <, >, \", \', and & HTML-escaped." (tests (eschtml "abc< > \" \' &")))
(def esc<>& "str" "Returns a string that is <code>str</code> with <, >, and & HTML-escaped." (tests (esc<>& "abc< > \" \' &")))
(mac cdata "[body ...]" "Prints <code>body</code> in a CDATA section." (htmltests (cdata (pr "hello"))))
(def striptags "str" "Returns <code>str</code> without tags.  Anything between angle brackets is removed." (tests (striptags "abc<foo>def</foo>ghi")))
)

(newtable "Internals"
(text "The implementation of HTML handling in Arc centers around the <code>opmeths*</code> table, which maps from a tag and attribute to one of the <code>op...</code> functions.  These functions generate the code that generates the HTML to set an attribute.
<p>  One Arc design pattern used in the HTML code is to use multiple functions to generate the code, and then use these functions inside macros.  This provides a simulation of first-class macros.")
(def opcolor "attribute color" "Generates code to assign a color object to an attribute." (tests (opcolor 'bgcolor orange)))
(def opstring "attribute string" "Generates code to assign a string to an attribute, if the string is not <code>nil</code>." (tests (opstring 'class "foo")))
(def opnum "attribute num" "Generates code to assign a number to an attribute, if <code>num</code> is not <code>nil</code>." (tests (opnum 'width 42)))
(def opsym "attribute val" "Generates code to assign a value to an attribute." (tests (opsym 'width 42)))
(def opesc "attribute val" "Generates code to assign a quoted value to an attribute. If <code>val</code> is a string, it is escaped with <code>pr-escaped</code>." (tests (opesc 'foo 'val)))
(def opsel "attribute val" "Generates code to set <code>attribute</code> to <code>selected</code> if <code>val</code> is true." (tests (opsel 'foo 'bar)))
(def start-tag "spec" "Generates code to start a tag." (tests (start-tag '(a href foo))))
(def end-tag "spec" "Generates code to end a tag." (tests (end-tag '(a href foo))))
(def tag-options "tag options" "Generates code to assign values to attributes.  <code>options</code> is a list of attribute/value pairs.  The allowable attributes are defined by <code>opmeth</code>, and <code>style</code> is allowed for all tags." (tests (tag-options 'td '((bgcolor red) (width 42)))
))
(var opmeths* "" "Table indexed by list of tag and attribute." (tests (opmeths* '(a href))))
(mac opmeth "tag attr" "Looks up the HTML tag and attribute in <code>opmeths*</code>" (tests (opmeth 'a 'href)))
(variable hexreps "" "Table mapping integers to hex strings of length 2 on the range 0 to 255." (tests (hexreps 14) (hexreps 250)))
(predicate literal "x" "Tests if x is a literal.  New in arc3." (tests (literal 'a) (literal 4)))
(clean-url "url" "Removes bad characters from url.  New in arc3." (tests (clean-url "http://arcfn.'\"<>com")))
(predicate valid-url "url" "Minimal validation of a URL.  New in arc3." (tests (valid-url "http://foobar") (valid-url "junk")))
(fontcolor "c body" "Wraps body in a font tag.  New in arc3."  (tests (fontcolor white (pr "hi"))))


)
)