wiki.bash-hackers.org/commands/builtin/declare.md

# The declare builtin command

## Synopsis

    declare [-aAfFgilrtux] [-p] [NAME[=VALUE] ...]

    # obsolete typeset synonym
    typeset [-aAfFgilrtux] [-p] [NAME[=VALUE] ...]

## Description

`declare` is used to display or set variables along with variable
attributes. When used to display variables/functions and their value,
the output is re-usable as input for the shell.

If no `NAME` is given, it displays the values of all variables or
functions when restricted by the `-f` option.

If `NAME` is followed by `=VALUE`, `declare` also sets the value for a
variable.

When used in a function, `declare` makes `NAMEs` local variables, unless
used with the `-g` option.

Don't use it's synonym `typeset` when coding for Bash, since it's tagged
as obsolete.

### Options

Below, `[-+]X` indicates an attribute, use `-X` to set the attribute,
`+X` to remove it.

| Option  | Description                                                                                                                                                    |
|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `[-+]a` | make NAMEs indexed arrays (removing with `+a` is valid syntax, but leads to an error message)                                                                  |
| `[-+]A` | make NAMEs associative arrays                                                                                                                                  |
| `[-+]c` | **Undocumented** convert NAMEs to "capcase" on assignment (makes the first letter upper-case and the rest lower). Requires Bash built with `-DCASEMOD_CAPCASE` |
| `-f`    | restrict action or display to function names and definitions (removing with `+f` is valid syntax, but leads to an error message)                               |
| `-F`    | restrict display to function names only (plus line number and source file when debugging)                                                                      |
| `-g`    | create global variables when used in a shell function; otherwise ignored (by default, `declare` declares local scope variables when used in shell functions)   |
| `[-+]i` | make NAMEs have the "integer" attribute                                                                                                                        |
| `[-+]l` | convert NAMEs to lower case on assignment (makes sure the variable contains only lower case letters)                                                           |
| `[-+]n` | make NAME a reference to the variable named by its value. Introduced in Bash 4.3-alpha                                                                         |
| `-p`    | display the attributes and value of each NAME                                                                                                                  |
| `[-+]r` | make NAMEs readonly (removing with `+r` is valid syntax, but not possible)                                                                                     |
| `[-+]t` | make NAMEs have the "trace" attribute (effective only for functions)                                                                                           |
| `[-+]u` | convert NAMEs to upper case on assignment (makes sure the variable contains only upper case letters)                                                           |
| `[-+]x` | make NAMEs exported                                                                                                                                            |

### Return status

| Status | Reason                                                                                 |
|:-------|:---------------------------------------------------------------------------------------|
| 0      | no error                                                                               |
| != 0   | invalid option                                                                         |
| != 0   | invalid variable name given                                                            |
| != 0   | attempt to **define** a function using `-f`                                            |
| != 0   | assignment to a readonly variable                                                      |
| != 0   | removing the readonly-attribute from a readonly variable                               |
| != 0   | assignment to an array variable without the compound assignment syntax (`array=(...)`) |
| != 0   | attempt to use `+a` to "destroy" an array                                              |
| != 0   | attemt to display a non-existent function with `-f`                                    |

## Notes

Unix shells offer very few datatypes. Bash and some other shells extend
this by allowing "attributes" to be set on variable names. The only
attributes specified by POSIX are `export` and `readonly`, which are set
by their own dedicated builtins. Datatypes in bash have a few other
interesting capabilities such as the ability to modify data on
assignment.

## Examples

### Display defined functions

`declare -f` can be used to display all defined functions...

    $ declare -f
    foo () 
    { 
        echo "FOO is BAR"
    }
    world () 
    { 
        echo "Hello World!"
    }

...or just a specific defined function.

    $ declare -f foo
    foo () 
    { 
        echo "FOO is BAR"
    }

### Nameref

Bash 4.3 adds a new way to indirectly reference variables. `typeset -n`
can be used to make a variable indirectly refer to another. In Bash, the
lvalue of the assignment given to `typeset -n` will refer to the
variable whose name is expanded on the RHS.

    # Sum a set of arrays and assign the result indirectly, also printing each intermediary result (without portability workarounds)
    # sum name arrname [ arrname ... ]
    function sum {
        typeset -n _result=$1 _arr
        typeset IFS=+
        _result=0
        for _arr in "${@:2}"; do                        # Demonstrate the special property of "for" on a nameref.
            (( _result += ${_arr[*]} ))
            printf '%s = %d\n' "${!_result}" "$_result" # Demonstrate the special property of ${!ref} on a nameref.
        done
    }

    a=(1 2 3) b=(6 5 4) c=(2 4 6)
    sum total a b c
    printf 'Final value of "total" is: %d\n' "$total"

\<div hide\> function sum {

      typeset -n _result=$1
      shift
      typeset IFS=+ _arrx
      _result=0
      for _arrx in "$@"; do                        # Demonstrate the special property of "for" on a nameref.
          typeset -n _arr=$_arrx
          (( _result += ${_arr[*]} ))
          printf '%s = %d\n' "${!_result}" "$_result" # Demonstrate the special property of ${!ref} on a nameref.
      done

}

a=(1 2 3); b=(6 5 4); c=(2 4 6) sum total a b c printf 'Final value of
"total" is: %d\n' "\$total" \</div\>

`typeset -n` is currently implemented in ksh93, mksh, and Bash 4.3. Bash
and mksh's implementations are quite similar, but much different from
ksh93's. See [Portability considerations](#portability_considerations)
for details. ksh93 namerefs are much more powerful than Bash's.

## Portability considerations

- `declare` is not specified by POSIX(r)
- `declare` is unique to Bash and totally non-portable with the possible
  exception of Zsh in Bash compatibility mode. Bash marks the synonym
  `typeset` as obsolete, which in Bash behaves identically to `declare`.
  All other Korn-like shells use `typeset`, so it probably isn't going
  away any time soon. Unfortunately, being a non-standard builtin,
  `typeset` differs significantly between shells. ksh93 also considers
  `typeset` a special builtin, while Bash does not - even in POSIX mode.
  If you use `typeset`, you should attempt to only use it in portable
  ways.
- **todo** nameref portability...

## See also

- [arrays](/syntax/arrays.md)
- [readonly](/commands/builtin/readonly.md)
- [unset](/commands/builtin/unset.md)