fish-shell/doc_src/cmds/for.rst

.. _cmd-for:

for - perform a set of commands multiple times
==============================================

Synopsis
--------

**for** *VARNAME* in [*VALUES*...]; *COMMANDS*...; **end**

Description
-----------

**for** is a loop construct. It will perform the commands specified by *COMMANDS* multiple times. On each iteration, the local variable specified by *VARNAME* is assigned a new value from *VALUES*. If *VALUES* is empty, *COMMANDS* will not be executed at all. The *VARNAME* is visible when the loop terminates and will contain the last value assigned to it. If *VARNAME* does not already exist it will be set in the local scope. For our purposes if the **for** block is inside a function there must be a local variable with the same name. If the **for** block is not nested inside a function then global and universal variables of the same name will be used if they exist.

Much like :ref:`set <cmd-set>`, **for** does not modify $status, but the evaluation of its subordinate commands can.

Example
-------

::

    for i in foo bar baz; echo $i; end
    
    # would output:
    foo
    bar
    baz


Notes
-----

The ``VARNAME`` was local to the for block in releases prior to 3.0.0. This means that if you did something like this:

::

    for var in a b c
        if break_from_loop
            break
        end
    end
    echo $var


The last value assigned to ``var`` when the loop terminated would not be available outside the loop. What ``echo $var`` would write depended on what it was set to before the loop was run. Likely nothing.
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 17:05:09 +08:00			`.. _cmd-for:`

doc: homogenize commands titles 2020-03-31 23:37:38 +08:00			`for - perform a set of commands multiple times`
			`==============================================`
Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
doc_src: Continue the slog through the letter F. We are using only :: in a synopsis for fishscript examples given of the command being documented. 2021-12-18 07:16:47 +08:00			`for VARNAME in [VALUES...]; COMMANDS...; end`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Description`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
doc_src: Continue the slog through the letter F. We are using only :: in a synopsis for fishscript examples given of the command being documented. 2021-12-18 07:16:47 +08:00			for is a loop construct. It will perform the commands specified by COMMANDS multiple times. On each iteration, the local variable specified by VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will not be executed at all. The VARNAME is visible when the loop terminates and will contain the last value assigned to it. If VARNAME does not already exist it will be set in the local scope. For our purposes if the for block is inside a function there must be a local variable with the same name. If the for block is not nested inside a function then global and universal variables of the same name will be used if they exist.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
doc_src: Continue the slog through the letter F. We are using only :: in a synopsis for fishscript examples given of the command being documented. 2021-12-18 07:16:47 +08:00			Much like :ref:`set <cmd-set>`, for does not modify $status, but the evaluation of its subordinate commands can.
Document that a for-loop passes through any exit status Unlike in other shells, for-loops do not set $status if 1. the loop count is zero, or if 2. the loop body consists of only commands like "set" that don't set $status. POSIX for-loops always set an exit status (they set 0 if no loop iterations). Following that would be awkward because it would add a lot of complexity in combination with the 2 special cases above. Document that "for" behaves the same as "set": it will pass through existing $status, and also the last child's $status. See the discussion in #8409 2021-11-18 21:27:44 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Example`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00			`::`

			`for i in foo bar baz; echo $i; end`

			`# would output:`
			`foo`
			`bar`
			`baz`

Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Notes`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			The ``VARNAME`` was local to the for block in releases prior to 3.0.0. This means that if you did something like this:
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00			`::`

			`for var in a b c`
			`if break_from_loop`
			`break`
			`end`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00			`end`
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00			`echo $var`

Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			The last value assigned to ``var`` when the loop terminated would not be available outside the loop. What ``echo $var`` would write depended on what it was set to before the loop was run. Likely nothing.