diff options
Diffstat (limited to 'doc_src/tutorial.hdr')
| -rw-r--r-- | doc_src/tutorial.hdr | 956 |
1 files changed, 400 insertions, 556 deletions
diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr index e026bb3c..505adc7c 100644 --- a/doc_src/tutorial.hdr +++ b/doc_src/tutorial.hdr @@ -1,746 +1,590 @@ -/** \page tutorial Tutorial - -\htmlonly - -<style type="text/css"> - -body.tutorial_body { - font-family: "Helvetica Neue", Verdana, Helvetica, Arial, sans-serif; - font-size: 13pt; - background-color: #1E335E; - margin: 0; -} - -pre { - border: solid #AAA 1px; - background-color: black; - color: white; - padding: 10px 12px; - font-size: 10pt; - font-family: Menlo, Monaco, "DejaVu Sans Mono", "Courier New", Courier, monospace; - line-height: 140%; - white-space: pre-wrap; - margin-top: 10px; - tab-size: 4; - -moz-tab-size: 4; - -o-tab-size: 4; -} - -p { - margin-bottom: 10px; - margin-top: 0; - color: #333333; - line-height: 1.25em; -} - -tt { - font-family: monospace; -} - -.suggest { - color: #555; -} - -pre u { - border-bottom: 2px solid #0F0; - text-decoration: none; -} - -.meta { - color: white; -} - -pre b { - /* Used for commands */ - color: #005fd7; - font-weight: normal; -} - -pre i { - /* Used for arguments */ - color: #00afff; - font-style: normal; -} - -pre em { - /* Used for path/help word */ - color: #0a0; - font-style: normal; -} - -.quote { - color: #A50; -} - -.error { - /* Used for errors */ - color: #F55; - font-weight: bold; -} - -.tutorial_nav { - position: relative; - z-index: 2; - margin-left: 10px; - margin-top: 15px; -} - -.tutorial_nav ul { - padding: 0 15px; - margin: 0; -} - -.tutorial_nav li { - margin: 0; - line-height: normal; - height: auto; - color: #EEE; - font-size: 12pt; - font-family: "Trebuchet MS", Verdana, Arial, sans-serif; - list-style-image: none; - list-style-position: outside; - list-style-type: none; - padding: 3px 15px; - margin: 0 -15px; -} - -.tutorial_nav a { - color: inherit; - text-decoration: none; - font-family: - font-size: 12pt; -} - -.tutorial_nav .chevron { - font-family: Times, "Times New Roman"; - color: #DDF; - font-size: 16pt; - line-height: 10pt; - font-weight: bold; -} - -.no_shadow > li > a, -.no_shadow { - text-shadow: none; -} - -.nav > li > a:hover { - text-decoration: none; - background-color: inherit; - color: #99BBFF; -} - -/* Override some default left bar stuff */ -ul.nav li { - margin-bottom: 0; -} - - -.title_top { - width: 100%; - text-align: left; - color: white; - font-size: 18pt; - height: 72px; - z-index: 1; - text-indent: 260px; -} - -.tutorial_content { - -moz-box-shadow: -5px 0px 5px -2px black; - -webkit-box-shadow: -5px 0px 5px -2px black; - box-shadow: -5px 0px 5px -2px black; - - margin-left: 280px; - padding: 1px 25px 10px 10px; - position: relative; - z-index: 5; - background-color: white; -} - -h3 { - font-size: 25px; - margin-top: 12px; -} - -h1, h2, h3 { color: #1E335E; } -h1.interior_title { - color: #333; - padding-bottom: 10px; - border-bottom: 1px solid #AAA; -} - -h1 { font-size: 150%; } -h2 { font-size: 135%; } -h3 { font-size: 110%; } - - - -</style> - - -<div class="fish_left_bar fish_left_medium"> - <div class="tutorial_nav"> - <ul class="nav no_shadow"> - <li><a href="#tut_why_fish"><span class="chevron">›</span> Why fish?</a></li> - <li><a href="#tut_learning_Fish"><span class="chevron">›</span> Learning fish</a></li> - <li><a href="#tut_running_commands"><span class="chevron">›</span> Running Commands</a></li> - <li><a href="#tut_getting_help"><span class="chevron">›</span> Getting Help</a></li> - <li><a href="#tut_syntax_highlighting"><span class="chevron">›</span> Syntax Highlighting</a></li> - <li><a href="#tut_wildcards"><span class="chevron">›</span> Wildcards</a></li> - <li><a href="#tut_pipes_and_redirections"><span class="chevron">›</span> Pipes and Redirections</a></li> - <li><a href="#tut_autosuggestions"><span class="chevron">›</span> Autosuggestions</a></li> - <li><a href="#tut_tab_completions"><span class="chevron">›</span> Tab Completions</a></li> - <li><a href="#tut_variables"><span class="chevron">›</span> Variables</a></li> - <li><a href="#tut_exit_status"><span class="chevron">›</span> Exit Status</a></li> - <li><a href="#tut_exports"><span class="chevron">›</span> Environment Variables</a></li> - <li><a href="#tut_lists"><span class="chevron">›</span> Lists</a></li> - <li><a href="#tut_command_substitutions"><span class="chevron">›</span> Command Substitutions</a></li> - <li><a href="#tut_combiners"><span class="chevron">›</span> Combiners (And, Or, Not)</a></li> - <li><a href="#tut_conditionals"><span class="chevron">›</span> Conditionals (If, Else, Switch)</a></li> - <li><a href="#tut_functions"><span class="chevron">›</span> Functions</a></li> - <li><a href="#tut_loops"><span class="chevron">›</span> Loops</a></li> - <li><a href="#tut_prompt"><span class="chevron">›</span> Prompt</a></li> - <li><a href="#tut_startup"><span class="chevron">›</span> Startup</a></li> - </ul> - </div> +/** +\page tutorial Tutorial +\htmlonly[block] +<div class="fish_left_bar"> +<div class="logo"></div> +<div class="menu tutorial_menu"> +\endhtmlonly +- <a href="#tut_why_fish">Why fish?</a> +- <a href="#tut_learning_Fish">Learning fish</a> +- <a href="#tut_running_commands">Running Commands</a> +- <a href="#tut_getting_help">Getting Help</a> +- <a href="#tut_syntax_highlighting">Syntax Highlighting</a> +- <a href="#tut_wildcards">Wildcards</a> +- <a href="#tut_pipes_and_redirections">Pipes and Redirections</a> +- <a href="#tut_autosuggestions">Autosuggestions</a> +- <a href="#tut_tab_completions">Tab Completions</a> +- <a href="#tut_variables">Variables</a> +- <a href="#tut_exit_status">Exit Status</a> +- <a href="#tut_exports">Shell Variables</a> +- <a href="#tut_lists">Lists</a> +- <a href="#tut_command_substitutions">Command Substitutions</a> +- <a href="#tut_combiners">Combiners (And, Or, Not)</a> +- <a href="#tut_conditionals">Conditionals (If, Else, Switch)</a> +- <a href="#tut_functions">Functions</a> +- <a href="#tut_loops">Loops</a> +- <a href="#tut_prompt">Prompt</a> +- <a href="#tut_path">$PATH</a> +- <a href="#tut_startup">Startup</a> +- <a href="#tut_autoload">Autoloading Functions</a> +- <a href="#tut-more">Ready for more?</a> + +\htmlonly[block] +</div> </div> -<div class="fish_right_bar fish_right_medium"> - +<div class="tutorial fish_right_bar"> <h1 class="interior_title">fish tutorial</h1> +\endhtmlonly + +\section tut_why_fish Why fish? + +`fish` is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. `fish` supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure. -<h2 id="tut_why_fish">Why fish?</h2> +If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then `fish` might be just what you're looking for! -<p>fish is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. fish supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure. -<p>If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then fish might be just what you're looking for! +\section tut_learning_Fish Learning fish -<h2 id="tut_learning_Fish">Learning fish</h2> +This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of `fish`. -<p>This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of fish. +If you have a strong understanding of other shells, and want to know what `fish` does differently, search for the magic phrase <em>unlike other shells</em>, which is used to call out important differences. -<p>If you have a strong understanding of other shells, and want to know what fish does differently, search for the magic phrase <i>unlike other shells</i>, which is used to call out important differences. +When you start `fish`, you should see this: -<p>When you start fish, you should see this: +\fish{cli-dark} +<outp>Welcome to fish, the friendly interactive shell</outp> +<outp>Type <span class="cwd">help</span> for instructions on how to use fish</outp> +<asis>you@hostname</asis> ~>____ +\endfish -<pre> -Welcome to fish, the friendly interactive shell -Type <em>help</em> for instructions on how to use fish -you@hostname <em>~</em>> -</pre> +`fish` comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '`>`' to save space. -<p>fish comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '>' to save space. -<h2 id="tut_running_commands">Running Commands</h2> +\section tut_running_commands Running Commands -<p>fish runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: +`fish` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: -<pre> -> <b>echo</b> <i>hello world</i> -hello world -</pre> +\fish{cli-dark} +>_ echo hello world +<outp>hello world</outp> +\endfish You can include a literal space in an argument with a backslash, or by using single or double quotes: -<pre> -> <b>mkdir</b> <i>My\ Files</i> -> <b>cp</b> <i>~/Some\ File</i> <i class=quote>'My Files'</i> -> <b>ls</b> <i class=quote>"My Files"</i> -Some File -</pre> +\fish{cli-dark} +>_ mkdir My\ Files +>_ cp ~/Some\ File 'My Files' +>_ ls "My Files" +<outp>Some File</outp> +\endfish Commands can be chained with semicolons. -<h2 id="tut_getting_help">Getting Help</h2> -fish has excellent help and man pages. Run <tt>help</tt> to open help in a web browser, and <tt>man</tt> to open it in a man page. You can also ask for help with a specific command, for example, <tt>help set</tt> to open in a web browser, or <tt>man set</tt> to see it in the terminal. +\section tut_getting_help Getting Help + +`fish` has excellent help and man pages. Run `help` to open help in a web browser, and `man` to open it in a man page. You can also ask for help with a specific command, for example, `help set` to open in a web browser, or `man set` to see it in the terminal. + +\fish{cli-dark} +>_ man set +<outp>set - handle shell variables</outp> +<outp> Synopsis...</outp> +\endfish + -<pre> -> <b>man</b> <i>set</i> -set - handle environment variables - Synopsis... -</pre> +\section tut_syntax_highlighting Syntax Highlighting -<h2 id="tut_syntax_highlighting">Syntax Highlighting</h2> -You'll quickly notice that fish performs syntax highlighting as you type. Invalid commands are colored red by default: +You'll quickly notice that `fish` performs syntax highlighting as you type. Invalid commands are colored red by default: -<pre> -> <b class="error">/bin/mkd</b> -</pre> +\fish{cli-dark} +>_ <error>/bin/mkd</error> +\endfish A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color: -<pre> -> <b>/bin/mkdir</b> -</pre> +\fish{cli-dark} +>_ /bin/mkdir +\endfish -fish will underline valid file paths as you type them: +`fish` will underline valid file paths as you type them: -<pre> -> <b>cat</b> <i><span style="text-decoration: underline">~/somef<u>i</u></span></i> -</pre> +\fish{cli-dark} +>_ cat <u>~/somefi</u>___ +\endfish -<p>This tells you that there exists a file that starts with '<tt>somefi</tt>', which is useful feedback as you type. +This tells you that there exists a file that starts with '`somefi`', which is useful feedback as you type. -<p>These colors, and many more, can be changed by running <tt>fish_config</tt>, or by modifying variables directly. +These colors, and many more, can be changed by running `fish_config`, or by modifying variables directly. -<h2 id="tut_wildcards">Wildcards</h2> -fish supports the familiar wildcard *. To list all JPEG files: +\section tut_wildcards Wildcards -<pre> -> <b>ls</b> <i>*.jpg</i> -lena.jpg -meena.jpg -santa maria.jpg -</pre> +`fish` supports the familiar wildcard `*`. To list all JPEG files: -<p>You can include multiple wildcards: +\fish{cli-dark} +>_ ls *.jpg +<outp>lena.jpg</outp> +<outp>meena.jpg</outp> +<outp>santa maria.jpg</outp> +\endfish -<pre> -> <b>ls</b> <i>l*.p*</i> -lena.png -lesson.pdf -</pre> +You can include multiple wildcards: -<p>Especially powerful is the <i>recursive wildcard</i> ** which searches directories recursively: +\fish{cli-dark} +>_ ls l*.p* +<outp>lena.png</outp> +<outp>lesson.pdf</outp> +\endfish -<pre> -> <b>ls</b> <i>/var/**.log</i> -/var/log/system.log -/var/run/sntp.log -</pre> +Especially powerful is the recursive wildcard ** which searches directories recursively: -<p>If that directory traversal is taking a long time, you can control-C out of it. +\fish{cli-dark} +>_ ls /var/**.log +<outp>/var/log/system.log</outp> +<outp>/var/run/sntp.log</outp> +\endfish -<h2 id="tut_pipes_and_redirections">Pipes and Redirections</h2> +If that directory traversal is taking a long time, you can @key{Control,C} out of it. -<p>You can pipe between commands with the usual vertical bar: -<pre> -> <b>echo</b> <i>hello world</i> | <b>wc</b> - 1 2 12 -</pre> +\section tut_pipes_and_redirections Pipes and Redirections -<p>stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^ +You can pipe between commands with the usual vertical bar: -<pre> -> <b>grep</b> <i>fish</i> < /etc/shells > ~/output.txt ^ ~/errors.txt -</pre> +\fish{cli-dark} +>_ echo hello world | wc +<outp> 1 2 12</outp> +\endfish -<h2 id="tut_autosuggestions">Autosuggestions</h2> +stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^ -fish suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example: +\fish{cli-dark} +>_ grep fish < /etc/shells > ~/output.txt ^ ~/errors.txt +\endfish -<pre> -> <b class="error">/bin/h</b><span class="suggest"><u>o</u>stname</span> -</pre> + +\section tut_autosuggestions Autosuggestions + +`fish` suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example: + +\fish{cli-dark} +>_ <error>/bin/h</error><s>___ostname</s> +\endfish It knows about paths and options: -<pre> -> <b>grep</b> <i>--i<span class="suggest"><u>g</u>nore-case</span></i> -</pre> +\fish{cli-dark} +>_ grep --i<s>___gnore-case</s> +\endfish And history too. Type a command once, and you can re-summon it by just typing a few letters: -<pre> -> <b>r</b><span class="suggest"><u>s</u>ync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</span> -</pre> +\fish{cli-dark} +>_ <error>r</error><s>___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</s> +\endfish -To accept the autosuggestion, hit right arrow or Control-F. To accept a single word of the autosuggestion, hit Alt+right arrow. If the autosuggestion is not what you want, just ignore it. +To accept the autosuggestion, hit @cursor_key{→,right arrow} or @key{Control,F}. To accept a single word of the autosuggestion, @key{Alt,→} (right arrow). If the autosuggestion is not what you want, just ignore it. -<h2 id="tut_tab_completions">Tab Completions</h2> +\section tut_tab_completions Tab Completions -<p>fish comes with a rich set of tab completions, that work "out of the box." +`fish` comes with a rich set of tab completions, that work "out of the box." -<p>Press tab, and fish will attempt to complete the command, argument, or path: +Press @key{Tab}, and `fish` will attempt to complete the command, argument, or path: -<pre> -> <b class="error">/pri</b><span class="meta"><tab> →</span> <b>/private/</b> -</pre> +\fish{cli-dark} +>_ <error>/pri</error> @key{Tab} → /private/ +\endfish -<p>If there's more than one possibility, it will list them: -<pre> -> <b class="error">~/stuff/s</b><span class="meta"><tab></span> -<i>~/stuff/s</i>cript.sh <i class="quote">(Executable, 4.8kB)</i> <i>~/stuff/s</i>ources/ <i class="quote">(Directory)</i> -</pre> +If there's more than one possibility, it will list them: -<p>Hit tab again to cycle through the possibilities. +\fish{cli-dark} +>_ <error>~/stuff/s</error> @key{Tab} +<outp><m>~/stuff/s</m>cript.sh <i>(Executable, 4.8kB)</i> <m>~/stuff/s</m>ources/ <i>(Directory)</i></outp> +\endfish -<p>fish can also complete many commands, like git branches: +Hit tab again to cycle through the possibilities. -<pre> -> <b>git</b> <i>merge pr</i><span class="meta"><tab> →</span> git merge prompt_designer -> <b>git</b> <i>checkout b</i><span class="meta"><tab></span> -<i>b</i>uiltin_list_io_merge <i class="quote">(Branch)</i> <i>b</i>uiltin_set_color <i class="quote">(Branch)</i> <i>b</i>usted_events <i class="quote">(Tag)</i> -</pre> +`fish` can also complete many commands, like git branches: -Try hitting tab and see what fish can do! +\fish{cli-dark} +>_ git merge pr @key{Tab} → git merge prompt_designer +>_ git checkout b @key{Tab} +<outp><m>b</m>uiltin_list_io_merge <i>(Branch)</i> <m>b</m>uiltin_set_color <i>(Branch)</i> <m>b</m>usted_events <i>(Tag)</i></outp> +\endfish -<h2 id="tut_variables">Variables</h2> +Try hitting tab and see what `fish` can do! -<p>Like other shells, a dollar sign performs <i>variable substitution</i>: +\section tut_variables Variables -<pre> -> <b>echo</b> <i>My home directory is $HOME</i> -My home directory is /home/tutorial -</pre> +Like other shells, a dollar sign performs variable substitution: + +\fish{cli-dark} +>_ echo My home directory is $HOME +<outp>My home directory is /home/tutorial</outp> +\endfish Variable substitution also occurs in double quotes, but not single quotes: -<pre> -> <b>echo</b> <i class="quote">"My current directory is </i><i>$</i><i class="quote">PWD"</i> -My current directory is /home/tutorial -> <b>echo</b> <i class="quote">'My current directory is $PWD'</i> -My current directory is $PWD -</pre> +\fish{cli-dark} +>_ echo "My current directory is $PWD" +<outp>My current directory is /home/tutorial</outp> +>_ echo 'My current directory is $PWD' +<outp>My current directory is $PWD</outp> +\endfish + +Unlike other shells, `fish` has no dedicated syntax for setting variables. Instead it has an ordinary command: `set`, which takes a variable name, and then its value. -Unlike other shells, fish has no dedicated syntax for setting variables. Instead it has an ordinary command: <tt>set</tt>, which takes a variable name, and then its value. +\fish{cli-dark} +>_ set name 'Mister Noodle' +>_ echo $name +<outp>Mister Noodle</outp> +\endfish -<pre> -> <b>set</b> <i>name</i> <i class="quote">'Mister Noodle'</i> -> <b>echo</b> <i>$name</i> -Mister Noodle -</pre> +(Notice the quotes: without them, `Mister` and `Noodle` would have been separate arguments, and `$name` would have been made into a list of two elements.) -<p>(Notice the quotes: without them, <tt>Mister</tt> and <tt>Noodle</tt> would have been separate arguments, and <tt>$name</tt> would have been made into a <i>list</i> of two elements.) +Unlike other shells, variables are not further split after substitution: -<p>Unlike other shells, variables are <i>not</i> further split after substitution: +\fish{cli-dark} +>_ mkdir $name +>_ ls +<outp>Mister Noodle</outp> +\endfish -<pre> -> <b>mkdir</b> <i>$name</i> -> <b>ls</b> -Mister Noodle -</pre> +In bash, this would have created two directories "Mister" and "Noodle". In `fish`, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to `mkdir`, spaces and all. -In bash, this would have created two directories "Mister" and "Noodle". In fish, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to <span style="mono">mkdir</span>, spaces and all. -<h2 id="tut_exit_status">Exit Status</h2> +\section tut_exit_status Exit Status -Unlike other shells, fish stores the exit status of the last command in <tt>$status</tt> instead of <tt>$?</tt>. +Unlike other shells, `fish` stores the exit status of the last command in `$status` instead of `$?`. -<pre> -> <b>false</b> -> <b>echo</b> <i>$status</i> -1 -</pre> +\fish{cli-dark} +>_ false +>_ echo $status +<outp>1</outp> +\endfish Zero is considered success, and non-zero is failure. -<h2 id="tut_exports">Exports (Environment Variables)</h2> -Unlike other shells, fish does not have an export command. Instead, a variable is exported via an option to <tt>set</tt>, either <tt>--export</tt> or just <tt>-x</tt>. +\section tut_exports Exports (Shell Variables) + +Unlike other shells, `fish` does not have an export command. Instead, a variable is exported via an option to `set`, either `--export` or just `-x`. -<pre> -> <b>set</b> <i>-x MyVariable SomeValue</i> -> <b>env</b> | <b>grep</b> <i>MyVariable</i> -<span style="background: #A0A">MyVariable</span>=SomeValue -</pre> +\fish{cli-dark} +>_ set -x MyVariable SomeValue +>_ env | grep MyVariable +<outp><sm>MyVariable</sm>=SomeValue</outp> +\endfish -You can erase a variable with <tt>-e</tt> or <tt>--erase</tt> -<pre> -> <b>set</b> <i>-e MyVariable</i> -> <b>env</b> | <b>grep</b> <i>MyVariable</i> -<span class="meta">(no output)</span> -</pre> +You can erase a variable with `-e` or `--erase` -<h2 id="tut_lists">Lists</h2> +\fish{cli-dark} +>_ set -e MyVariable +>_ env | grep MyVariable +<outp>(no output)</outp> +\endfish -<p>The <tt>set</tt> command above used quotes to ensure that <tt>Mister Noodle</tt> was one argument. If it had been two arguments, then <tt>name</tt> would have been a <i>list</i> of length 2. In fact, all variables in fish are really lists, that can contain any number of values, or none at all. -<p>Some variables, like <tt>$PWD</tt>, only have one value. By convention, we talk about that variable's value, but we really mean its <i>first</i> (and only) value. +\section tut_lists Lists -<p>Other variables, like <tt>$PATH</tt>, really do have multiple values. During <i>variable expansion</i>, the variable expands to become multiple arguments: +The `set` command above used quotes to ensure that `Mister Noodle` was one argument. If it had been two arguments, then `name` would have been a list of length 2. In fact, all variables in `fish` are really lists, that can contain any number of values, or none at all. -<pre> -> <b>echo</b> <i>$PATH</i> -/usr/bin /bin /usr/sbin /sbin /usr/local/bin -</pre> +Some variables, like `$PWD`, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value. -<p>Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop. +Other variables, like `$PATH`, really do have multiple values. During variable expansion, the variable expands to become multiple arguments: -<p>Get the length of a list with <tt>count</tt>: +\fish{cli-dark} +>_ echo $PATH +<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp> +\endfish -<pre> -> <b>count</b> <i>$PATH</i> -5 -</pre> +Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop. + +Get the length of a list with `count`: + +\fish{cli-dark} +>_ count $PATH +<outp>5</outp> +\endfish You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH: -<pre> -> <b>set</b> <i>PATH $PATH /usr/local/bin</i> -</pre> +\fish{cli-dark} +>_ set PATH $PATH /usr/local/bin +\endfish You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end: -<pre> -> <b>echo</b> <i>$PATH</i> -/usr/bin /bin /usr/sbin /sbin /usr/local/bin -> <b>echo</b> <i>$PATH[1]</i> -/usr/bin -> <b>echo</b> <i>$PATH[-1]</i> -/usr/local/bin -</pre> + +\fish{cli-dark} +>_ echo $PATH +<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp> +>_ echo $PATH[1] +<outp>/usr/bin</outp> +>_ echo $PATH[-1] +<outp>/usr/local/bin</outp> +\endfish You can also access ranges of elements, known as "slices:" -<pre> -> <b>echo</b> <i>$PATH[1..2]</i> -/usr/bin /bin -> <b>echo</b> <i>$PATH[-1..2]</i> -/usr/local/bin /sbin /usr/sbin /bin -</pre> +\fish{cli-dark} +>_ echo $PATH[1..2] +<outp>/usr/bin /bin</outp> +>_ echo $PATH[-1..2] +<outp>/usr/local/bin /sbin /usr/sbin /bin</outp> +\endfish -You can iterate over a list (or a slice) with a <i>for loop</i>: +You can iterate over a list (or a slice) with a for loop: -<pre> -> <b>for</b> <i>val</i> <b>in</b> <i>$PATH</i> - <b>echo</b> <i>"entry: $val"</i> - <b>end</b> -entry: usr/bin/ -entry: /bin -entry: /usr/sbin -entry: /sbin -entry: /usr/local/bin -</pre> +\fish{cli-dark} +>_ for val in $PATH + echo "entry: $val" + end +<outp>entry: /usr/bin/</outp> +<outp>entry: /bin</outp> +<outp>entry: /usr/sbin</outp> +<outp>entry: /sbin</outp> +<outp>entry: /usr/local/bin</outp> +\endfish -<h2 id="tut_command_substitutions">Command Substitutions</h2> +\section tut_command_substitutions Command Substitutions -Command substitutions use the output of one command as an argument to another. Unlike other shells, fish does not use backticks ` for command substitutions. Instead, it uses parentheses: +Command substitutions use the output of one command as an argument to another. Unlike other shells, `fish` does not use backticks ` for command substitutions. Instead, it uses parentheses: -<pre> -> <b>echo</b> <i>In (</i><b>pwd</b><i>), running (</i><b>uname</b><i>)</i> -In /home/tutorial, running FreeBSD -</pre> +\fish{cli-dark} +>_ echo In (pwd), running (uname) +<outp>In /home/tutorial, running FreeBSD</outp> +\endfish A common idiom is to capture the output of a command in a variable: -<pre> -> <b>set</b> <i>os (</i><b>uname</b><i>)</i> -> <b>echo</b> <i>$os</i> -Linux -</pre> +\fish{cli-dark} +>_ set os (uname) +>_ echo $os +<outp>Linux</outp> +\endfish Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument: -<pre> -> <b>touch</b> <i class="quote">"testing_"</i><i>(</i><b>date</b> <i>+%s</i><i>)</i><i class="quote">".txt"</i> -> <b>ls</b> <i>*.txt</i> -testing_1360099791.txt -</pre> +\fish{cli-dark} +>_ touch <i class="quote">"testing_"</i>(date +%s)<i class="quote">".txt"</i> +>_ ls *.txt +<outp>testing_1360099791.txt</outp> +\endfish -<h2 id="tut_combiners">Combiners (And, Or, Not)</h2> -Unlike other shells, fish does not have special syntax like && or || to combine commands. Instead it has commands <tt>and</tt>, <tt>or</tt>, and <tt>not</tt>. +\section tut_combiners Combiners (And, Or, Not) -<pre> -> <b>cp</b> <i>file1.txt file1_bak.txt</i>; <b>and echo</b> <i class="quote">"Backup successful"</i>; <b>or echo</b> <i class="quote">"Backup failed"</i> -Backup failed -</pre> +Unlike other shells, `fish` does not have special syntax like && or || to combine commands. Instead it has commands `and`, `or`, and `not`. -<h2 id="tut_conditionals">Conditionals (If, Else, Switch)</h2> +\fish{cli-dark} +>_ cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed" +<outp>Backup failed</outp> +\endfish -Use <tt>if</tt>, <tt>else if</tt>, and <tt>else</tt> to conditionally execute code, based on the exit status of a command. -<pre> -<b>if grep</b> <i>fish /etc/shells</i> - <b>echo</b> <i>Found fish</i> -<b>else if grep</b> <i>bash /etc/shells</i> - <b>echo</b> <i>Found bash</i> -<b>else</b> - <b>echo</b> <i>Got nothing</i> -<b>end</b> -</pre> +\section tut_conditionals Conditionals (If, Else, Switch) -There is also a <tt>switch</tt> command: +Use `if`, `else if`, and `else` to conditionally execute code, based on the exit status of a command. -<pre> -<b>switch</b> <i>(</i><b>uname</b><i>)</i> - <b>case</b> <i>Linux</i> - <b>echo</b> <i>Hi Tux!</i> - <b>case</b> <i>Darwin</i> - <b>echo</b> <i>Hi Hexley!</i> - <b>case</b> <i>FreeBSD NetBSD DragonFly</i> - <b>echo</b> <i>Hi Beastie!</i> - <b>case</b> <i class="quote">'*'</i> - <b>echo</b> <i>Hi, stranger!</i> -<b>end</b> -</pre> +\fish{cli-dark} +if grep fish /etc/shells + echo Found fish +else if grep bash /etc/shells + echo Found bash +else + echo Got nothing +end +\endfish + +There is also a `switch` command: + +\fish{cli-dark} +switch (uname) +case Linux + echo Hi Tux! +case Darwin + echo Hi Hexley! +case FreeBSD NetBSD DragonFly + echo Hi Beastie! +case '*' + echo Hi, stranger! +end +\endfish + +Note that `case` does not fall through, and can accept multiple arguments or (quoted) wildcards. -Note that <tt>case</tt> does not fall through, and can accept multiple arguments or (quoted) wildcards. -<h2 id="tut_functions">Functions</h2> +\section tut_functions Functions -A fish function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like <tt>$1</tt>, but instead in a single list <tt>$argv</tt>. To create a function, use the <tt>function</tt> builtin: +A `fish` function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like `$1`, but instead in a single list `$argv`. To create a function, use the `function` builtin: -<pre> -> <i><b>function</b> say_hello - <b>echo</b> Hello $argv - <b>end</b></i> -> <b>say_hello</b> -Hello -> <b>say_hello <i>everybody!</i></b> -Hello everybody! -</pre> +\fish{cli-dark} +>_ function say_hello + echo Hello $argv + end +>_ say_hello +<outp>Hello</outp> +>_ say_hello everybody! +<outp>Hello everybody!</outp> +\endfish -<p>Unlike other shells, fish does not have aliases or special prompt syntax. Functions take their place. +Unlike other shells, `fish` does not have aliases or special prompt syntax. Functions take their place. -<p>You can list the names of all functions with the <tt>functions</tt> keyword (note the plural!). fish starts out with a number of functions: +You can list the names of all functions with the `functions` keyword (note the plural!). `fish` starts out with a number of functions: -<pre> -> <b>functions</b> -alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared -</pre> +\fish{cli-dark} +>_ functions +<outp>alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared</outp> +\endfish -<p>You can see the source for any function by passing its name to <tt>functions</tt>: +You can see the source for any function by passing its name to `functions`: -<pre> -> <b>functions</b> <i>ls</i> +\fish{cli-dark} +>_ functions ls function ls --description 'List contents of directory' - command ls -G $argv + command ls -G $argv end -</pre> +\endfish + -<h2 id="tut_loops">Loops</h2> +\section tut_loops Loops While loops: -<pre> -> <b>while</b> <i>true</i> - <b>echo</b> <i class="quote">"Loop forever"</i> -<b>end</b> -Loop forever -Loop forever -Loop forever -... -</pre> +\fish{cli-dark} +>_ while true + echo <i class="quote">"Loop forever"</i> +end +<outp>Loop forever</outp> +<outp>Loop forever</outp> +<outp>Loop forever</outp> +<outp>...</outp> +\endfish For loops can be used to iterate over a list. For example, a list of files: -<pre> -> <b>for</b> <i>file in *.txt</i> - <b>cp</b> <i>$file $file.bak</i> -<b>end</b> -</pre> +\fish{cli-dark} +>_ for file in *.txt + cp $file $file.bak +end +\endfish Iterating over a list of numbers can be done with `seq`: -<pre> -> <b>for</b> <i>x in (</i><b>seq</b> <i>5)</i> - <b>touch</b> <i>file_$x.txt</i> -<b>end</b> -</pre> +\fish{cli-dark} +>_ for x in (seq 5) + touch file_$x.txt +end +\endfish -<h2 id="tut_prompt">Prompt</h2> +\section tut_prompt Prompt -Unlike other shells, there is no prompt variable like PS1. To display your prompt, fish executes a function with the name <tt>fish_prompt</tt>, and its output is used as the prompt. +Unlike other shells, there is no prompt variable like PS1. To display your prompt, `fish` executes a function with the name `fish_prompt`, and its output is used as the prompt. You can define your own prompt: -<pre> -> <b>function <i>fish_prompt</i> - echo <i>"New Prompt % "</i> - end</b> -New Prompt % <u> </u> -</b> -</pre> - -Multiple lines are OK. Colors can be set via <tt>set_color</tt>, passing it named ANSI colors, or hex RGB values: - -<pre> -> <b>function</b> <i>fish_prompt</i> - <b>set_color</b> <i>purple</i> - <b>date</b> <i class="quote">"+%m/%d/%y"</i> - <b>set_color</b> <i>FF0</i> - <b>echo</b> <i>(</i><b>pwd</b><i>)</i> <i class="quote">'>'</i> - <b>set_color</b> <i>normal</i> - <b>end</b> + +\fish{cli-dark} +>_ function fish_prompt + echo "New Prompt % " +end +<asis>New Prompt % </asis>___ +\endfish + +Multiple lines are OK. Colors can be set via `set_color`, passing it named ANSI colors, or hex RGB values: + +\fish{cli-dark} +>_ function fish_prompt + set_color purple + date "+%m/%d/%y" + set_color FF0 + echo (pwd) '>' + set_color normal + end <span style="color: purple">02/06/13</span> -<span style="color: #FF0">/home/tutorial ></span><u> </u> -</b> -</pre> +<span style="color: #FF0">/home/tutorial ></span>___ +\endfish -<p>You can choose among some sample prompts by running <tt>fish_config prompt</tt>. fish also supports RPROMPT through <tt>fish_right_prompt</tt>. +You can choose among some sample prompts by running `fish_config prompt`. `fish` also supports RPROMPT through `fish_right_prompt`. -<h3>$PATH</h2> +\section tut-path $PATH -<tt>$PATH</tt> is an environment variable containing the directories in which fish searches for commands. Instead of separating entries with a colon, $PATH is a list. You can modify $PATH in a few ways: +`$PATH` is an environment variable containing the directories in which `fish` searches for commands. Instead of separating entries with a colon, $PATH is a list. You can modify $PATH in a few ways: -<p><ol> -<li>By modifying the <tt>$fish_user_paths</tt> variable, which is automatically appended to <tt>$PATH</tt>. For example, to permanently add /usr/local/bin to your <tt>$PATH</tt>, you could write: +-# By modifying the `$fish_user_paths` variable, which is automatically appended to `$PATH`. For example, to permanently add `/usr/local/bin` to your `$PATH`, you could write: -<pre> -> <b>set</b> <i>-U fish_user_paths $fish_user_paths /usr/local/bin</i> -</pre> +\fish{cli-dark} +>_ set -U fish_user_paths $fish_user_paths /usr/local/bin +\endfish +-# Directly in config.fish (see below). -<li>Directly in config.fish (see below).</li> -</ol> -<h2 id="tut_startup">Startup (Where's .bashrc?)</h2> +\section tut_startup Startup (Where's .bashrc?) -<p>fish starts by executing commands in <tt>~/.config/fish/config.fish</tt>. You can create it if it does not exist. +`fish` starts by executing commands in `~/.config/fish/config.fish`. You can create it if it does not exist. -<p>It is possible to directly create functions and variables in <tt>config.fish</tt> file, using the commands shown above. For example: +It is possible to directly create functions and variables in `config.fish` file, using the commands shown above. For example: -<p><pre> -> <b>cat</b> <i>~/.config/fish/config.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/config.fish set -x PATH $PATH /sbin/ function ll ls -lh $argv end -</pre> +\endfish -<p>However, it is more common and efficient to use <i>autoloading functions</i> and <i>universal variables</i>. +However, it is more common and efficient to use autoloading functions and universal variables. -<h3>Autoloading Functions</h2> +\section tut-autoload Autoloading Functions -<p>When fish encounters a command, it attempts to <i>autoload</i> a function for that command, by looking for a file with the name of that command in <tt>~/.config/fish/functions/</tt>. +When `fish` encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in `~/.config/fish/functions/`. -<p>For example, if you wanted to have a function <tt>ll</tt>, you would add a text file <tt>ll.fish</tt> to <tt>~/.config/fish/functions</tt>: +For example, if you wanted to have a function `ll`, you would add a text file `ll.fish` to `~/.config/fish/functions`: -<pre> -> <b>cat</b> <i>~/.config/fish/functions/ll.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/functions/ll.fish function ll - ls -lh $argv + ls -lh $argv end -</pre> +\endfish This is the preferred way to define your prompt as well: -<pre> -> <b>cat</b> <i>~/.config/fish/functions/fish_prompt.fish</i> +\fish{cli-dark} +>_ cat ~/.config/fish/functions/fish_prompt.fish function fish_prompt - echo (pwd) '> ' + echo (pwd) "> " end -</pre> +\endfish -<p>See the documentation for <a href="docs/current/commands.html#funced">funced</a> and <a href="docs/current/commands.html#funcsave">funcsave</a> for ways to create these files automatically. +See the documentation for <a href="commands.html#funced">funced</a> and <a href="commands.html#funcsave">funcsave</a> for ways to create these files automatically. -<h3>Universal Variables</h2> +\section tut-universal Universal Variables -<p>A universal variable is a variable whose value is shared across all instances of fish, now and in the future - even after a reboot. You can make a variable universal with <tt>set -U</tt>: +A universal variable is a variable whose value is shared across all instances of `fish`, now and in the future - even after a reboot. You can make a variable universal with `set -U`: -<pre> -> <b>set</b> <i>-U EDITOR vim</i> -</pre> +\fish{cli-dark} +>_ set -U EDITOR vim +\endfish Now in another shell: -<pre> -> <b>echo</b> <i>$EDITOR</i> +\fish{cli-dark} +>_ echo $EDITOR vim -</pre> +\endfish -<h3>Ready for more?</h2> +\section tut-more Ready for more? -<p>If you want to learn more about fish, there is <a href="docs/current/">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel <tt>#fish</tt> on <tt>irc.oftc.net</tt>, and the <a href="http://github.com/fish-shell/fish-shell/">github page</a>. +If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel \#fish on `irc.oftc.net`, and the <a href="https://github.com/fish-shell/fish-shell/">github page</a>. +\htmlonly[block] </div> - \endhtmlonly +\endhtmlonly +*/ |