diff options
author | Andy Wingo <wingo@pobox.com> | 2013-01-30 15:29:18 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2013-01-30 15:29:18 +0100 |
commit | e10c250928bc6c4116d6344616d39f3c52edc36b (patch) | |
tree | dffa1373ad37416ead9549da2f971185608eec73 /doc/ref/sxml.texi | |
parent | 1260fd0b2c4ce1d0d7e7b17df924c245f67f9058 (diff) | |
download | guile-e10c250928bc6c4116d6344616d39f3c52edc36b.tar.gz |
add #:doctype-handler to xml->sxml
* module/sxml/simple.scm (read-internal-doctype-as-string): New helper.
(xml->sxml): Add #:doctype-handler argument.
* doc/ref/sxml.texi (Reading and Writing XML): Document
#:doctype-handler. Fix some other examples, and fix the default value
of #:declare-namespaces?.
* test-suite/tests/sxml.simple.test: Add all tests from the manual
here.
Diffstat (limited to 'doc/ref/sxml.texi')
-rw-r--r-- | doc/ref/sxml.texi | 52 |
1 files changed, 43 insertions, 9 deletions
diff --git a/doc/ref/sxml.texi b/doc/ref/sxml.texi index 66584bf89..6dc261f31 100644 --- a/doc/ref/sxml.texi +++ b/doc/ref/sxml.texi @@ -57,7 +57,8 @@ to text. @deffn {Scheme Procedure} xml->sxml [string-or-port] [#:namespaces='()] @ [#:declare-namespaces?=#t] [#:trim-whitespace?=#f] @ - [#:entities='()] [#:default-entity-handler=#f] + [#:entities='()] [#:default-entity-handler=#f] @ + [#:doctype-handler=#f] Use SSAX to parse an XML document into SXML. Takes one optional argument, @var{string-or-port}, which defaults to the current input port. Returns the resulting SXML document. If @var{string-or-port} is @@ -99,18 +100,19 @@ for certain namespaces with the @code{#:namespaces} keyword argument to @result{} (*TOP* (foo (ns2:baz))) @end example -Passing a true @code{#:declare-namespaces?} argument will cause the -user-given @code{#:namespaces} to be treated as if they were declared on -the root element. +By default, namespaces passed to @code{xml->sxml} are treated as if they +were declared on the root element. Passing a false +@code{#:declare-namespaces?} argument will disable this behavior, +requiring in-document declarations of namespaces before use.. @example (xml->sxml "<foo><ns2:baz/></foo>" #:namespaces '((ns2 . "http://example.org/ns2"))) -@result{} error: undeclared namespace: `bar' +@result{} (*TOP* (foo (ns2:baz))) (xml->sxml "<foo><ns2:baz/></foo>" #:namespaces '((ns2 . "http://example.org/ns2")) - #:declare-namespaces? #t) -@result{} (*TOP* (foo (ns2:baz))) + #:declare-namespaces? #f) +@result{} error: undeclared namespace: `bar' @end example By default, all whitespace in XML is significant. Passing the @@ -120,10 +122,10 @@ whitespace in front, behind and between elements, treating it as @example (xml->sxml "<foo>\n<bar> Alfie the parrot! </bar>\n</foo>") -@result{} (*TOP* (foo "\n" (bar " Alfie the parrot! ") "\n") +@result{} (*TOP* (foo "\n" (bar " Alfie the parrot! ") "\n")) (xml->sxml "<foo>\n<bar> Alfie the parrot! </bar>\n</foo>" #:trim-whitespace? #t) -@result{} (*TOP* (foo (bar " Alfie the parrot! ")) +@result{} (*TOP* (foo (bar " Alfie the parrot! "))) @end example Parsed entities may be declared with the @code{#:entities} keyword @@ -159,6 +161,38 @@ numeric character entities. @result{} (*TOP* (foo "\xa0 foo")) @end example +By default, @code{xml->sxml} skips over the @code{<!DOCTYPE>} +declaration, if any. This behavior can be overridden with the +@code{#:doctype-handler} argument, which should be a procedure of three +arguments: the @dfn{docname} (a symbol), @dfn{systemid} (a string), and +the internal doctype subset (as a string or @code{#f} if not present). + +The handler should return keyword arguments as multiple values, as if it +were calling its continuation with keyword arguments. The continuation +accepts the @code{#:entities} and @code{#:namespaces} keyword arguments, +in the same format that @code{xml->sxml} itself takes. These entities +and namespaces will be prepended to those given to the @code{xml->sxml} +invocation. + +@example +(define (handle-foo docname systemid internal-subset) + (case docname + ((foo) + (values #:entities '((greets . "<i>Hello, world!</i>")))) + (else + (values)))) + +(xml->sxml "<!DOCTYPE foo><p>&greets;</p>" + #:doctype-handler handle-foo) +@result{} (*TOP* (p (i "Hello, world!"))) +@end example + +If the document has no doctype declaration, the @var{doctype-handler} is +invoked with @code{#f} for the three arguments. + +In the future, the continuation may accept other keyword arguments, for +example to validate the parsed SXML against the doctype. + @deffn {Scheme Procedure} sxml->xml tree [port] Serialize the SXML tree @var{tree} as XML. The output will be written to the current output port, unless the optional argument @var{port} is |