basis/xml/traversal/traversal-docs.factor

   1 ! Copyright (C) 2005, 2009 Daniel Ehrenberg
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax xml.data sequences strings ;
   4 IN: xml.traversal
   5
   6 ABOUT: "xml.traversal"
   7
   8 ARTICLE: "xml.traversal" "Utilities for traversing XML"
   9     "The " { $vocab-link "xml.traversal" } " vocabulary provides utilities for traversing an XML DOM tree and viewing the contents of a single tag. The following words are defined:"
  10 $nl
  11 { $subsections
  12     { "xml.traversal" "intro" }
  13     tag-named
  14     tags-named
  15     deep-tag-named
  16     deep-tags-named
  17     get-id
  18 }
  19 "To get at the contents of a single tag, use"
  20 { $subsections
  21     children>string
  22     children-tags
  23     first-child-tag
  24     assert-tag
  25 } ;
  26
  27 ARTICLE: { "xml.traversal" "intro" } "An example of XML processing"
  28 "To illustrate how to use the XML library, we develop a simple Atom parser in Factor. Atom is an XML-based syndication format, like RSS. To see the full version of what we develop here, look at " { $snippet "basis/syndication" } " at the " { $snippet "atom1.0" } " word. First, we want to load a file and get a DOM tree for it."
  29 { $code "\"file.xml\" file>xml" }
  30 "No encoding descriptor is needed, because XML files contain sufficient information to auto-detect the encoding. Next, we want to extract information from the tree. To get the title, we can use the following:"
  31 { $code "\"title\" tag-named children>string" }
  32 "The " { $link tag-named } " word finds the first tag named " { $snippet "title" } " in the top level (just under the main tag). Then, with a tag on the stack, its children are asserted to be a string, and the string is returned." $nl
  33 "For a slightly more complicated example, we can look at how entries are parsed. To get a sequence of tags with the name " { $snippet "entry" } ":"
  34 { $code "\"entry\" tags-named" }
  35 "Imagine that, for each of these, we want to get the URL of the entry. In Atom, the URLs are in a " { $snippet "link" } " tag which is contained in the " { $snippet "entry" } " tag. There are multiple " { $snippet "link" } " tags, but one of them contains the attribute " { $snippet "rel=alternate" } ", and the " { $snippet "href" } " attribute has the URL. So, given an element of the sequence produced in the above quotation, we run the code:"
  36 { $code "\"link\" tags-named [ \"rel\" attr \"alternate\" = ] find nip " }
  37 "to get the link tag on the stack, and"
  38 { $code "\"href\" attr >url " }
  39 "to extract the URL from it." ;
  40
  41 HELP: deep-tag-named
  42 { $values { "tag" "an XML tag or document" } { "name/string" "an XML name or string representing a name" } { "matching-tag" tag } }
  43 { $description "Finds an XML tag with a matching name, recursively searching children and children of children." }
  44 { $see-also tags-named tag-named deep-tags-named } ;
  45
  46 HELP: deep-tags-named
  47 { $values { "tag" "an XML tag or document" } { "name/string" "an XML name or string representing a name" } { "tags-seq" "a sequence of tags" } }
  48 { $description "Returns a sequence of all tags of a matching name, recursively searching children and children of children." }
  49 { $see-also tag-named deep-tag-named tags-named } ;
  50
  51 HELP: children>string
  52 { $values { "tag" "an XML tag or document" } { "string" string } }
  53 { $description "Concatenates the children of the tag, throwing an exception when there is a non-string child." } ;
  54
  55 HELP: children-tags
  56 { $values { "tag" "an XML tag or document" } { "sequence" sequence } }
  57 { $description "Gets the children of the tag that are themselves tags." }
  58 { $see-also first-child-tag } ;
  59
  60 HELP: first-child-tag
  61 { $values { "tag" "an XML tag or document" } { "child" tag } }
  62 { $description "Returns the first child of the given tag that is a tag." }
  63 { $see-also children-tags } ;
  64
  65 HELP: tag-named
  66 { $values { "tag" "an XML tag or document" }
  67     { "name/string" "an XML name or string representing the name" }
  68     { "matching-tag" tag } }
  69 { $description "Finds the first tag with matching name which is the direct child of the given tag." }
  70 { $see-also deep-tags-named deep-tag-named tag-named-with-attr tags-named } ;
  71
  72 HELP: tag-named-with-attr
  73 { $values { "tag" "an XML tag or document" }
  74     { "tag-name" "an XML name or string representing the name" }
  75     { "attr-value" "a string representing the attribute value" }
  76     { "attr-name" "a string representing the attribute name" }
  77     { "matching-tag" tag } }
  78 { $description "Finds the first tag with matching name with the corresponding attribute name and value which is the direct child of the given tag." }
  79 { $see-also tag-named } ;
  80
  81 HELP: tags-named
  82 { $values { "tag" "an XML tag or document" }
  83     { "name/string" "an XML name or string representing the name" }
  84     { "tags-seq" "a sequence of tags" } }
  85 { $description "Finds all tags with matching name that are the direct children of the given tag." }
  86 { $see-also deep-tag-named deep-tags-named tag-named } ;
  87
  88 HELP: get-id
  89 { $values { "tag" "an XML tag or document" } { "id" string } { "elem" "an XML element or f" } }
  90 { $description "Finds the XML tag with the specified id, ignoring the namespace." } ;