11 Переменные и параметры

<!-- Category: top-level-element -->
<!-- Category: instruction -->
<xsl:variable
  name = qname
  select = expression>
  <!-- Content: template -->
</xsl:variable>

<!-- Category: top-level-element -->
<xsl:param
  name = qname
  select = expression>
  <!-- Content: template -->
</xsl:param>

Переменная - это имя, которое может быть связано со значением. Значение, к которому привязана переменная, (значение переменной) может быть объектом любого типа, который может быть возвращен выражением. Для привязки переменных могут использоваться два элемента: xsl:variable и xsl:param. Разница между ними заключается в том, что значение, указанное в переменной xsl:param, является лишь значением по умолчанию. Если используется шаблон или стиль, в котором используется элемент xsl:param, то могут быть переданы параметры, которые будут использоваться вместо значений по умолчанию.

И xsl:variable, и xsl:param имеют обязательный атрибут name, задающий имя переменной. Значением атрибута name является QName, которое приводится к расширенному имени как описано в главе [2.4 Полные имена].

Когда используется любой из этих элементов привязки переменных, в дереве стилей всегда есть область, где эта привязка будет видима. В пределах этой области видима любая привязка данной переменной, однако соответствующий элемент привязки переменной остается скрытым. Таким образом, видна только самая внутренняя привязка переменной. Набор привязок переменной в области видимости выражения состоит из тех привязок, которые были видимы в том месте стиля, где это выражение находится.

11.1 Фрагменты конечного дерева

Переменные привносят в язык выражений новый тип данных. Этот дополнительный тип данных называется фрагментом конечного дерева (result tree fragment). Переменная может быть привязана к фрагменту конечного дерева, а не только к одному из четырех базовых типов данных в XPath (строка, число, булево значение, набор узлов). Фрагмент конечного дерева представляет здесь именно фрагмент в конечном дереве. Фрагмент конечного дерева обрабатывается точно так же как набор узлов, который содержит только один корневой узел. Однако для фрагмента конечного дерева разрешена лишь часть операций, допустимых для набора узлов. Операцию можно использовать для фрагмента конечного дерева только когда ее можно использовать для строки (операция над строкой может включать предварительное преобразование этой строки в число или булево значение). В частности, для фрагментов конечного дерева нельзя использовать операции /, // и []. Если для фрагмента конечного дерева выполняется рпазрешенная операция, то она выполняется точно так же как если применена к эквивалентному набору узлов.

Если в конечное дерево копируется фрагмент конечного дерева (см. [11.3 Использование значений переменных и параметров с конструкцией xsl:copy-of]), то в конечное дерево последовательно добавляются все узлы из эквивалентного набора узлов, являющиеся непосредственными потомками корневого узла.

Выражение может возвратить значение, имеющее тип фрагмента конечного дерева, либо ссылаясь на переменные, имеющие тип фрагмента конечного дерева, либо вызывая функции расширения, которые возвращают фрагмент конечного дерева, либо получая системное свойство, значением которых является фрагмент конечного дерева.

11.2 Значения переменных и параметров

Элемент привязки переменной может указывать значение переменной тремя разными способами.

• Если элемент привязки переменной имеет атрибут select, то значением этого атрибута должно быть выражение, а значением самой переменной является объект, полученный в результате обработки этого выражения. Содержимое элемента в этом случае должно быть пустым.

• Если элемент привязки переменной не имеет атрибута select, но имеет непустое содержание (иначе говоря, элемент привязки переменной имеет один или несколько узлов - непосредственных потомков), тогда требуемое значение задается содержимым элемента привязки переменной. Содержимое элемента привязки переменной является шаблоном, который обрабатывается для получения значения данной переменной. Этим значением является фрагмент конечного дерева, эквивалентный набору узлов, состоящему из одного корневого узла, который в качестве непосредственных потомков имеет последовательность узлов, полученных при обработке представленного шаблона. Базовым URI для узлов в рассматриваемом фрагменте конечного дерева является базовый URI элемента привязки переменной.

  Если в последовательности узлов, полученной при обработке шаблона, появится узел атрибута или узел пространства имен, фиксируется ошибка, поскольку корневой узел не может иметь непосредственным потомком ни узел атрибута, ни узел пространства имен. XSLT процессор может сигнализировать о такой ошибке. Если он этого не делает, то должен обработать ее сам, не добавляя соответствующий узел атрибутов или пространства имен.

• Если элемент привязки переменной имеет пустое содержание и не имеет атрибута select, значением переменной является пустая строка. Таким образом

  <xsl:variable name="x"/>

  равнозначно

  <xsl:variable name="x" select="''"/>

Замечание: Если переменная используется для нахождения узла по номеру позиции, то не следует делать следующего:

<xsl:variable name="n">2</xsl:variable>
... 
<xsl:value-of select="item[$n]"/>

Результатом будет значение первого элемента item, поскольку переменная n будет привязана к фрагменту конечного дерева, а не к числу. Вместо этого делайте либо

<xsl:variable name="n" select="2"/> 
...
<xsl:value-of select="item[$n]"/>

либо

<xsl:variable name="n">2</xsl:variable>
...
<xsl:value-of select="item[position()=$n]"/>

Замечание: Удобный прием, позволяющий задать пустой набор узлов в качестве значение по умолчанию для параметра:

<xsl:param name="x" select="/.."/>

11.3 Использование значений переменных и параметров с конструкцией xsl:copy-of

<!-- Category: instruction -->
<xsl:copy-of
  select = expression />

Чтобы вставить фрагмент конечного дерева в конечное дерево без предварительного преобразования в строку, как это делает xsl:value-of (см. [7.6.1 Создание текста с помощью xsl:value-of]), можно использовать элемент xsl:copy-of. Обязательный атрибут select содержит выражение. Если результатом обработки выражения является фрагмент конечного дерева, то этот фрагмент целиком копируется в конечное дерево. Если же результатом является набор узлов, в конечное дерево копируются все узлы этого набора и в том порядке, как они были в документе. Когда копируется узел элемента, вместе с самим узлом элемента копируются также узлы атрибутов, узлы пространства имен и непосредственные потомки этого узла элемента. Копирование корневого узла выполняется копированием его непосредственных потомков. Если результат не является ни набором узлов, ни фрагментом конечного дерева, то он преобразуется в строку, а затем помещается в конечное дерево, как при использовании xsl:value-of.

11.4 Переменные и параметры верхнего уровня

И xsl:variable, и xsl:param можно использовать в элементах верхнего уровня. Элемент привязки переменной на верхнем уровне декларирует глобальную переменную, которая видна отовсюду. Элемент верхнего уровня xsl:param декларирует параметр для стиля, однако XSLT не определяет механизм передачи параметров стилю. Если стиль содержит привязку для нескольких переменных верхнего уровня с одним и тем же именем и одинаковым приоритетом импорта, фиксируется ошибка. На верхнем уровне выражение или шаблон, указывающие значение переменной, обрабатываются с тем же контекстом, что и при обработке корневого узла в исходном документе: текущим узлом является корневой узел исходного документа, а текущим набором узлов - список, содержащий только корневой узел исходного документа. Если шаблон или выражение, определяющее значение глобальной переменной x, ссылается на глобальную переменную y, то значение y должны быть вычислено прежде значения x. Если это можно сделать не для всех глобальных деклараций переменных, фиксируется ошибка. Иными словами, фиксируется ошибка, если декларации зацикливаются.

Данный пример декларирует глобальную переменную para-font-size, с помощью которой в шаблоне значения атрибута делается ссылка.

<xsl:variable name="para-font-size">12pt</xsl:variable>

<xsl:template match="para">
 <fo:block font-size="{$para-font-size}"> 
   <xsl:apply-templates/> 
 </fo:block>
</xsl:template> 

11.5 Переменные и параметры в шаблонах

Помимо верхнего уровня, и xsl:variable, и xsl:param можно использовать также в шаблонах. xsl:variable можно ставить в любом месте шаблона, где допустимо использование инструкций. В этом случае, данная привязка видна для всех последующих узлов, имеющих того же родителя и их потомков. Заметим однако, что привязка для самого элемента xsl:variable не видна. xsl:param можно использовать как непосредственный потомок в начале элемента xsl:template. В данном контексте привязка переменной видна для всех последующих узлов, имеющих того же родителя и их потомков. Заметим, что для самого элемента xsl:param эта привязка не видна.

Одна привязка переменной маскирует другую, если она появляется в точке, где вторая привязка была видна и обе они имеют одно и то же имя. Если привязка переменной, задаваемая в шаблоне элементом xsl:variable или xsl:param, маскируется другой привязкой, заданной в том же шаблоне элементом xsl:variable или xsl:param, фиксируется ошибка. Однако если привязка переменной, заданная в шаблоне элементом xsl:variable или xsl:param, маскирует другую привязку, заданную элементом верхнего уровня xsl:variable или xsl:param, ошибка не фиксируется. Таким образом, в следующем примере содержится ошибка:

<xsl:template name="foo">
<xsl:param name="x" select="1"/> 
<xsl:variable name="x" select="2"/>
</xsl:template>

Однако допустим другой вариант:

<xsl:param name="x" select="1"/>
<xsl:template name="foo">
<xsl:variable name="x" select="2"/>
</xsl:template>

Замечание: В Java ближайшим эквивалентом элемента xsl:variable в шаблоне является декларация переменной типа final local с инициализацией. Например,

<xsl:variable name="x" select="'value'"/>

имеет семантику, похожую на

final Object x = "value";

В XSLT нет эквивалента оператору присвоения из Java

x = "value";

поскольку это затруднило бы реализацию процессора, который бы обрабатывал документ не в пакетном режиме, то есть, последовательно от начала до конца.

11.6 Передача параметров шаблону

<xsl:with-param
  name = qname
  select = expression>
  <!-- Content: template -->
</xsl:with-param>

Параметры передаются шаблонам с помощью элемента xsl:with-param. Обязательный атрибут name сообщает название параметра (переменной, значение которой должно быть изменено). Значением атрибута name является QName, процедура приведения которого к расширенному имени описана в главе [2.4 Полные имена]. xsl:with-param можно использовать для xsl:call-template и для xsl:apply-templates. Значение параметра задается точно так же, как для xsl:variable или xsl:param. При обработке значения, заданного элементом xsl:with-param, используются те же текущий узел и текущий набор узлов, что и для элементов xsl:apply-templates или xsl:call-template, в которых этот элемент находится. Если параметр x был передан в шаблон, не имеющий соответствующего элемента xsl:param, ошибка фиксироваться не будет, а сам параметр просто игнорируется.

В данном примере определяется именованный шаблон numbered-block с аргументом, задающий формат числа.

<xsl:template name="numbered-block"> 
  <xsl:param name="format">1. </xsl:param> 
  <fo:block>
    <xsl:number format="{$format}"/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="ol//ol/li">
  <xsl:call-template name="numbered-block">
    <xsl:with-param name="format">a. </xsl:with-param>
  </xsl:call-template>
</xsl:template>