basis/xml/utilities/utilities-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 xml.data sequences strings ;
   4 IN: xml.utilities
   5
   6 ABOUT: "xml.utilities"
   7
   8 ARTICLE: "xml.utilities" "Utilities for processing XML"
   9     "Getting parts of an XML document or tag:"
  10     $nl
  11     "Note: the difference between deep-tag-named and tag-named is that the former searches recursively among all children and children of children of the tag, while the latter only looks at the direct children, and is therefore more efficient."
  12     { $subsection tag-named }
  13     { $subsection tags-named }
  14     { $subsection deep-tag-named }
  15     { $subsection deep-tags-named }
  16     { $subsection get-id }
  17     "To get at the contents of a single tag, use"
  18     { $subsection children>string }
  19     { $subsection children-tags }
  20     { $subsection first-child-tag }
  21     { $subsection assert-tag } ;
  22
  23 HELP: deep-tag-named
  24 { $values { "tag" "an XML tag or document" } { "name/string" "an XML name or string representing a name" } { "matching-tag" tag } }
  25 { $description "Finds an XML tag with a matching name, recursively searching children and children of children." }
  26 { $see-also tags-named tag-named deep-tags-named } ;
  27
  28 HELP: deep-tags-named
  29 { $values { "tag" "an XML tag or document" } { "name/string" "an XML name or string representing a name" } { "tags-seq" "a sequence of tags" } }
  30 { $description "Returns a sequence of all tags of a matching name, recursively searching children and children of children." }
  31 { $see-also tag-named deep-tag-named tags-named } ;
  32
  33 HELP: children>string
  34 { $values { "tag" "an XML tag or document" } { "string" "a string" } }
  35 { $description "Concatenates the children of the tag, throwing an exception when there is a non-string child." } ;
  36
  37 HELP: children-tags
  38 { $values { "tag" "an XML tag or document" } { "sequence" sequence } }
  39 { $description "Gets the children of the tag that are themselves tags." }
  40 { $see-also first-child-tag } ;
  41
  42 HELP: first-child-tag
  43 { $values { "tag" "an XML tag or document" } { "tag" tag } }
  44 { $description "Returns the first child of the given tag that is a tag." }
  45 { $see-also children-tags } ;
  46
  47 HELP: tag-named
  48 { $values { "tag" "an XML tag or document" }
  49     { "name/string" "an XML name or string representing the name" }
  50     { "matching-tag" tag } }
  51 { $description "Finds the first tag with matching name which is the direct child of the given tag." }
  52 { $see-also deep-tags-named deep-tag-named tags-named } ;
  53
  54 HELP: tags-named
  55 { $values { "tag" "an XML tag or document" }
  56     { "name/string" "an XML name or string representing the name" }
  57     { "tags-seq" "a sequence of tags" } }
  58 { $description "Finds all tags with matching name that are the direct children of the given tag." }
  59 { $see-also deep-tag-named deep-tags-named tag-named } ;
  60
  61 HELP: get-id
  62 { $values { "tag" "an XML tag or document" } { "id" "a string" } { "elem" "an XML element or f" } }
  63 { $description "Finds the XML tag with the specified id, ignoring the namespace." } ;