Chapter 5. XPath extension functions which are specific to w2x

number content-type(node?)

Returns a numeric code indicating the type of contents of specified element (or parent element of specified node in case specified node is not an element). Returns -1 when this content type cannot be determined.

Parameter node defaults to the context element (or the parent element of the context node if the context node is not an element).

CodeDescription
0Empty.
1

Whitespace only.

[Important]

Non-breaking space characters ( ) are considered to be whitespace.

2Element only.
3Elements and whitespace.
4Text other than whitespace (words) but no elements.
6Words and elements.
number find-rule(string)

Returns the index of the CSS rule having specified selector. Returns -1 if such rule is not found in the document being edited.

For this function to work, command parse-styles must have been invoked in order to “intern” all the CSS rules found in the document being edited.

The string argument specifies the selector of a CSS rule.

Let's suppose the document being edited contains:

<style>
...
/* First character class rule is rule #43. */
.c-Important {
    color: #FF0000;
    font-weight: bold;
}

.c-Code {
    font-family: "Courier New";
    font-size: 9pt;
}
...
</style>
  • The string argument may be a number (possibly in string form). This number is the index of a CSS rule within the document being edited. First index is 0.

    Examples: find-rule(1000000) returns -1; find-rule(43) returns 43.

  • The string argument may be a selector.

    Examples: find-rule("NOT_FOUND") returns -1; find-rule(".c-Code") returns 44.

  • The string argument may be a selector pattern. The index of the first CSS rule having a selector matching this pattern is returned by this function.

    A selector pattern has the following syntax: /pattern/ or ^pattern$ (which is equivalent to /^pattern$/), where pattern is a regular expression pattern.

    Examples: find-rule("/NOT FOUND/") returns -1; find-rule("^\.c-.+$") returns 43.

See also get-rule.

Related commands: add-rule, remove-rule, set-rule.

number font-size(node?)

Equivalent to length(lookup-style("font-size", node)), but specifically adapted to the font-size CSS property (for example,it supports a font size expressed as a percentage).

string get-class(string?, node?)

Returns specified CSS class of specified element (or parent element of specified node in case specified node is not an element). Returns empty string "" when the element does not have specified class.

This function differs from @class=string in that it searches for CSS classes “interned” by the parse-styles editing command.

Parameter node defaults to the context element (or the parent element of the context node if the context node is not an element).

The first string argument specifies which CSS classes to search for. The first string argument defaults to the empty string "", which means: all classes.

Let's suppose the element which is the argument of this function has the following interned CSS classes "p-Normal pn-1-0 n-1-0".

  • The empty string "" specifies all classes.

    Example: get-class() or get-class("") returns "p-Normal pn-1-0 n-1-0".

  • The first argument may be a class name. This class is returned as is if found for specified element.

    Examples: get-class("NOT_FOUND") returns ""; get-class("p-Normal") returns "p-Normal".

  • The first argument may be a class pattern. Only the first class name matching this pattern is returned by this function.

    A class pattern has the following syntax: /pattern/ or ^pattern$ (which is equivalent to /^pattern$/), where pattern is a regular expression pattern.

    Examples: get-class("/n-\d/") returns "pn-1-0"; get-class("^p-.+$") returns "p-Normal".

Related commands: add-class, remove-class.

string get-rule(string, string?)

Returns the value of specified CSS style property if found in CSS rule having specified selector. Returns the empty string "" if specified rule is not found in the document being edited or if it does not contain specified property.

For this function to work, command parse-styles must have been invoked in order to “intern” all the CSS rules found in the document being edited.

The first string argument specifies the selector of a CSS rule.

The second string argument specifies the name of a CSS style property. The empty string "" means: all the properties of the CSS rule.

Let's suppose the document being edited contains:

<style>
...
/* First character class rule is rule #43. */
.c-Important {
    color: #FF0000;
    font-weight: bold;
}

.c-Code {
    font-family: "Courier New";
    font-size: 9pt;
}
...
</style>
  • The first string argument may be a number (possibly in string form). This number is the index of a CSS rule within the document being edited. First index is 0.

    Examples: get-rule(1000000) returns ""; get-rule("43") or get-rule(43, "") returns "color: #FF0000; font-weight: bold;"; get-rule(43, "NOT_FOUND") returns ""; get-rule(43, "color") returns "#FF0000".

  • The first string argument may be a selector.

    Examples: get-rule("NOT_FOUND") returns ""; get-rule(".c-Code") or get-rule(".c-Code", "") returns "font-family: "Courier New"; font-size: 9pt;"; get-rule(".c-Code", "NOT_FOUND") returns ""; get-rule(".c-Code", "font-size") returns "9pt".

  • The first string argument may be a selector pattern. The properties of the first CSS rule having a selector matching this pattern are returned by this function.

    A selector pattern has the following syntax: /pattern/ or ^pattern$ (which is equivalent to /^pattern$/), where pattern is a regular expression pattern.

    Examples: get-rule("/NOT FOUND/") returns ""; get-rule("^\.c-.+$") or get-rule("^\.c-.+$", "") returns "color: #FF0000; font-weight: bold;"; get-rule("^\.c-.+$", "NOT_FOUND") returns ""; get-rule("^\.c-.+$", "color") returns "#FF0000".

See also find-rule.

Related commands: add-rule, remove-rule, set-rule.

string get-style(string, node?)

Returns the value of specified CSS style property if directly set on specified element (or parent element of specified node in case specified node is not an element). Returns empty string "" when the element has no such direct CSS style property.

This function differs from substring-after(@style, concat(string, ":")) in that it searches for CSS style properties “interned” by the parse-styles editing command.

Parameter node defaults to the context element (or the parent element of the context node if the context node is not an element).

The first argument string specifies the name of a CSS style property.

Examples: let's suppose the element which is the argument of this function has the following interned CSS style properties "color: #FF0000; font-size: 9pt;", get-style("font-family") return ""; get-style("color") returns "#FF0000".

See also style-count, lookup-style.

Related commands: set-style.

boolean is-monospaced(string)

Returns true() is specified string contains the name of at least one monospaced font family; return false() otherwise.

Examples: is-monospaced("Calibri") return false(); is-monospaced("monospace") return true(); is-monospaced("'Courier New', 'Lucida Console'") return true().

number length(string, node?)

Converts first string argument, a CSS length value, to a number of points. Returns NaN if specified string cannot be parsed as a CSS length.

Parameter node defaults to the context element (or the parent element of the context node if the context node is not an element). The context element is needed to convert relative lengths such as "1.1em" to points.

Examples: length("") returns NaN; length("12pt") returns 12; length("12") returns 9 (implicit px unit; px are converted to pt assuming a 96DPI screen resolution).

See also lookup-length.

number lookup-length(string, node?)

Strictly equivalent to length(lookup-style(string, node)).

string lookup-style(string, node?)

Similar to get-style(string, node), except that the whole CSS cascade is searched for the CSS style property specified by the first string argument. While get-style limits its search to the CSS style properties directly set on the element, lookup-style

  1. searches the CSS style properties directly set on the element,

  2. searches the CSS style properties resulting from applying all matching CSS selectors to the element,

  3. if searched CSS style property is inheritable, repeats the first two steps for each ancestor of the element,

until searched CSS style property is found.

Function lookup-style is efficient because it works on CSS style properties, CSS classes and CSS rules “interned” by the parse-styles editing command.

See also lookup-length.

Related commands: add-rule, remove-rule, set-rule, set-style.

string or-regex(string+)

Concatenates specified strings and converts the result of this concatenation to an OR regular expression pattern. Returns specified string as is if passed a single string containing a single token.

This helper function is often used in conjunction with get-class to return the class matching one of several alternative classes.

Examples: or-regex("foo") returns "foo"; or-regex("foo bar") returns "^((foo)|(bar))$"; or-regex("foo bar", "gee") returns "^((foo)|(bar)|(gee))$".

string string-to-id(string, number?)

Converts first argument to an XML ID. For example, returns "_first_then_2_second" for "1 first then 2 second". Note that there is no guarantee that the returned ID is unique within a document.

The optional second argument specifies the maximum length of the returned ID. Its default value is 40.

number style-count(node?)

Returns the number of CSS style properties directly set on specified element (or parent element of specified node in case specified node is not an element). Returns 0 when the element has no direct CSS style properties.

This function differs from count(tokenize(@style, "\s+")) in that it counts CSS style properties “interned” by the parse-styles editing command.

Parameter node defaults to the context element (or the parent element of the context node if the context node is not an element).

Example: let's suppose the element which is the argument of this function has the following interned CSS style properties "color: #FF0000; font-size: 9pt;", this function would return 2.

See also get-style.

Related commands: set-style.

string unique-key-value(string, string)

First argument is a key name. Second argument is a key value. Returns second argument as is if the key map having a name equals to first argument does not contain this value. If the key map already contains this value then a suffix ("-2", "-3", "-4", etc) is automatically appended to second argument in order to obtain a new value which is not contained in the key map.

Example: unique-key-value("ids", "Reference"). If key map "ids" does not contain "Reference", unique-key-value() returns "Reference"; otherwise, if key map "ids" does not contain "Reference-2", unique-key-value() returns "Reference-2"; otherwise, if key map "ids" does not contain "Reference-3", unique-key-value() returns "Reference-3", etc.