14.1 Define, Get and Set Shared Conversion State ¶

Four types for selectors and value are currently considered:

string

A string.

integer

An integer

element

A Texinfo tree element.

index_entry.

An index entry reference as appearing in index data structures. See (texi2any_internals)Texinfo::Document index_entries.

New shared infomation is defined with define_shared_conversion_state:

Function: $converter->define_shared_conversion_state ($cmdname, $name, \@specification) ¶

$cmdname is an @-command name, without leading @. name is the name associated with the data. The top command name is conventionally used if there is no natural association with another @-command. \@specification array reference specifies the types of the selectors and the type of the value as strings. The last string of the array specifies the type of the value. The preceding strings specify the number and types of selectors⁵.

For example, ['integer', 'element', 'string'] specifies a ‘string’ type for the value, and two selectors, the first with ‘integer’ type, and the second with ‘element’ type. ['integer'] specifies an integer for the value and no selector.

For example, the following defines a ‘color’ shared conversion state formally associated with @quotation, with an integer value and a string selector.

$converter->define_shared_conversion_state ('quotation', 'color',
                                            ['string', 'integer']);

The association with an @-command is provided for a semantic classification of shared conversion information, but has no practical effect. In particular, nothing prevents using shared conversion state information associated with an @-command in the formatting of another @-command.

The function get_shared_conversion_state is used to get information:

Function: $value = $converter->get_shared_conversion_state ($cmdname, $name, [$selector …]) ¶

Return the reference $value associated with $cmdname and $name. The number of selectors given in argument should match the number of selectors in the definition (possibly none).

For example, continuing with the ‘color’ shared information data defined above, with one selector variable:

my $color_number
   = $converter->get_shared_conversion_state('quotation',
                                               'color', 'purple1');

The function set_shared_conversion_state is used to set shared information:

Function: $converter->define_shared_conversion_state ($cmdname, $name, [$selector …], $value) ¶

Sets $value associated with $cmdname and $name. The number of selectors given in argument should match the number of selectors in the definition (possible none).

For example:

$converter->set_shared_conversion_state('quotation', 'color',
                                        'special_black', 42);

The converter is used to hold the information, but does not use nor write.