XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (145 page)

See Also

on page 240

on page 344

on page 425

on page 483

on page 517

xsl:character-map

The

element is a top-level XSLT declaration used to provide detailed control over the way individual characters are serialized. A character map is used only when the result of the transformation is serialized, and when the

declaration that controls the serialization references the character map.

Changes in 2.0

Character maps are a new feature in XSLT 2.0, designed as a replacement for
disable-output- escaping
, which is now deprecated.

Format

Position

is a top-level declaration, so it must always occur as a child of the

element.

Attributes

Content

Zero or more

elements.

Effect

The
name
attribute is mandatory, and defines the name of the character map. It must be a lexical QName: a name with or without a namespace prefix. If the name uses a prefix, it must refer to a namespace declaration that is in scope at this point in the stylesheet, and as usual it is the namespace URI rather than the prefix that is used when matching names. If several character maps in the stylesheet have the same name, then the one with highest import precedence is used; an error is reported if this rule does not identify a character map uniquely. Import precedence is explained on page 359.

The character map contains zero or more

elements. Each

element defines a mapping between a single Unicode character and a string that is used to represent that character in the serialized output. For example, the element:

indicates that the nonbreaking space character (Unicode codepoint 160) is to be represented on output by the string
 
. This illustrates one of the possible uses of character maps, which is to render specific characters using XML or HTML entity references.

The
use-character-maps
attribute is optional. It is used to build up one character map from a number of others. If present, its value must be a whitespace-separated list of tokens, each of which is a valid
QName
that refers to another named character map in the stylesheet. For example:

This example creates a composite character map called
latin-1-entities
that is effectively the union of three underlying character maps. The effect in this case is as if all the

elements in the three underlying character maps were actually present as children of the composite character map.

The rules for merging character maps are as follows. Firstly, there must be no circularities (a character map must not reference itself, directly or indirectly). The
expanded content
of a character map can then be defined (recursively) as the concatenation of the expanded content of each of the character maps referenced in its
use-character-maps
attribute, in the order in which they are named, followed by the

elements that are directly contained in the

element, in the order that they appear in the stylesheet. If the expanded content of a character map contains two mappings for the same Unicode character, then the one that comes last in this sequence is the one that is used.

Usage and Examples

Character maps have no effect on the XSLT transformation proper; they only affect the way that the result tree is serialized. If the result tree is used in some way other than passing it to a serializer (for example, if it is input to another transformation in a pipeline), then character maps have no effect.

For advice on using character maps as part of the serialization process, and worked examples, see Chapter 15
Serialization
.

See Also

on page 420

on page 424

Character Maps
in Chapter 15, page 941

xsl:choose

The

instruction defines a choice between a number of alternatives.

If there are two alternatives it performs the equivalent of
if-then-else
in other languages; if there are more than two, it performs the equivalent of a
switch
or
select
statement.

Changes in 2.0

There are no changes to the syntax of

in XSLT 2.0. However, by using

instructions within the

or

branch, it is now possible to use

in cases where the required result is an atomic value, or a reference to an existing node. In XSLT 1.0, the result always consisted of newly constructed nodes.

In many situations where

was used in XSLT 1.0, it is now possible to use an XPath conditional expression (
if
-
then
-
else
) instead, which can sometimes make the code much more compact.

Format

Position

is an instruction; it is always used within a sequence constructor.

Attributes

None.

Content

One or more

elements.

Optionally, an

element, which must come last if it is present at all.

Effect

The

element is evaluated as follows:

• The first
  
  element whose
  test
  expression
  is true is selected. Subsequent
  
  elements are ignored whether or not their
  test
  expression
  is true. The
  test
  expression is evaluated to obtain its
  effective boolean value
  ; the rules for this are given under
  
  , on page 354.
  
• If none of the
  
  elements has a
  test
  expression
  that is true, the
  
  element is selected. If there is no
  
  element, no element is selected, and the
  
  element therefore has no effect (it returns an empty sequence).
  
• The selected child element (if any) is executed by evaluating its sequence constructor in the current context. So the effect is as if the relevant sequence constructor appeared in place of the
  
  instruction.
  

The
test
expression in

elements after the selected one is not evaluated.

Usage

The

instruction is useful where there is a choice of two or more alternative courses of action. It thus performs the functions of both the
if
-
then
-
else
and
switch
or
Select
Case
constructs found in other programming languages.

Using

with a single

instruction and no

is permitted and means exactly the same as

. Some people suggest writing every

instruction this way, to save rewriting it later when you discover that you want an
else
branch after all.

When

is used within the body of an

(or

or

) element, the effect is a conditional assignment: the relevant variable is assigned a different value depending on the conditions.