basis/xml/errors/errors-docs.factor

   1 ! Copyright (C) 2005, 2009 Daniel Ehrenberg
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax ;
   4 IN: xml.errors
   5
   6 <PRIVATE
   7
   8 : $xml-error ( element -- )
   9     "Bad XML document for the error" $heading $code ;
  10
  11 PRIVATE>
  12
  13 HELP: multitags
  14 { $class-description "XML parsing error describing the case where there is more than one main tag in a document." }
  15 { $xml-error "<a/>\n<b/>" } ;
  16
  17 HELP: notags
  18 { $class-description "XML parsing error describing the case where an XML document contains no main tag, or any tags at all" }
  19 { $xml-error "<?xml version='1.0'?>" } ;
  20
  21 HELP: extra-attrs
  22 { $class-description "XML parsing error describing the case where the XML prolog (" { $snippet "<?xml ...?>" } ") contains attributes other than the three allowed ones, " { $snippet "standalone" } ", " { $snippet "version" } " and " { $snippet "encoding" } ". Contains one slot, " { $snippet "attrs" } ", which is a hashtable of all the extra attributes' names." }
  23 { $xml-error "<?xml version='1.0' reason='because I said so'?>\n<foo/>" } ;
  24
  25 HELP: nonexist-ns
  26 { $class-description "XML parsing error describing the case where a namespace doesn't exist but it is used in a tag. Contains one slot, " { $snippet "name" } ", which contains the name of the undeclared namespace." }
  27 { $xml-error "<a:b>c</a:b>" } ;
  28
  29 HELP: not-yes/no
  30 { $class-description "XML parsing error used to describe the case where standalone is set in the XML prolog to something other than " { $snippet "yes" } " or " { $snippet "no" } ". This contains one slot, text, which contains offending value." }
  31 { $xml-error "<?xml version='1.0' standalone='maybe'?>\n<x/>" } ;
  32
  33 HELP: unclosed
  34 { $class-description "XML parsing error used to describe the case where the XML document contains classes which are not closed by the end of the document. Contains one slot, " { $snippet "tags" } ", a sequence of names." }
  35 { $xml-error "<x>some text" } ;
  36
  37 HELP: mismatched
  38 { $class-description "XML parsing error describing mismatched tags. Contains two slots: " { $snippet "open" } " is the name of the opening tag and " { $snippet "close" } " is the name of the closing tag. This shows the location of the closing tag" }
  39 { $xml-error "<a></c>" } ;
  40
  41 HELP: expected
  42 { $class-description "XML parsing error describing when an expected token was not present. Contains two slots, " { $snippet "should-be" } ", which has the expected string, and " { $snippet "was" } ", which has the actual string." } ;
  43
  44 HELP: no-entity
  45 { $class-description "XML parsing error describing the use of an undefined entity. Contains one slot, " { $snippet "thing" } ", containing a string representing the entity." }
  46 { $xml-error "<x>&foo;</x>" } ;
  47
  48
  49 HELP: pre/post-content
  50 { $class-description "Describes the error where a non-whitespace string is used before or after the main tag in an XML document. Contains two slots: " { $snippet "string" } " contains the offending string, and " { $snippet "pre?" } " is " { $snippet "t" } " if it occured before the main tag and " { $snippet "f" } " if it occured after." }
  51 { $xml-error "hello\n<main-tag/>" } ;
  52
  53 HELP: bad-name
  54 { $class-description "Describes the error where a name is used, for example in an XML tag or attribute key, which is invalid." }
  55 { $xml-error "<%>\n</%>" } ;
  56
  57 HELP: quoteless-attr
  58 { $class-description "Describes the error where an attribute of an XML tag is missing quotes around a value." }
  59 { $xml-error "<tag foo=bar/>" } ;
  60
  61 HELP: disallowed-char
  62 { $class-description "Describes the error where a disallowed character occurs in an XML document." } ;
  63
  64 HELP: missing-close
  65 { $class-description "Describes the error where a particular closing token is missing." } ;
  66
  67 HELP: unexpected-end
  68 { $class-description "Describes the error where a document unexpectedly ends, and the XML parser expected it to continue." } ;
  69
  70 HELP: duplicate-attr
  71 { $class-description "Describes the error where there is more than one attribute of the same key." }
  72 { $xml-error "<tag value='1' value='2'/>" } ;
  73
  74 HELP: bad-cdata
  75 { $class-description "Describes the error where CDATA is used outside of the main tag of an XML document." }
  76 { $xml-error "<x>y</x>\n<![CDATA[]]>" } ;
  77
  78 HELP: text-w/]]>
  79 { $class-description "Describes the error where a text node contains the literal string " { $snippet "]]>" } " which is disallowed." }
  80 { $xml-error "<x>Here's some text: ]]> there it was</x>" } ;
  81
  82 HELP: attr-w/<
  83 { $class-description "Describes the error where an attribute value contains the literal character " { $snippet "<" } " which is disallowed." }
  84 { $xml-error "<x value='bar<baz'/>" } ;
  85
  86 HELP: misplaced-directive
  87 { $class-description "Describes the error where an internal DTD directive is used outside of a DOCTYPE or DTD file, or where a DOCTYPE occurs somewhere other than before the main tag of an XML document." }
  88 { $xml-error "<x><!ENTITY foo 'bar'></x>" } ;
  89
  90 HELP: xml-error
  91 { $class-description "The exception class that all parsing errors in XML documents are in." } ;
  92
  93 ARTICLE: "xml.errors" "XML parsing errors"
  94 "The " { $vocab-link "xml.errors" } " vocabulary provides a rich and highly inspectable set of parsing errors. All XML errors are described by the union class " { $link xml-error } "."
  95 { $subsections
  96     multitags
  97     notags
  98     extra-attrs
  99     nonexist-ns
 100     not-yes/no
 101     unclosed
 102     mismatched
 103     expected
 104     no-entity
 105     pre/post-content
 106     unclosed-quote
 107     bad-name
 108     quoteless-attr
 109     disallowed-char
 110     missing-close
 111     unexpected-end
 112     duplicate-attr
 113     bad-cdata
 114     text-w/]]>
 115     attr-w/<
 116     misplaced-directive
 117 }
 118 "Additionally, most of these errors are a kind of " { $link xml-error } " which provides more information about where the error occurred."
 119 $nl
 120 "Note that, in parsing an XML document, only the first error is reported." ;
 121
 122 ABOUT: "xml.errors"