1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>read - read line of input into variables — fish-shell 4.2.1 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=4da8bbd6" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=f89b4716" />
<script src="../_static/documentation_options.js?v=6fb65176"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="realpath - convert a path to an absolute path without symlinks" href="realpath.html" />
<link rel="prev" title="random - generate random number" href="random.html" />
<link rel="shortcut icon" type="image/png" href="../_static/fish.png" />
</head><body><div id="fmain">
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="../_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="../index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="../commands.html" accesskey="U">Commands</a> »</li>
<li class="nav-item nav-item-this"><a href="">read - read line of input into variables</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../index.html">Documents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently asked questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../interactive.html">Interactive use</a></li>
<li class="toctree-l1"><a class="reference internal" href="../language.html">The fish language</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../commands.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fish_for_bash_users.html">Fish for bash users</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../completions.html">Writing your own completions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../prompt.html">Writing your own prompt</a></li>
<li class="toctree-l1"><a class="reference internal" href="../design.html">Design</a></li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../terminal-compatibility.html">Terminal Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">Contributing To Fish</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<div>
<h4><a href="../index.html">Sections</a></h4>
<ul>
<li><a class="reference internal" href="#">read - read line of input into variables</a><ul>
<li><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li><a class="reference internal" href="#description">Description</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="read-read-line-of-input-into-variables">
<h1>read - read line of input into variables<a class="headerlink" href="#read-read-line-of-input-into-variables" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<div class="highlight-fish-synopsis notranslate"><div class="highlight"><pre><span></span><span class="nf">read</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">OPTIONS</span><span class="g g-Other">]</span><span class="w"> </span><span class="g g-Other">[</span><span class="no">VARIABLE</span><span class="w"> </span><span class="g g-Other">...]</span>
</pre></div>
</div>
</section>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">read</span></code> reads from standard input and stores the result in shell variables. In an alternative mode, it can also print to its own standard output, for example for use in command substitutions.</p>
<p>By default, <code class="docutils literal notranslate"><span class="pre">read</span></code> reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given.</p>
<p>Unlike other shells, there is no default variable (such as <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">REPLY</span></code>) for storing the result - instead, it is printed on standard output.</p>
<p>When <code class="docutils literal notranslate"><span class="pre">read</span></code> reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1.
Otherwise, it is set to 0.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">read</span></code> sets a variable and you don’t specify a scope, it will use the same rules that <a class="reference internal" href="set.html"><span class="doc">set - display and change shell variables</span></a> does - if the variable exists, it will use it (in the lowest scope). If it doesn’t, it will use an unexported function-scoped variable.</p>
<p>The following options, like the corresponding ones in <a class="reference internal" href="set.html"><span class="doc">set - display and change shell variables</span></a>, control variable scope or attributes:</p>
<dl class="simple">
<dt><strong>-U</strong> or <strong>--universal</strong></dt><dd><p>Sets a universal variable.
The variable will be immediately available to all the user’s <code class="docutils literal notranslate"><span class="pre">fish</span></code> instances on the machine, and will be persisted across restarts of the shell.</p>
</dd>
<dt><strong>-f</strong> or <strong>--function</strong></dt><dd><p>Sets a variable scoped to the executing function.
It is erased when the function ends.</p>
</dd>
<dt><strong>-l</strong> or <strong>--local</strong></dt><dd><p>Sets a locally-scoped variable in this block.
It is erased when the block ends.
Outside of a block, this is the same as <strong>--function</strong>.</p>
</dd>
<dt><strong>-g</strong> or <strong>--global</strong></dt><dd><p>Sets a globally-scoped variable.
Global variables are available to all functions running in the same shell.
They can be modified or erased.</p>
</dd>
<dt><strong>-u</strong> or <strong>--unexport</strong></dt><dd><p>Prevents the variables from being exported to child processes (default behaviour).</p>
</dd>
<dt><strong>-x</strong> or <strong>--export</strong></dt><dd><p>Exports the variables to child processes.</p>
</dd>
</dl>
<p>The following options control the interactive mode:</p>
<dl class="simple">
<dt><strong>-c</strong> <em>CMD</em> or <strong>--command</strong> <em>CMD</em></dt><dd><p>Sets the initial string in the interactive mode command buffer to <em>CMD</em>.</p>
</dd>
<dt><strong>-s</strong> or <strong>--silent</strong></dt><dd><p>Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.</p>
</dd>
<dt><strong>-p</strong> or <strong>--prompt</strong> <em>PROMPT_CMD</em></dt><dd><p>Uses the output of the shell command <em>PROMPT_CMD</em> as the prompt for the interactive mode. The default prompt command is <code class="docutils literal notranslate"><span class="pre">set_color</span> <span class="pre">green;</span> <span class="pre">echo</span> <span class="pre">-n</span> <span class="pre">read;</span> <span class="pre">set_color</span> <span class="pre">normal;</span> <span class="pre">echo</span> <span class="pre">-n</span> <span class="pre">"></span> <span class="pre">"</span></code></p>
</dd>
<dt><strong>-P</strong> or <strong>--prompt-str</strong> <em>PROMPT_STR</em></dt><dd><p>Uses the literal <em>PROMPT_STR</em> as the prompt for the interactive mode.</p>
</dd>
<dt><strong>-R</strong> or <strong>--right-prompt</strong> <em>RIGHT_PROMPT_CMD</em></dt><dd><p>Uses the output of the shell command <em>RIGHT_PROMPT_CMD</em> as the right prompt for the interactive mode. There is no default right prompt command.</p>
</dd>
<dt><strong>-S</strong> or <strong>--shell</strong></dt><dd><p>Enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for <strong>--shell</strong> was <strong>-s</strong>, but it has been changed for compatibility with bash’s <strong>-s</strong> short opt for <strong>--silent</strong>.</p>
</dd>
</dl>
<p>The following options control how much is read and how it is stored:</p>
<dl class="simple">
<dt><strong>-d</strong> or <strong>--delimiter</strong> <em>DELIMITER</em></dt><dd><p>Splits on <em>DELIMITER</em>. <em>DELIMITER</em> will be used as an entire string to split on, not a set of characters.</p>
</dd>
<dt><strong>-n</strong> or <strong>--nchars</strong> <em>NCHARS</em></dt><dd><p>Makes <code class="docutils literal notranslate"><span class="pre">read</span></code> return after reading <em>NCHARS</em> characters or the end of the line, whichever comes first.</p>
</dd>
<dt><strong>-t</strong>, <strong>--tokenize</strong> or <strong>--tokenize-raw</strong></dt><dd><p>Causes read to split the input into variables by the shell’s tokenization rules.
This means it will honor quotes and escaping.
This option is of course incompatible with other options to control splitting like <strong>--delimiter</strong> and does not honor <span class="target" id="index-1"></span><a class="reference internal" href="../language.html#envvar-IFS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">IFS</span></code></a> (like fish’s tokenizer).
The <strong>-t</strong> -or <strong>--tokenize</strong> variants perform quote removal, so e.g. <code class="docutils literal notranslate"><span class="pre">a\</span> <span class="pre">b</span></code> is stored as <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">b</span></code>.
However variables and command substitutions are not expanded.</p>
</dd>
<dt><strong>-a</strong> or <strong>--list</strong></dt><dd><p>Stores the result as a list in a single variable. This option is also available as <strong>--array</strong> for backwards compatibility.</p>
</dd>
<dt><strong>-z</strong> or <strong>--null</strong></dt><dd><p>Marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.</p>
</dd>
<dt><strong>-L</strong> or <strong>--line</strong></dt><dd><p>Reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the <code class="docutils literal notranslate"><span class="pre">--delimiter</span></code> option.</p>
</dd>
</dl>
<p>Without the <code class="docutils literal notranslate"><span class="pre">--line</span></code> option, <code class="docutils literal notranslate"><span class="pre">read</span></code> reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in <em>VARIABLES</em>. If there are more tokens than variables, the complete remainder is assigned to the last variable.</p>
<p>If no option to determine how to split like <code class="docutils literal notranslate"><span class="pre">--delimiter</span></code>, <code class="docutils literal notranslate"><span class="pre">--line</span></code> or <code class="docutils literal notranslate"><span class="pre">--tokenize</span></code> is given, the variable <code class="docutils literal notranslate"><span class="pre">IFS</span></code> is used as a list of characters to split on. Relying on the use of <code class="docutils literal notranslate"><span class="pre">IFS</span></code> is deprecated and this behaviour will be removed in future versions. The default value of <code class="docutils literal notranslate"><span class="pre">IFS</span></code> contains space, tab and newline characters. As a special case, if <code class="docutils literal notranslate"><span class="pre">IFS</span></code> is set to the empty string, each character of the input is considered a separate token.</p>
<p>With the <code class="docutils literal notranslate"><span class="pre">--line</span></code> option, <code class="docutils literal notranslate"><span class="pre">read</span></code> reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized.</p>
<p>If no variable names are provided, <code class="docutils literal notranslate"><span class="pre">read</span></code> enters a special case that provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read a password from the console instead of hardcoding it in the command itself, which prevents it from showing up in fish’s history:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">mysql</span><span class="w"> </span><span class="no">-uuser</span><span class="w"> </span><span class="no">-p</span><span class="o">(</span><span class="nf">read</span><span class="o">)</span>
</pre></div>
</div>
<p>When running in this mode, <code class="docutils literal notranslate"><span class="pre">read</span></code> does not split the input in any way and text is redirected to standard output without any further processing or manipulation.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">-l</span></code> or <code class="docutils literal notranslate"><span class="pre">--list</span></code> is provided, only one variable name is allowed and the tokens are stored as a list in this variable.</p>
<p>In order to protect the shell from consuming too many system resources, <code class="docutils literal notranslate"><span class="pre">read</span></code> will only consume a
maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then <em>VARIABLE</em>
is set to empty and the exit status is set to 122. This limit can be altered with the
<span class="target" id="index-2"></span><a class="reference internal" href="../language.html#envvar-fish_read_limit"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_read_limit</span></code></a> variable. If set to 0 (zero), the limit is removed.</p>
</section>
<section id="example">
<h2>Example<a class="headerlink" href="#example" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">read</span></code> has a few separate uses.</p>
<p>The following code stores the value ‘hello’ in the shell variable <span class="target" id="index-3"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">foo</span></code>.</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="no">hello</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">foo</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="while.html"><span class="doc">while</span></a> command is a neat way to handle command output line-by-line:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s\n'</span><span class="w"> </span><span class="no">line1</span><span class="w"> </span><span class="no">line2</span><span class="w"> </span><span class="no">line3</span><span class="w"> </span><span class="no">line4</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">while</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">foo</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"This is another line: </span><span class="o">$foo</span><span class="s2">"</span>
<span class="w"> </span><span class="nf">end</span>
</pre></div>
</div>
<p>Delimiters given via “-d” are taken as one string:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="no">a==b==c</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="no">==</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$a</span><span class="w"> </span><span class="c"># a</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$b</span><span class="w"> </span><span class="c"># b</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$c</span><span class="w"> </span><span class="c"># c</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">--tokenize</span></code> honors quotes and escaping like the shell’s argument passing:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="s1">'a\ b'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">-t</span><span class="w"> </span><span class="no">first</span><span class="w"> </span><span class="no">second</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$first</span><span class="w"> </span><span class="c"># outputs "a b", $second is empty</span>
<span class="nf">echo</span><span class="w"> </span><span class="s1">'a"foo bar"b (command echo wurst)*" "{a,b}'</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">-lt</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$a</span><span class="w"> </span><span class="c"># outputs 'afoo barb' (without the quotes)</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$b</span><span class="w"> </span><span class="c"># outputs '(command echo wurst)* {a,b}' (without the quotes)</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$c</span><span class="w"> </span><span class="c"># nothing</span>
</pre></div>
</div>
<p>For an example on interactive use, see <a class="reference internal" href="../language.html#user-input"><span class="std std-ref">Querying for user input</span></a>.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="../_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="../index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="../commands.html" >Commands</a> »</li>
<li class="nav-item nav-item-this"><a href="">read - read line of input into variables</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="footer">
© Copyright fish-shell developers.
<br />
<a href="https://github.com/fish-shell/fish-shell/issues">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<script type="text/javascript">
FISH_DOCS_VERSION = "4.2";
function copy_to_clipboard(it) {
// Find the pre tag we're interested in.
var pre = it.target;
while (pre.tagName != "PRE") pre = pre.parentNode;
var txt = "";
// Cheesy: If we have a prompt,
// we only copy prompted lines,
// by splitting and matching and stuff
if (pre.querySelector('span.gp')) {
var texts= [];
for (var line of pre.innerText.split('\n')) {
if (line.match(/^>_?.*/)) {
texts.push(line.replace(/^>_?/, ""));
}
}
txt = texts.join("\n");
} else {
// Even cheesier: If we don't have a prompt, we remove the button text from the end.
var txt = pre.innerText.substring(0, pre.innerText.length - it.target.innerText.length).trim();
}
navigator.clipboard.writeText(txt).then(function() {
// Success - set the text to indicate it,
// then set it back after 2 seconds.
var span = pre.querySelector("button span");
if (span) {
var oldText = span.innerText;
span.innerText = "COPIED!";
setTimeout(function() {
span.innerText = oldText;
}, 2000);
}
}, function() {
});
}
(function () {
// Add copy buttons to all the codeblocks.
var codeblocks = document.querySelectorAll('div > pre');
var button = document.createElement('button');
var span = document.createElement('span');
span.innerText = "COPY";
button.appendChild(span);
for (var i of codeblocks) {
var newButton = button.cloneNode(true);
newButton.addEventListener('click', copy_to_clipboard);
i.appendChild(newButton);
}
})();
</script>
</body>
</html>
|
