totable

Purpose

Converts the argument to a table element it is found in.

Syntax

totable(element_name, $group)

Arguments

Takes two required arguments. The first argument element_name specifies a table element a user wants to extract. It takes values listed in the table below.

Value

Comments

table

whole table text, including table’s name.

table_name

table’s name.

row_text

row’s text (all cells' values separated by a space).

row_name

row’s name (a value of the leftmost cell of the row).

col_text

column text (all columns' value separated by a space).

col_name

column’s name (a value of the top cell of the column).

cell_text

cell’s text.

cell_unit

cell’s units (if specified).

cell_factor

cell scale factor.

table_num

table’s number

row_num

row’s number

col_num

column’s number

Notes When using unnamed parameters cell_unit and cell_factor, cell_unit and cell_factor values of adjacent table cells are displayed if they are available.

The second argument is a reference to a named group. The function also takes the following optional named parameters:

Parameter

Comments

first:=<numeral>

If the argument is omitted, the parameter is treated as a range of values. Otherwise, it specifies the offset of the start position.

last:=<numeral>

If the argument is omitted, the parameter is treated as a range of values. Otherwise, it specifies the offset of the end position.

separator:=<string>

The user can indicate a custom separator. If it is not specified, default separator "; " is used.

table_level:=<numeral>

Specifies a table level of the elements a user searches for. By default, the level is not set.

nested:=<string>

Specifies the search range within/out of/ within and out of nested tables. Takes "yes"/"no"/"any" values. Set to "any" by default.

has_nested:=<string>

Specifies if a table has nested tables. Takes "yes"/"no"/"any" values. Set to "any" by default.

parent_table:=<string>

Specifies if the output for a parent table should be shown. A parent table is the table one level up. Takes "yes"/"no"/"any" values. Set to "no" by default.

default:=<string>

Specifies the value assigned to the attribute if the result is empty.

Notes

  • If a program deals with a discontinuous argument that is found in different table elements, arguments will be separated by a separator.

  • The parameters first and last specify the offset of the start and the end position relative to the argument. By default, first:=0, last:=0.

  • The parameters first and last work for two regimes: for first level tables and their table names they deal with a document, but in other cases they deal with a table.

  • When using the first and last parameters, in case of a discontinuous argument, intersecting elements shown in the result are displayed only once.

Returned Value

The returned data type is string.

Examples

totable(row_name, first:=-1, last:=-1, $m) converts the argument $m to the row name preceding the row in which it was found. For example, if the named group is found in the fifth row, it will be converted to the name of the fourth group.

Note If the named group is found in the first row of the table, it will be impossible to convert it.

totable(row_name) converts the result to all row names of the table.

totable(row_name, first:=10, $m) is incorrect because the parameter last is not specified.

totable(row_name, first:=-10, $m) is correct because the value of the parameter last is greater then the value of the parameter first by default.

totable(row_name, first:=-100, last:=100, $m) if the named group $m is found in the first row of the table consisting of 5 rows, it will be converted to the names of these 5 rows.

totable(col_name, $m) if the named group $m is found in a cell containing only a nested table, then the values are displayed for both the parent and child tables and are aggregated.

totable(col_name, table_level:=1, $m) outputs the value of the top-level table as a result.

totable(col_name, nested:=yes, $m) outputs the value of the nested table as a result. If there are several nested tables, their values will be shown in the result. In this case, it is better to specify the table_level parameter.

totable(col_name, table_level:=2, $m) outputs the value of the nested table of the second level as a result.

totable(col_name, has_nested:=no, $m) outputs the value of the nested table of the last level which does not have its own nested tables.