File: //usr/share/zsh/help/integer
typeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ n ] ]
[ + ] [ name[=value] ... ]
typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ n ] ]
[ + | SCALAR[=value] array[=(value ...)] [ sep ] ]
typeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ]
Set or display attributes and values for shell parameters.
Except as noted below for control flags that change the behav-
ior, a parameter is created for each name that does not already
refer to one. When inside a function, a new parameter is cre-
ated for every name (even those that already exist), and is un-
set again when the function completes. See `Local Parameters'
in zshparam(1). The same rules apply to special shell parame-
ters, which retain their special attributes when made local.
For each name=value assignment, the parameter name is set to
value. If the assignment is omitted and name does not refer to
an existing parameter, a new parameter is initialized to empty
string, zero, or empty array (as appropriate), unless the shell
option TYPESET_TO_UNSET is set. When that option is set, the
parameter attributes are recorded but the parameter remains un-
set.
If the shell option TYPESET_SILENT is not set, for each remain-
ing name that refers to a parameter that is already set, the
name and value of the parameter are printed in the form of an
assignment. Nothing is printed for newly-created parameters, or
when any attribute flags listed below are given along with the
name. Using `+' instead of minus to introduce an attribute
turns it off.
If no name is present, the names and values of all parameters
are printed. In this case the attribute flags restrict the dis-
play to only those parameters that have the specified attrib-
utes, and using `+' rather than `-' to introduce the flag sup-
presses printing of the values of parameters when there is no
parameter name.
All forms of the command handle scalar assignment. Array as-
signment is possible if any of the reserved words declare, ex-
port, float, integer, local, readonly or typeset is matched when
the line is parsed (N.B. not when it is executed). In this case
the arguments are parsed as assignments, except that the `+='
syntax and the GLOB_ASSIGN option are not supported, and scalar
values after = are not split further into words, even if ex-
panded (regardless of the setting of the KSH_TYPESET option;
this option is obsolete).
Examples of the differences between command and reserved word
parsing:
# Reserved word parsing
typeset svar=$(echo one word) avar=(several words)
The above creates a scalar parameter svar and an array parameter
avar as if the assignments had been
svar="one word"
avar=(several words)
On the other hand:
# Normal builtin interface
builtin typeset svar=$(echo two words)
The builtin keyword causes the above to use the standard builtin
interface to typeset in which argument parsing is performed in
the same way as for other commands. This example creates a
scalar svar containing the value two and another scalar parame-
ter words with no value. An array value in this case would ei-
ther cause an error or be treated as an obscure set of glob
qualifiers.
Arbitrary arguments are allowed if they take the form of assign-
ments after command line expansion; however, these only perform
scalar assignment:
var='svar=val'
typeset $var
The above sets the scalar parameter svar to the value val.
Parentheses around the value within var would not cause array
assignment as they will be treated as ordinary characters when
$var is substituted. Any non-trivial expansion in the name part
of the assignment causes the argument to be treated in this
fashion:
typeset {var1,var2,var3}=name
The above syntax is valid, and has the expected effect of set-
ting the three parameters to the same value, but the command
line is parsed as a set of three normal command line arguments
to typeset after expansion. Hence it is not possible to assign
to multiple arrays by this means.
Note that each interface to any of the commands may be disabled
separately. For example, `disable -r typeset' disables the re-
served word interface to typeset, exposing the builtin inter-
face, while `disable typeset' disables the builtin. Note that
disabling the reserved word interface for typeset may cause
problems with the output of `typeset -p', which assumes the re-
served word interface is available in order to restore array and
associative array values.
Unlike parameter assignment statements, typeset's exit status on
an assignment that involves a command substitution does not re-
flect the exit status of the command substitution. Therefore,
to test for an error in a command substitution, separate the de-
claration of the parameter from its initialization:
# WRONG
typeset var1=$(exit 1) || echo "Trouble with var1"
# RIGHT
typeset var1 && var1=$(exit 1) || echo "Trouble with var1"
To initialize a parameter param to a command output and mark it
readonly, use typeset -r param or readonly param after the para-
meter assignment statement.
If no attribute flags are given, and either no name arguments
are present or the flag +m is used, then each parameter name
printed is preceded by a list of the attributes of that parame-
ter (array, association, exported, float, integer, readonly, or
undefined for autoloaded parameters not yet loaded). If +m is
used with attribute flags, and all those flags are introduced
with +, the matching parameter names are printed but their val-
ues are not.
The following control flags change the behavior of typeset:
+ If `+' appears by itself in a separate word as the last
option, then the names of all parameters (functions with
-f) are printed, but the values (function bodies) are
not. No name arguments may appear, and it is an error
for any other options to follow `+'. The effect of `+'
is as if all attribute flags which precede it were given
with a `+' prefix. For example, `typeset -U +' is equiv-
alent to `typeset +U' and displays the names of all ar-
rays having the uniqueness attribute, whereas `typeset -f
-U +' displays the names of all autoloadable functions.
If + is the only option, then type information (array,
readonly, etc.) is also printed for each parameter, in
the same manner as `typeset +m "*"'.
-g The -g (global) means that any resulting parameter will
not be restricted to local scope. Note that this does
not necessarily mean that the parameter will be global,
as the flag will apply to any existing parameter (even if
unset) from an enclosing function. This flag does not
affect the parameter after creation, hence it has no ef-
fect when listing existing parameters, nor does the flag
+g have any effect except in combination with -m (see be-
low).
-m If the -m flag is given the name arguments are taken as
patterns (use quoting to prevent these from being inter-
preted as file patterns). With no attribute flags, all
parameters (or functions with the -f flag) with matching
names are printed (the shell option TYPESET_SILENT is not
used in this case).
If the +g flag is combined with -m, a new local parameter
is created for every matching parameter that is not al-
ready local. Otherwise -m applies all other flags or as-
signments to the existing parameters.
Except when assignments are made with name=value, using
+m forces the matching parameters and their attributes to
be printed, even inside a function. Note that -m is ig-
nored if no patterns are given, so `typeset -m' displays
attributes but `typeset -a +m' does not.
-p [ n ]
If the -p option is given, parameters and values are
printed in the form of a typeset command with an assign-
ment, regardless of other flags and options. Note that
the -H flag on parameters is respected; no value will be
shown for these parameters.
-p may be followed by an optional integer argument. Cur-
rently only the value 1 is supported. In this case ar-
rays and associative arrays are printed with newlines be-
tween indented elements for readability.
-T [ scalar[=value] array[=(value ...)] [ sep ] ]
This flag has a different meaning when used with -f; see
below. Otherwise the -T option requires zero, two, or
three arguments to be present. With no arguments, the
list of parameters created in this fashion is shown.
With two or three arguments, the first two are the name
of a scalar and of an array parameter (in that order)
that will be tied together in the manner of $PATH and
$path. The optional third argument is a single-character
separator which will be used to join the elements of the
array to form the scalar; if absent, a colon is used, as
with $PATH. Only the first character of the separator is
significant; any remaining characters are ignored.
Multibyte characters are not yet supported.
Only one of the scalar and array parameters may be as-
signed an initial value (the restrictions on assignment
forms described above also apply).
Both the scalar and the array may be manipulated as nor-
mal. If one is unset, the other will automatically be
unset too. There is no way of untying the variables
without unsetting them, nor of converting the type of one
of them with another typeset command; +T does not work,
assigning an array to scalar is an error, and assigning a
scalar to array sets it to be a single-element array.
Note that both `typeset -xT ...' and `export -T ...'
work, but only the scalar will be marked for export.
Setting the value using the scalar version causes a split
on all separators (which cannot be quoted). It is possi-
ble to apply -T to two previously tied variables but with
a different separator character, in which case the vari-
ables remain joined as before but the separator is
changed.
When an existing scalar is tied to a new array, the value
of the scalar is preserved but no attribute other than
export will be preserved.
Attribute flags that transform the final value (-L, -R, -Z, -l,
-u) are only applied to the expanded value at the point of a pa-
rameter expansion expression using `$'. They are not applied
when a parameter is retrieved internally by the shell for any
purpose.
The following attribute flags may be specified:
-A The names refer to associative array parameters; see `Ar-
ray Parameters' in zshparam(1).
-L [ n ]
Left justify and remove leading blanks from the value
when the parameter is expanded. If n is nonzero, it de-
fines the width of the field. If n is zero, the width is
determined by the width of the value of the first assign-
ment. In the case of numeric parameters, the length of
the complete value assigned to the parameter is used to
determine the width, not the value that would be output.
The width is the count of characters, which may be multi-
byte characters if the MULTIBYTE option is in effect.
Note that the screen width of the character is not taken
into account; if this is required, use padding with para-
meter expansion flags ${(ml...)...} as described in `Pa-
rameter Expansion Flags' in zshexpn(1).
When the parameter is expanded, it is filled on the right
with blanks or truncated if necessary to fit the field.
Note truncation can lead to unexpected results with nu-
meric parameters. Leading zeros are removed if the -Z
flag is also set.
-R [ n ]
Similar to -L, except that right justification is used;
when the parameter is expanded, the field is left filled
with blanks or truncated from the end. May not be com-
bined with the -Z flag.
-U For arrays (but not for associative arrays), keep only
the first occurrence of each duplicated value. This may
also be set for tied parameters (see -T) or colon-sepa-
rated special parameters like PATH or FIGNORE, etc. Note
the flag takes effect on assignment, and the type of the
variable being assigned to is determinative; for vari-
ables with shared values it is therefore recommended to
set the flag for all interfaces, e.g. `typeset -U PATH
path'.
This flag has a different meaning when used with -f; see
below.
-Z [ n ]
Specially handled if set along with the -L flag. Other-
wise, similar to -R, except that leading zeros are used
for padding instead of blanks if the first non-blank
character is a digit. Numeric parameters are specially
handled: they are always eligible for padding with ze-
roes, and the zeroes are inserted at an appropriate place
in the output.
-a The names refer to array parameters. An array parameter
may be created this way, but it may be assigned to in the
typeset statement only if the reserved word form of type-
set is enabled (as it is by default). When displaying,
both normal and associative arrays are shown.
-f The names refer to functions rather than parameters. No
assignments can be made, and the only other valid flags
are -t, -T, -k, -u, -U and -z. The flag -t turns on exe-
cution tracing for this function; the flag -T does the
same, but turns off tracing for any named (not anonymous)
function called from the present one, unless that func-
tion also has the -t or -T flag. The -u and -U flags
cause the function to be marked for autoloading; -U also
causes alias expansion to be suppressed when the function
is loaded. See the description of the `autoload' builtin
for details.
Note that the builtin functions provides the same basic
capabilities as typeset -f but gives access to a few ex-
tra options; autoload gives further additional options
for the case typeset -fu and typeset -fU.
-h Hide: only useful for special parameters (those marked
`<S>' in the table in zshparam(1)), and for local parame-
ters with the same name as a special parameter, though
harmless for others. A special parameter with this at-
tribute will not retain its special effect when made lo-
cal. Thus after `typeset -h PATH', a function containing
`typeset PATH' will create an ordinary local parameter
without the usual behaviour of PATH. Alternatively, the
local parameter may itself be given this attribute; hence
inside a function `typeset -h PATH' creates an ordinary
local parameter and the special PATH parameter is not al-
tered in any way. It is also possible to create a local
parameter using `typeset +h special', where the local
copy of special will retain its special properties re-
gardless of having the -h attribute. Global special pa-
rameters loaded from shell modules (currently those in
zsh/mapfile and zsh/parameter) are automatically given
the -h attribute to avoid name clashes.
-H Hide value: specifies that typeset will not display the
value of the parameter when listing parameters; the dis-
play for such parameters is always as if the `+' flag had
been given. Use of the parameter is in other respects
normal, and the option does not apply if the parameter is
specified by name, or by pattern with the -m option.
This is on by default for the parameters in the zsh/para-
meter and zsh/mapfile modules. Note, however, that un-
like the -h flag this is also useful for non-special pa-
rameters.
-i [ n ]
Use an internal integer representation. If n is nonzero
it defines the output arithmetic base, otherwise it is
determined by the first assignment. Bases from 2 to 36
inclusive are allowed.
-E [ n ]
Use an internal double-precision floating point represen-
tation. On output the variable will be converted to sci-
entific notation. If n is nonzero it defines the number
of significant figures to display; the default is ten.
-F [ n ]
Use an internal double-precision floating point represen-
tation. On output the variable will be converted to
fixed-point decimal notation. If n is nonzero it defines
the number of digits to display after the decimal point;
the default is ten.
-l Convert the result to lower case whenever the parameter
is expanded. The value is not converted when assigned.
-r The given names are marked readonly. Note that if name
is a special parameter, the readonly attribute can be
turned on, but cannot then be turned off.
If the POSIX_BUILTINS option is set, the readonly at-
tribute is more restrictive: unset variables can be
marked readonly and cannot then be set; furthermore, the
readonly attribute cannot be removed from any variable.
It is still possible to change other attributes of the
variable though, some of which like -U or -Z would affect
the value. More generally, the readonly attribute should
not be relied on as a security mechanism.
Note that in zsh (like in pdksh but unlike most other
shells) it is still possible to create a local variable
of the same name as this is considered a different vari-
able (though this variable, too, can be marked readonly).
Special variables that have been made readonly retain
their value and readonly attribute when made local.
-t Tags the named parameters. Tags have no special meaning
to the shell. This flag has a different meaning when
used with -f; see above.
-u Convert the result to upper case whenever the parameter
is expanded. The value is not converted when assigned.
This flag has a different meaning when used with -f; see
above.
-x Mark for automatic export to the environment of subse-
quently executed commands. If the option GLOBAL_EXPORT
is set, this implies the option -g, unless +g is also ex-
plicitly given; in other words the parameter is not made
local to the enclosing function. This is for compatibil-
ity with previous versions of zsh.
declare
Same as typeset.
float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ n ] ] [ name[=value] ... ]
Equivalent to typeset -E, except that options irrelevant to
floating point numbers are not permitted.
integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ n ] ] [ name[=value] ... ]
Equivalent to typeset -i, except that options irrelevant to in-
tegers are not permitted.
local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ]
Same as typeset, except that the options -g, and -f are not per-
mitted. In this case the -x option does not force the use of
-g, i.e. exported variables will be local to functions.
readonly
Same as typeset -r. With the POSIX_BUILTINS option set, same as
typeset -gr.