4Suite™ API Documentation

# ► Module Ft.Xml.XPath.Util

General utilities for XPath applications

    Copyright 2005 Fourthought, Inc. (USA).
    Detailed license and copyright information: http://4suite.org/COPYRIGHT
    Project home, documentation, distributions: http://4suite.org/

Functions: Compile, ElementsById, Evaluate, ExpandQName, GetElementById, NormalizeNode, SimpleEvaluate |  |  |  | Globals: g_documentIdIndex

## Functions

Compile(expr)
  Given an XPath expression as a string, returns an object that allows an evaluation engine to operate on the expression efficiently. This "compiled" expression object can be passed to the Evaluate function instead of a string, in order to shorten the amount of time needed to evaluate the expression.
ElementsById(element, idmap)
  Given an element node and a cache of ID value to element node mappings already known, supplements the cache with mappings for all descendant elements that have ID attributes. The cache is modified in place.

      Only works for elements named 'id' or 'ID' in no namespace;
      the attribute type as defined by a DTD does not matter.

Evaluate(expr, contextNode=None, context=None)
  Evaluates the given XPath expression.

      Two arguments are required: the expression (as a string or compiled
      expression object), and a context. The context can be given as a
      Domlette node via the 'contextNode' named argument, or can be given as
      an Ft.Xml.XPath.Context.Context object via the 'context' named
      argument.

      If namespace bindings or variable bindings are needed, use a
      Context object. If extension functions are needed, either use a
      Context object, or set the EXTMODULES environment variable to be a
      ':'-separated list of names of Python modules that implement
      extension functions.

      The return value will be one of the following:
      node-set: list of Domlette node objects (xml.dom.Node based);
      string: Unicode string type;
      number: float type;
      boolean: Ft.Lib.boolean C extension object;
      or a non-XPath object (i.e. as returned by an extension function).

ExpandQName(qname, refNode=None, namespaces=None)
  Expand the given QName in the context of the given node, or in the given namespace dictionary.

      Returns a 2-tuple consisting of the namespace URI and local name.

GetElementById(document, idstr)
  Given an ID string, returns the node with that ID from the given Domlette document. Raises a ValueError if there is more than one element with that ID.
NormalizeNode(node)
  NormalizeNode is used to prepare a DOM for XPath evaluation.

      1.  Convert CDATA Sections to Text Nodes.
      2.  Normalize all text nodes (adjacent nodes are merged into the first one).

SimpleEvaluate(expr, node, explicitNss=None)
  Designed to be the most simple/brain-dead interface to using XPath Usually invoked through Node objects using: node.xpath(expr[, explicitNss])

      expr - XPath expression in string or compiled form
      node - the node to be used as core of the context for evaluating the XPath
      explicitNss - (optional) any additional or overriding namespace mappings
                    in the form of a dictionary of prefix: namespace
                    the base namespace mappings are taken from in-scope
                    declarations on the given node.  This explicit dictionary
                    is suprimposed on the base mappings

## Globals

g_documentIdIndex = {}