From a8120359c732f5c87363158aaa3e4300ec0ceb09 Mon Sep 17 00:00:00 2001 From: ridiculousfish Date: Sun, 24 Feb 2019 19:40:27 -0800 Subject: [PATCH] Remove all of doc_src See the last_doxygen tag for the last supported Doxygen build. --- doc_src/FORMATTING.md | 253 ----- doc_src/abbr.txt | 83 -- doc_src/alias.txt | 41 - doc_src/and.txt | 23 - doc_src/argparse.txt | 131 --- doc_src/ascii_fish.png | Bin 12062 -> 0 bytes doc_src/begin.txt | 46 - doc_src/bg.txt | 25 - doc_src/bind.txt | 170 --- doc_src/block.txt | 46 - doc_src/break.txt | 25 - doc_src/breakpoint.txt | 14 - doc_src/builtin.txt | 24 - doc_src/case.txt | 42 - doc_src/cd.txt | 33 - doc_src/cdh.txt | 16 - doc_src/command.txt | 30 - doc_src/commandline.txt | 82 -- doc_src/commands.hdr.in | 38 - doc_src/complete.txt | 131 --- doc_src/contains.txt | 48 - doc_src/continue.txt | 26 - doc_src/count.txt | 25 - doc_src/design.hdr | 110 -- doc_src/dirh.txt | 14 - doc_src/dirs.txt | 15 - doc_src/disown.txt | 24 - doc_src/echo.txt | 60 - doc_src/else.txt | 23 - doc_src/emit.txt | 28 - doc_src/end.txt | 19 - doc_src/eval.txt | 21 - doc_src/exec.txt | 15 - doc_src/exit.txt | 12 - doc_src/false.txt | 10 - doc_src/faq.hdr | 306 ----- doc_src/fg.txt | 15 - doc_src/fish.txt | 34 - doc_src/fish_breakpoint_prompt.txt | 30 - doc_src/fish_config.txt | 18 - doc_src/fish_git_prompt.txt | 93 -- doc_src/fish_hg_prompt.txt | 45 - doc_src/fish_indent.txt | 28 - doc_src/fish_key_reader.txt | 35 - doc_src/fish_mode_prompt.txt | 37 - doc_src/fish_opt.txt | 54 - doc_src/fish_prompt.txt | 29 - doc_src/fish_right_prompt.txt | 26 - doc_src/fish_svn_prompt.txt | 82 -- doc_src/fish_update_completions.txt | 9 - doc_src/fish_vcs_prompt.txt | 28 - doc_src/fish_vi_mode.txt | 12 - doc_src/for.txt | 36 - doc_src/funced.txt | 20 - doc_src/funcsave.txt | 12 - doc_src/function.txt | 101 -- doc_src/functions.txt | 69 -- doc_src/help.txt | 23 - doc_src/history.txt | 79 -- doc_src/if.txt | 39 - doc_src/index.hdr.in | 1641 --------------------------- doc_src/isatty.txt | 35 - doc_src/jobs.txt | 33 - doc_src/license.hdr | 400 ------- doc_src/math.txt | 106 -- doc_src/nextd.txt | 32 - doc_src/not.txt | 23 - doc_src/open.txt | 17 - doc_src/or.txt | 23 - doc_src/popd.txt | 28 - doc_src/prevd.txt | 32 - doc_src/printf.txt | 70 -- doc_src/prompt_pwd.txt | 31 - doc_src/psub.txt | 28 - doc_src/pushd.txt | 44 - doc_src/pwd.txt | 16 - doc_src/random.txt | 44 - doc_src/read.txt | 94 -- doc_src/realpath.txt | 12 - doc_src/return.txt | 25 - doc_src/set.txt | 113 -- doc_src/set_color.txt | 57 - doc_src/source.txt | 29 - doc_src/status.txt | 70 -- doc_src/string.txt | 359 ------ doc_src/suspend.txt | 15 - doc_src/switch.txt | 39 - doc_src/test.txt | 166 --- doc_src/trap.txt | 37 - doc_src/true.txt | 10 - doc_src/tutorial.hdr | 727 ------------ doc_src/type.txt | 34 - doc_src/ulimit.txt | 64 -- doc_src/umask.txt | 41 - doc_src/user_doc.css | 269 ----- doc_src/user_doc.footer.html | 2 - doc_src/user_doc.header.html | 24 - doc_src/vared.txt | 15 - doc_src/wait.txt | 34 - doc_src/while.txt | 22 - 100 files changed, 7824 deletions(-) delete mode 100644 doc_src/FORMATTING.md delete mode 100644 doc_src/abbr.txt delete mode 100644 doc_src/alias.txt delete mode 100644 doc_src/and.txt delete mode 100644 doc_src/argparse.txt delete mode 100644 doc_src/ascii_fish.png delete mode 100644 doc_src/begin.txt delete mode 100644 doc_src/bg.txt delete mode 100644 doc_src/bind.txt delete mode 100644 doc_src/block.txt delete mode 100644 doc_src/break.txt delete mode 100644 doc_src/breakpoint.txt delete mode 100644 doc_src/builtin.txt delete mode 100644 doc_src/case.txt delete mode 100644 doc_src/cd.txt delete mode 100644 doc_src/cdh.txt delete mode 100644 doc_src/command.txt delete mode 100644 doc_src/commandline.txt delete mode 100644 doc_src/commands.hdr.in delete mode 100644 doc_src/complete.txt delete mode 100644 doc_src/contains.txt delete mode 100644 doc_src/continue.txt delete mode 100644 doc_src/count.txt delete mode 100644 doc_src/design.hdr delete mode 100644 doc_src/dirh.txt delete mode 100644 doc_src/dirs.txt delete mode 100644 doc_src/disown.txt delete mode 100644 doc_src/echo.txt delete mode 100644 doc_src/else.txt delete mode 100644 doc_src/emit.txt delete mode 100644 doc_src/end.txt delete mode 100644 doc_src/eval.txt delete mode 100644 doc_src/exec.txt delete mode 100644 doc_src/exit.txt delete mode 100644 doc_src/false.txt delete mode 100644 doc_src/faq.hdr delete mode 100644 doc_src/fg.txt delete mode 100644 doc_src/fish.txt delete mode 100644 doc_src/fish_breakpoint_prompt.txt delete mode 100644 doc_src/fish_config.txt delete mode 100644 doc_src/fish_git_prompt.txt delete mode 100644 doc_src/fish_hg_prompt.txt delete mode 100644 doc_src/fish_indent.txt delete mode 100644 doc_src/fish_key_reader.txt delete mode 100644 doc_src/fish_mode_prompt.txt delete mode 100644 doc_src/fish_opt.txt delete mode 100644 doc_src/fish_prompt.txt delete mode 100644 doc_src/fish_right_prompt.txt delete mode 100644 doc_src/fish_svn_prompt.txt delete mode 100644 doc_src/fish_update_completions.txt delete mode 100644 doc_src/fish_vcs_prompt.txt delete mode 100644 doc_src/fish_vi_mode.txt delete mode 100644 doc_src/for.txt delete mode 100644 doc_src/funced.txt delete mode 100644 doc_src/funcsave.txt delete mode 100644 doc_src/function.txt delete mode 100644 doc_src/functions.txt delete mode 100644 doc_src/help.txt delete mode 100644 doc_src/history.txt delete mode 100644 doc_src/if.txt delete mode 100644 doc_src/index.hdr.in delete mode 100644 doc_src/isatty.txt delete mode 100644 doc_src/jobs.txt delete mode 100644 doc_src/license.hdr delete mode 100644 doc_src/math.txt delete mode 100644 doc_src/nextd.txt delete mode 100644 doc_src/not.txt delete mode 100644 doc_src/open.txt delete mode 100644 doc_src/or.txt delete mode 100644 doc_src/popd.txt delete mode 100644 doc_src/prevd.txt delete mode 100644 doc_src/printf.txt delete mode 100644 doc_src/prompt_pwd.txt delete mode 100644 doc_src/psub.txt delete mode 100644 doc_src/pushd.txt delete mode 100644 doc_src/pwd.txt delete mode 100644 doc_src/random.txt delete mode 100644 doc_src/read.txt delete mode 100644 doc_src/realpath.txt delete mode 100644 doc_src/return.txt delete mode 100644 doc_src/set.txt delete mode 100644 doc_src/set_color.txt delete mode 100644 doc_src/source.txt delete mode 100644 doc_src/status.txt delete mode 100644 doc_src/string.txt delete mode 100644 doc_src/suspend.txt delete mode 100644 doc_src/switch.txt delete mode 100644 doc_src/test.txt delete mode 100644 doc_src/trap.txt delete mode 100644 doc_src/true.txt delete mode 100644 doc_src/tutorial.hdr delete mode 100644 doc_src/type.txt delete mode 100644 doc_src/ulimit.txt delete mode 100644 doc_src/umask.txt delete mode 100644 doc_src/user_doc.css delete mode 100644 doc_src/user_doc.footer.html delete mode 100644 doc_src/user_doc.header.html delete mode 100644 doc_src/vared.txt delete mode 100644 doc_src/wait.txt delete mode 100644 doc_src/while.txt diff --git a/doc_src/FORMATTING.md b/doc_src/FORMATTING.md deleted file mode 100644 index 98c7a2d39..000000000 --- a/doc_src/FORMATTING.md +++ /dev/null @@ -1,253 +0,0 @@ -# Formatting guide for fish docs - -The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs and man pages. - -Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort. - -While the documentation is pretty robust to variations in the documentation source, adherence to the following style guide will help keep the already excellent documentation in good shape moving forward. - -## Line breaks and wrapping - -Contrary to the rest of the fish source code, the documentation greatly benefits from the use of long lines and soft wrapping. Doxygen is able to treat paragraphs as complete blocks. The semantic filter can see complete lines when deciding on how to apply syntax highlighting. In advanced pagers, such as 'most', man pages will consistently wrap to the width of the user's console. - -## Doxygen special commands and aliases - -While Markdown syntax forms the basis of the documentation content, there are some exceptions that require the use of Doxygen special commands. On the whole, Doxygen commands should be avoided, especially inline word formatting such as \\c as this would allow Doxygen to make unhelpful assumptions, such as converting double dashes (\--) to n-dashes (–). - -### Structure: \\page, \\section and \\subsection - -Use of Doxygen sections markers are important, as these determine what will be eventually output as a web page, man page or included in the developer docs. - -Currently the make process for the documentation is quite convoluted, but basically the HTML docs are produced from a single, compiled file, doc.h. This contains a number of \\page markers that produce the various pages used in the documentation. The format of a \\page mark is: - - \page universally_unique_page_id Page title - -The source files that contain the page markers are currently: - -- __index.hdr.in__: Core documentation -- __commands.hdr.in__: Individual commands -- __tutorial.hdr__: Tutorial -- __design.hdr__: Design document -- __faq.hdr__: Frequently Asked Questions -- __license.hdr__: Fish and 3rd party licences - -Unless there is a _VERY_ good reason and developer consensus, new pages should never be added. - -The rest of the documentation is structured using \\section and \\subsection markers. Most of the source files (listed above) contain their full content, the exception being commands, which are separated out into source text files in the doc_src directory. These files are concatenated into one file, so each one starts with a \\section declaration. The synopsis, description and examples (if present) are declared as \\subsections. The format of these marks is practically identical to the page mark. - - \section universally_unique_section_id Section title - \subsection universally_unique_subsection_id Subsection title - -Each page, section and subsection id _must_ be unique across the whole of the documentation, otherwise Doxygen will issue a warning. - -### Semantic markup: the \\fish .. \\endfish block - -While Doxygen has support for \\code..\\endcode blocks with enhanced markup and syntax colouring, it only understands the core Doxygen languages: C, C++, Objective C, Java, PHP, Python, Tcl and Fortran. To enhance Fish's syntax presentation, use the special \\fish..\\endfish blocks instead. - -Text placed in this block will be parsed by Doxygen using the included lexicon filter (see lexicon_filter.in) as a Doxygen input filter. The filter is built during make so that it can pick up information on builtins, functions and shell commands mentioned in completions and apply markup to keywords found inside the \\fish block. - -Basically, preformatted plain text inside the \\fish block is fed through the filter and is returned marked up so that Doxygen aliases can convert it back to a presentable form, according to the output document type. - -For instance: - -`echo hello world` - -is transformed into: - -`@cmnd{echo} @args{hello} @args{world}` - -which is then transformed by Doxygen into an HTML version (`make doc`): - -`echo hello world` - -And a man page version (`make share/man`): - -__echo__ hello world - -### Fonts - -In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default. - -I've tried to use a sensible set of fonts in the documentation's CSS based on 'good' terminal fonts and as a result the first preference font used throughout the documentation is '[DejaVu](https://dejavu-fonts.github.io)'. The rationale behind this is that while DejaVu is getting a little long in the tooth, it still provides the most complete support across serif, sans-serif and monospace styles (giving a well balanced feel and consistent [x-height](https://en.wikipedia.org/wiki/X-height)), has the widest support for extended Unicode characters and has a free, permissive licenses (though it's still incompatible with GPLv2, though arguably less so than the SIL Open Font license, though this is a moot point when using it solely in the docs). - -#### Fonts inside \\fish blocks and \`backticks\` - -As the point of these constructs is to make fish's syntax clearer to the user, it makes sense to mimic what the user will see in the console, therefore any content is formatted using the monospaced style, specifically monospaced fonts are chosen in the following order: - -1. __DejaVu Sans Mono__: Explained above. [[↓](https://dejavu-fonts.github.io)] -2. __Source Code Pro__: Monospaced code font, part of Adobe's free Edge Web Fonts. [[↓](https://edgewebfonts.adobe.com)] -3. __Menlo__: Apple supplied variant of DejaVu. -4. __Ubuntu Mono__: Ubuntu Linux's default monospaced font. [[↓](http://font.ubuntu.com)] -5. __Consolas__: Modern Microsoft supplied console font. -6. __Monaco__: Apple supplied console font since 1984! -7. __Lucida Console__: Generic mono terminal font, standard in many OS's and distros. -8. __monospace__: Catchall style. Chooses default monospaced font, often Courier. -9. __fixed__: As above, more often used on mobile devices. - -#### General Fonts - -1. __DejaVu Sans__: As above.[[↓](https://dejavu-fonts.github.io)] -2. __Roboto__: Elegant Google free font and is Doxygen's default [[↓](https://fonts.google.com/specimen/Roboto)] -3. __Lucida Grande__: Default Apple OS X content font. -4. __Calibri__: Default Microsoft Office font (since 2007). -5. __Verdana__: Good general font found in a lot of OSs. -6. __Helvetica Neue__: Better spaced and balanced Helvetica/Arial variant. -7. __Helvetica__: Standard humanist typeface found almost everywhere. -8. __Arial__: Microsoft's Helvetica. -9. __sans-serif__: Catchall style. Chooses default sans-serif typeface, often Helvetica. - -The ordering of the fonts is important as it's designed to allow the documentation to settle into a number of different identities according to the fonts available. If you have the complete DejaVu family installed, then the docs are presented using that, and if your Console is set up to use the same fonts, presentation will be completely consistent. - -On OS X, with nothing extra installed, the docs will default to Menlo and Lucida Grande giving a Mac feel. Under Windows, it will default to using Consolas and Calibri on recent versions, giving a modern Windows style. - -#### Other sources: - -- [Font Squirrel](https://www.fontsquirrel.com): Good source of open source font packages. - -### Choosing a CLI style: using a \\fish{style} block - -By default, when output as HTML, a \\fish block uses syntax colouring suited to the style of the documentation rather than trying to mimic the terminal. The block has a light, bordered background and a colour scheme that 'suggests' what the user would see in a console. - -Additional stying can be applied adding a style declaration: - - \fish{additional_style [another_style...]} - ... - \endfish - -This will translate to classes applied to the `
` tag, like so: - -
- ... -
- -The various classes are defined in `doc_src/user_doc.css` and new style can be simply added - -The documentation currently defines a couple of additional styles: - -- __cli-dark__: Used in the _tutorial_ and _FAQ_ to simulate a dark background terminal, with fish's default colours (slightly tweaked for legibility in the browser). - -- __synopsis__: A simple colour theme helpful for displaying the logical 'summary' of a command's syntax, options and structure. - -## Markdown - -Apart from the exceptions discussed above, the rest of the documentation now supports the use of Markdown. As such the use of Doxygen special commands for HTML tags is unnecessary. - -There are a few exceptions and extensions to the Markdown [standard](https://daringfireball.net/projects/markdown/) that are documented in the Doxygen [documentation](https://www.stack.nl/~dimitri/doxygen/manual/markdown.html). - -### \`Backticks\` - -As is standard in Markdown and 'Github Flavoured Markdown' (GFM), backticks can be used to denote inline technical terms in the documentation, `like so`. In the documentation this will set the font to the monospaced 'console' typeface and will cause the enclosed term to stand out. - -However, fenced code blocks using 4 spaces or 3 backticks (\`\`\`) should be avoided as Doxygen will interpret these as \\code blocks and try to apply standard syntax colouring, which doesn't work so well for fish examples. Use `\fish..\endfish` blocks instead. - -### Lists - -Standard Markdown list rules apply, but as Doxygen will collapse white space on output, combined with the use of long lines, it's a good idea to include an extra new line between long list items to assist future editing. - -## Special cases - -The following can be used in \\fish blocks to render some fish scenarios. These are mostly used in the tutorial when an interactive situation needs to be displayed. - -### Custom formatting tags - -```html -: These words are underlined. -: autosuggestion. -: Matched items, such as tab completions. -: Matched items searched for, like grep results. -: Render the contents with a preceding backslash. Useful when presenting output. -: This would be shown as an error. (Note eror, not error). -: This text will not be parsed for fish markup. -: This would be rendered as command/script output. -{{ and }}: Required when wanting curly braces in regular expression example. -``` - -### Prompts and cursors - -```html ->_: Display a basic prompt. -~>_: Display a prompt with a the home directory as the current working directory. -___ (3 underscores): Display a cursor. -``` - -### Keyboard shortcuts: @key{} and @cursor_key{} - -Graphical keyboard shortcuts can be defined using the following special commands. These allow for the different text requirements across the html and man pages. The HTML uses CSS to create a keyboard style, whereas the man page would display the key as text. - -- `@key{lable}` - Displays a key with a purely textual lable, such as: 'Tab', 'Page Up', 'Page Down', 'Home', 'End', 'F1', 'F19' and so on. - -- `@key{modifier,lable}` - Displays a keystroke requiring the use of a 'modifier' key, such as 'Control-A', 'Shift-X', 'Alt-Tab' etc. - -- `@key{modifier,entity,lable}` - Displays a keystroke using a graphical entity, such as an arrow symbol for cursor key based shortcuts. - -- `@cursor_key{entity,lable}` - A special case for cursor keys, when no modifier is needed. i.e. `@cursor_key{↑,up}` for the up arrow key. - -Some useful Unicode/HTML5 entities: - -- Up arrow: `↑` -- Down arrow: `↓` -- Left arrow: `←` -- Right arrow `→` -- Shift: `⇧` -- Tab: `⇥` -- Mac option: `⌥` -- Mac command: `⌘` - -## Notes - -### Doxygen - -Tested on: -- Ubuntu 14.04 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git). -- CentOS 6.5 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git). -- Mac OS X 10.9 with Homebrew install Doxygen 1.8.7 and 1.8.8. - -Graphviz was also installed in all the above testing. - -Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive which fixes a multitude of problems in the rendering of the docs. In Doxygen 1.8.7 the list of understood HTML entities was greatly increased. I tested earlier versions and many little issues returned. - -As fish ships with pre-built documentation, I don't see this as an issue. - -### Updated Configure/Makefile - -- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9. -- Makefile has GNU/BSD sed/grep detection. - -### HTML output - -- The output HTML is HTML5 compliant, but should quickly and elegantly degrade on older browsers without losing basic structure. -- The CSS avoids the use or browser specific extensions (i.e. -webkit, -moz etc), using the W3C HTML5 standard instead. -- It's been tested in Chrome 37.0 and Firefox 32.0 on Mac OS X 10.9 (+Safari 7), Windows 8.1 (+Internet Explorer 11) and Ubuntu Desktop 14.04. -- My assumption is basically that if someone cares enough to want to install fish, they'll be keeping a browser current. - -### Man page output - -- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9. -- Output is substantially cleaner. -- Tested in cat, less, more and most pagers using the following fish script: - -``` -function manTest --description 'Test manpage' --argument page - set -l pager - for i in $argv - switch $i - case "-l" - set pager -P '/usr/bin/less -is' - case "-m" - set pager -P '/usr/bin/more -s' - case "-c" - set pager -P '/bin/cat' - end - end - man $pager ~/Projects/OpenSource/fish-shell/share/man/man1/$page.1 -end - -# Assumes 'most' is the default system pager. -# NOT PORTABLE! Paths would be need to be updated on other systems. -``` - -#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths) diff --git a/doc_src/abbr.txt b/doc_src/abbr.txt deleted file mode 100644 index b3dd6896e..000000000 --- a/doc_src/abbr.txt +++ /dev/null @@ -1,83 +0,0 @@ -\section abbr abbr - manage fish abbreviations - -\subsection abbr-synopsis Synopsis -\fish{synopsis} -abbr --add [SCOPE] WORD EXPANSION -abbr --erase word -abbr --rename [SCOPE] OLD_WORD NEW_WORD -abbr --show -abbr --list -abbr --query WORD.. -\endfish - -\subsection abbr-description Description - -`abbr` manages abbreviations - user-defined words that are replaced with longer phrases after they are entered. - -For example, a frequently-run command like `git checkout` can be abbreviated to `gco`. After entering `gco` and pressing @key{Space} or @key{Enter}, the full text `git checkout` will appear in the command line. - -\subsection abbr-options Options - -The following options are available: - -- `-a WORD EXPANSION` or `--add WORD EXPANSION` Adds a new abbreviation, causing WORD to be expanded to PHRASE. - -- `-r OLD_WORD NEW_WORD` or `--rename OLD_WORD NEW_WORD` Renames an abbreviation, from OLD_WORD to NEW_WORD. - -- `-s` or `--show` Show all abbreviations in a manner suitable for export and import. - -- `-l` or `--list` Lists all abbreviated words. - -- `-e WORD` or `--erase WORD` Erase the abbreviation WORD. - -- `-q` or `--query` Return 0 (true) if one of the WORDs is an abbreviation. - -In addition, when adding abbreviations: - -- `-g` or `--global` to use a global variable. -- `-U` or `--universal` to use a universal variable (default). - -See the "Internals" section for more on them. - -\subsection abbr-example Examples - -\fish -abbr -a -g gco git checkout -\endfish -Add a new abbreviation where `gco` will be replaced with `git checkout` global to the current shell. This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish). - -\fish -abbr -a -U l less -\endfish -Add a new abbreviation where `l` will be replaced with `less` universal so all shells. Note that you omit the `-U` since it is the default. - -\fish -abbr -r gco gch -\endfish -Renames an existing abbreviation from `gco` to `gch`. - -\fish -abbr -e gco -\endfish -Erase the `gco` abbreviation. - -\fish -ssh another_host abbr -s | source -\endfish -Import the abbreviations defined on another_host over SSH. - -\subsection abbr-internals Internals -Each abbreviation is stored in its own global or universal variable. The name consists of the prefix `_fish_abbr_` followed by the WORD after being transformed by `string escape style=var`. The WORD cannot contain a space but all other characters are legal. - -Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like `~/.config/fish/config.fish` like this: - -\fish -if status --is-interactive - abbr --add --global first 'echo my first abbreviation' - abbr --add --global second 'echo my second abbreviation' - abbr --add --global gco git checkout - # etcetera -end -\endfish - -You can create abbreviations interactively and they will be visible to other fish sessions if you use the `-U` or `--universal` flag or don't explicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the `-g` or `--global` flag. diff --git a/doc_src/alias.txt b/doc_src/alias.txt deleted file mode 100644 index 606a05ec7..000000000 --- a/doc_src/alias.txt +++ /dev/null @@ -1,41 +0,0 @@ -\section alias alias - create a function - -\subsection alias-synopsis Synopsis -\fish{synopsis} -alias -alias [OPTIONS] NAME DEFINITION -alias [OPTIONS] NAME=DEFINITION -\endfish - -\subsection alias-description Description - -`alias` is a simple wrapper for the `function` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell `alias`. For other uses, it is recommended to define a function. - -`fish` marks functions that have been created by `alias` by including the command used to create them in the function description. You can list `alias`-created functions by running `alias` without arguments. They must be erased using `functions -e`. - -- `NAME` is the name of the alias -- `DEFINITION` is the actual command to execute. The string `$argv` will be appended. - -You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to `alias` just like at the command line, _even inside quoted parts_. - -The following options are available: - -- `-h` or `--help` displays help about using this command. - -- `-s` or `--save` Automatically save the function created by the alias into your fish configuration directory using funcsave. - -\subsection alias-example Example - -The following code will create `rmi`, which runs `rm` with additional arguments on every invocation. - -\fish -alias rmi="rm -i" - -# This is equivalent to entering the following function: -function rmi --wraps rm --description 'alias rmi=rm -i' - rm -i $argv -end - -# This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google": -alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana' -\endfish diff --git a/doc_src/and.txt b/doc_src/and.txt deleted file mode 100644 index 3757847de..000000000 --- a/doc_src/and.txt +++ /dev/null @@ -1,23 +0,0 @@ -\section and and - conditionally execute a command - -\subsection and-synopsis Synopsis -\fish{synopsis} -COMMAND1; and COMMAND2 -\endfish - -\subsection and-description Description - -`and` is used to execute a command if the previous command was successful (returned a status of 0). - -`and` statements may be used as part of the condition in an `if` or `while` block. See the documentation for `if` and `while` for examples. - -`and` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. - -\subsection and-example Example - -The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process. - -\fish -make; and make install; or make clean -\endfish - diff --git a/doc_src/argparse.txt b/doc_src/argparse.txt deleted file mode 100644 index 42da8fdd0..000000000 --- a/doc_src/argparse.txt +++ /dev/null @@ -1,131 +0,0 @@ -\section argparse argparse - parse options passed to a fish script or function - -\subsection argparse-synopsis Synopsis -\fish{synopsis} -argparse [OPTIONS] OPTION_SPEC... -- [ARG...] -\endfish - -\subsection argparse-description Description - -This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal `--`, then the arguments to be parsed (which might also include a literal `--`). More on this in the usage section below. - -Each OPTION_SPEC can be written in the domain specific language described below or created using the companion `fish_opt` command. All OPTION_SPECs must appear after any argparse flags and before the `--` that separates them from the arguments to be parsed. - -Each option that is seen in the ARG list will result in a var name of the form `_flag_X`, where `X` is the short flag letter and the long flag name. The OPTION_SPEC always requires a short flag even if it can't be used. So there will always be `_flag_X` var set using the short flag letter if the corresponding short or long flag is seen. The long flag name var (e.g., `_flag_help`) will only be defined, obviously, if the OPTION_SPEC includes a long flag name. - -For example `_flag_h` and `_flag_help` if `-h` or `--help` is seen. The var will be set with local scope (i.e., as if the script had done `set -l _flag_X`). If the flag is a boolean (that is, does not have an associated value) the values are the short and long flags seen. If the option is not a boolean flag the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag var will not be set. - -\subsection argparse-options Options - -The following `argparse` options are available. They must appear before all OPTION_SPECs: - -- `-n` or `--name` is the command name to insert into any error messages. If you don't provide this value `argparse` will be used. - -- `-x` or `--exclusive` should be followed by a comma separated list of short of long options that are mutually exclusive. You can use this option more than once to define multiple sets of mutually exclusive options. - -- `-N` or `--min-args` is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero. - -- `-X` or `--max-args` is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity. - -- `-s` or `--stop-nonopt` causes scanning the arguments to stop as soon as the first non-option argument is seen. Using this arg is equivalent to calling the C function `getopt_long()` with the short options starting with a `+` symbol. This is sometimes known as "POSIXLY CORRECT". If this flag is not used then arguments are reordered (i.e., permuted) so that all non-option arguments are moved after option arguments. This mode has several uses but the main one is to implement a command that has subcommands. - -- `-h` or `--help` displays help about using this command. - -\subsection argparse-usage Usage - -Using this command involves passing two sets of arguments separated by `--`. The first set consists of one or more option specifications (`OPTION_SPEC` above) and options that modify the behavior of `argparse`. These must be listed before the `--` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the `--` argument and can be empty. More about this below but here is a simple example that might be used in a function named `my_function`: - -\fish -argparse --name=my_function 'h/help' 'n/name=' -- $argv -or return -\endfish - -If `$argv` is empty then there is nothing to parse and `argparse` returns zero to indicate success. If `$argv` is not empty then it is checked for flags `-h`, `--help`, `-n` and `--name`. If they are found they are removed from the arguments and local variables (more on this below) are set so the script can determine which options were seen. Assuming `$argv` doesn't have any errors, such as a missing mandatory value for an option, then `argparse` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one. - -The `--` argument is required. You do not have to include any arguments after the `--` but you must include the `--`. For example, this is acceptable: - -\fish -set -l argv -argparse 'h/help' 'n/name' -- $argv -\endfish - -But this is not: - -\fish -set -l argv -argparse 'h/help' 'n/name' $argv -\endfish - -The first `--` seen is what allows the `argparse` command to reliably separate the option specifications from the command arguments. - -\subsection argparse-option-specs Option Specifications - -Each option specification is a string composed of - -- A short flag letter (which is mandatory). It must be an alphanumeric or "#". The "#" character is special and means that a flag of the form `-123` is valid. The short flag "#" must be followed by "-" (since the short name isn't otherwise valid since `_flag_#` is not a valid var name) and must be followed by a long flag name with no modifiers. - -- A `/` if the short flag can be used by someone invoking your command else `-` if it should not be exposed as a valid short flag. If there is no long flag name these characters should be omitted. You can also specify a '#' to indicate the short and long flag names can be used and the value can be specified as an implicit int; i.e., a flag of the form `-NNN`. - -- A long flag name which is optional. If not present then only the short flag letter can be used. - -- Nothing if the flag is a boolean that takes no argument or is an implicit int flag, else - -- `=` if it requires a value and only the last instance of the flag is saved, else - -- `=?` it takes an optional value and only the last instance of the flag is saved, else - -- `=+` if it requires a value and each instance of the flag is saved. - -- Optionally a `!` followed by fish script to validate the value. Typically this will be a function to run. If the return status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on Flag Value Validation for more information. - -See the `fish_opt` command for a friendlier but more verbose way to create option specifications. - -In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set. - -\subsection argparse-validation Flag Value Validation - -It is common to want to validate the the value provided for an option satisfies some criteria. For example, that it is a valid integer within a specific range. You can always do this after `argparse` returns but you can also request that `argparse` perform the validation by executing arbitrary fish script. To do so simply append an `!` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined: - -- `_argparse_cmd` will be set to the value of the value of the `argparse --name` value. - -- `_flag_name` will be set to the short or long flag that being processed. - -- `_flag_value` will be set to the value associated with the flag being processed. - -If you do this via a function it should be defined with the `--no-scope-shadowing` flag. Otherwise it won't have access to those variables. - -The script should write any error messages to stdout, not stderr. It should return a status of zero if the flag value is valid otherwise a non-zero status to indicate it is invalid. - -Fish ships with a `_validate_int` function that accepts a `--min` and `--max` flag. Let's say your command accepts a `-m` or `--max` flag and the minimum allowable value is zero and the maximum is 5. You would define the option like this: `m/max=!_validate_int --min 0 --max 5`. The default if you just call `_validate_int` without those flags is to simply check that the value is a valid integer with no limits on the min or max value allowed. - -\subsection argparse-optspec-examples Example OPTION_SPECs - -Some OPTION_SPEC examples: - -- `h/help` means that both `-h` and `--help` are valid. The flag is a boolean and can be used more than once. If either flag is used then `_flag_h` and `_flag_help` will be set to the count of how many times either flag was seen. - -- `h-help` means that only `--help` is valid. The flag is a boolean and can be used more than once. If the long flag is used then `_flag_h` and `_flag_help` will be set to the count of how many times the long flag was seen. - -- `n/name=` means that both `-n` and `--name` are valid. It requires a value and can be used at most once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the single mandatory value associated with the flag. - -- `n/name=?` means that both `-n` and `--name` are valid. It accepts an optional value and can be used at most once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the value associated with the flag if one was provided else it will be set with no values. - -- `n-name=+` means that only `--name` is valid. It requires a value and can be used more than once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the values associated with each occurrence of the flag. - -- `x` means that only `-x` is valid. It is a boolean can can be used more than once. If it is seen then `_flag_x` will be set to the count of how many times the flag was seen. - -- `x=`, `x=?`, and `x=+` are similar to the n/name examples above but there is no long flag alternative to the short flag `-x`. - -- `x-` is not valid since there is no long flag name and therefore the short flag, `-x`, has to be usable. - -- `#-max` means that flags matching the regex "^--?\d+$" are valid. When seen they are assigned to the variable `_flag_max`. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example `head -3 /a/file` to emit only the first three lines of /a/file. - -- `n#max` means that flags matching the regex "^--?\d+$" are valid. When seen they are assigned to the variables `_flag_n` and `_flag_max`. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example `head -3 /a/file` to emit only the first three lines of /a/file. You can also specify the value using either flag: `-n NNN` or `--max NNN` in this example. - -After parsing the arguments the `argv` var is set with local scope to any values not already consumed during flag processing. If there are not unbound values the var is set but `count $argv` will be zero. - -If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr. - -\subsection argparse-notes Notes - -Prior to the addition of this builtin command in the 2.7.0 release there were two main ways to parse the arguments passed to a fish script or function. One way was to use the OS provided `getopt` command. The problem with that is that the GNU and BSD implementations are not compatible. Which makes using that external command difficult other than in trivial situations. The other way is to iterate over `$argv` and use the fish `switch` statement to decide how to handle the argument. That, however, involves a huge amount of boilerplate code. It is also borderline impossible to implement the same behavior as builtin commands. diff --git a/doc_src/ascii_fish.png b/doc_src/ascii_fish.png deleted file mode 100644 index 390fe6f50846366cbd0e5d0431f3408434ddecc7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 12062 zcmX9^c{o)6_qPl)7-sCoI+MuG*h$QShE%qYL}L%x$e3KA`^)gJ0aPZA=#3M z%Gi^N5Jh}_e!oBNz0Y%>=f2Ll&vVXspYwX16w6EJxj98SnV6Wk&2YxnC(ntK>n@1> zLp~3WjId2`)D6eTGRo!(-Q)K*inootmXBU- z9=&+>;1^%h4f*>^@6<~TV|aO5eyy^^OjPY&v02}2I;W!dL_t2c%pUj3-9x0Cd*1qE zUCQW%KGz1KlRx#>z;c?*K4z zjcmbfP;Y>HsW69QVa@`p;Qi;7wMWMm>0Fou-W)CEDJkOA74w#qfu=D~@bx^jPol?k zYS?t5)VTQFEsZJIt3c_$Zmd&!}ll2GZ}sRTJ+^mtbpV3F*4m5ht_g(^Zl7NWr>ta z%3Rw!F#-vGyFQ&WG`2OqwHGv|dIn^)APE{O5Vl+0dCB;Km-xJVY-QQcZ-$6DR95Oy zXdsUPV#j*cLj2rg-gHP_-03=IjfG0XKP17*d?I*lkdmr+^*cd8=YBx?fS7mI8zdY5 z#e+~V>Uz4)cYZZksig#j;W0b#q(tK*m>iFoN^ zs#vz30fPzHp7i7v+Q&2@oBFk(GpqP?)?(s;=V-@2PV>{+>ai&rlxUkNYUj7Q;(ltw1^bi zvi#g)pk3fg(lv&IxwF%Ka9FTpXH1L})5C?cPS%(+@=|@`G09n6^XFnHp)m=2TO2|Q zrfV@DsSh^(x%t#V++XU;zJK_weB;}IK2`DOIcxFzGdmaA)!-X42qep`w3ul zA1J_r;QbcJ=3eOiTbc1BR<%$#fr)qdmz(<5)*TKW61ET9FuqVxg9J;a&?1;em-G0wzfPXX-WB=r$BYd(=p+ies!3g|krhLKG@k!Z4UjbOMi~F1+Bn$u|{GyM6m2CLzOT2ZjG9#y5quS2i$q3L{o2q z=L~2<22d%^sIZ_q{%Xn}=X(!LS!wz$6}n1xIe8&5!ah?9dmIK6XOwXo7L4&PcH z-&)>~%b96e1b9?gIjwe$IQljl z9%e{1Z!Ww+<5<#<=BF09 z>m2>t-gmN~_qxtMuZMxqSB(-)0xuZ}`6B=BY;4v+bM%z9%nal8Z3Qf{3`F!Hu46*E zB{GgB%6G^;VajHjX1pDyRU zJ*e+4&C1MBF4WVcwZghse;O58E>9*#7$x^5rIbHf=KU`>!U(}%x!Q^;aFYep%2@9f zwAaZ@?5G(SbT%>iM$wUBn>--s?;g9$o(3^Z4)-Dm^a5V!;FLN6jj?)~7ybBRvhoe; z=Pr)J%zuEd0_Xw^wdxd(@<-w@^UJ2Nw$(T^;F+I;|A=8s$s-1PrE;8Uj0(wCFy6zU zcn1zBDuxB+b4-Lm{ngQ}lR{;*m`}W?1@P57+@BNE|L*e(*)3`fqZVBy6&{jmTfi1- zx@^w{Nh1Ts(6~mpUt+{&5)`8=v;LPfh$Ba1jn+VXz6-gPsq* zr9Wys)%&JESjYk=!uFN{#Dm%ga`%Z}zKI*IqKT7t;ITcUM~{(Q0T0E6?U`L+CRDw~ z7`EVL72JzJfuij#iZcb@vT?5;&mUq;fQJ5kwdp(jYz--nIs+OKxsyj=N6Fl^#{G5sEDKH_kX1KjAiK1Z5-s+*6U>Xa8anB^W$|#A`*uSGIdR=#w`%y`c%tz#w z$;2t=Ry50s8(%14t2+uz2xeSUN;GocFNGEN*6yrLT3MQTGzEVqdsmc9NWUxCoa)y4 z&%ke5+Zt)ouz8P{q7f`>>=0wayN zVr7N3Y$y2hjvH7Rxm-ua=_m}(;ImSje9BJexm31x~8D=iDHkqne`kgnnFNxTKH{ zXO6wF&mCQ=CNO9z>6GbF!K}A`y@Y>45Gj6zQ!Q)9GutAz8O<{9LGKbPe;pyXd80Z# zV$Egf+wk6bb8gc}`p7V?Pv|?wR0rpwCf*3ATpQmrcs|oo$%Ock*@8>(Gsnvrc8fF+ z(w}X~J9l$ia!j$Z!XfLfY$^n&KG^AbV9WwzK9=c#mrIZoxS=xNcun)DQ-gXDWZ22! zAi@pHTF`ND2xA6(wVzB7kEs=@hud!fD-pj-Ledl!tA5mrqvLtQ z{JCgu(u=VUQ2V06k56abgWGn8BGi%dOS6J)bwY`rUy!G`J>dI2!d(?9znXqeSmM?9 z{{7>A52qB=1WGL_9Ko-XZ{di3m|Dr(Sd%rO4OC=Bf=ZYCPJ+14Lc#$2iuu*yrYqYe zcNZ6b=oB_=^q<)<+wxi2>^-;~EB;==*Lm8mUZ)Qd!BJgmSdL&7Loz>fL-7LSp^9oe z!O4Ay^aQ6qsnb%!{g!k*e1dk$n*9w@Q~~gvn&c0SIf*ufqfQY}ToYW`Er65+ef7iX z?w`<0T0I{7c^@O4g5zPsxd#UFT{nff&WM3?Y%!yZaC#lIJCj6|Fy{ ze98+g%o3t-m_yOWeml%GY(*$^H|s;5VMa z(dBrlDXy8qSqPTT@sZ&=L)ik0wLLGKlaxw&F{#KGEErF1+eChrC!~D}Uo@fuZ%ea= zjad5X47sIPhORp$$BGxz>hOB#KkR3N0N63X3!5_949otzW?zc(ggzxt&_1-Jblw(k zep3sijC1d~R@L(7=YgwT!PX+-^ZxWJb7&Top6Uwrd(bR5jUmh?n!6VjA$nZGIYi@4 zw9_ThHqo&;gl4y%^7n!^xtM{0UJ8F1s-D*zyMqA`c{vd&u2bzW(w(OdBVG_)rVhvG z@9IOkdD9igcs_%g1e=;rs)^XX!M2F!#-RVQkHR;ffjdK4|j)A$AQ~5P;BKP58>#Ah5S_i?t5ztqS-I?ka=G^=el5i z)R%(k9J_DN$|4G#X>(VNOPml~Sdjnd-m|BQ?4)<46AGBX8G%{W?;EyS#UAY25%0fv zthY_+EA<9H@A-&nV!e!JTO5i*CeGK%{{reB#l*nAW#lnaeq8W*EvwSFQm{XH$&;vY zExG}7dl((xp!WSc=lC)%$p80i)w!ttxr zzs!eQT7)PG{lX2l;C)!is=S31zW*vY!6riMD8$3~BW}%g;7b^DIi~6n#5!cdlrvO& zMZib0zvv0Pu?HVTyHDkRXj6D`2NK+>&+;gjTV0SV8`{PIB4F~Hb+H!7CanADVd*~) z@~p?texrtPP*1-iVvdZZUPiz&*-7fCd z)cE#l^8@0^1|0b$IPgM`D5$(=UUg8Z5&r8jv^6RF*+?4Gv1>3T8H-M#Sj~3Z0C7Wnwl0*Tb zU_=!Z!(fw&z_x_KSRn_OVg;>)9r^FBzxnzA5^VR^njU$>=F<{wLqH%n)cBBz7^*jV zAUoVYfI~++rHw>Lya|$7FE#qekZ%vynhoVX`zI<%*F3SRw2r2c^+hUVOY3O~cNFc+ z=K=E_vN?|G-)nceliQj%KNa?;ZFWx5Sg@O^JD^!;h@?05Xp958C*U&@`0uPI>@W1Q z(IE7QiJrMCk<3Kz0zO6n1BkW-@JMX9K^&Y22gc_R&H1)5LBexzL4wadTM@0TWC)(# zs5bj{s*8ZC`;sRoDE7j&mT`Xmmam6Xt+fiRT?N>e-+#^LMPL0w{t~|aufo&P z8EKw-Lz(LZN6W}tCo#Jql5OC8lEE|gHRMz;wMz*; z*m8J$>HLppeB4O&lY-cvgyj+B1W@B0qkGKDSU&pj0}o%1(I@9e=-!;#L+$( z9u=H=fCb7sjUFR180q>ueMS!#nXRYZ?$$rw+o4W5t(^pKKR(^YthdvnkVEks(kN&m zCL9BUiwa>k{<0sP@Q&p|zZXQ;{OZ~v+l<_z*iJ*P$Uy$1rU~pi2D+zq>sHgbOK)tb zWSQ`lC`D-!98JBdd0QmIU6MjWeHwbnXLCCVdv&=l^xFzOT&mnD5H$5%_B&H@z(R{LsUGR7r zM+U1>udMsLW>rTsaf$uw#SN^Qdx(r=KgoLyWNqTt7fZdUC*FCMT6A^gpBNt;JYaT+ z|9F|NEC6J6GnzWq+fy>|emYH*dJzyl??Y$UtdxHyW?oKH=|P#Ec8~k(6uP|0=kbg*tZ5)C>l7 zP7;%5M+0BBghfbVu7qNM4d=axlX=iT4-|1LTlP0jFR8I_Ljf}l-Ix4bt_l<1bUnBi z!@(6&3-}42=ALM|*As4VQd-}Rv}jLLDDdQ_)mm;m^==D(=3xbMk%>Ps^jsW`QppK( zbw_4q_kB0`+(?!9?y~j!7F|QQWA@r+_AT=z6F@6^s3=;4EYrre%m(!QZL;?d8e&SY zb&l^&I($t%N`j&>7!*G2u}NKi!fi=o4U`db82aSBxR}%;wlUnjO6BSGEIi~s-b9<&K>UK&_hJg+ zu>M__{n&xO}|F@_>M28nM5;s2l&j~VHp{vk4sjC^>^P{*;ns#5v<(a9?0_Hhafk3js0R+%nrFjnMCrp9R8H zM*GvoJOGu*a}#2KuYw^O>%Z4h-$0|R*iu}~MS$N_&z$MKm;l$N@2hsrP;}|=K)n#9 zSGr8q#0UHPntm%G=4dtn!s|qLB>-=kSHwsm?@831H{6qIATfbQVUdn$W>jG84VrS! zZ53ipta5?Bk6IW_;d$dh^yN0Fi_c7NwT=l$8 zRE`=QN^9Zz_BF*EP0lpD`|j;eV_!OgGk%e~BEhiBl*M)kNmt_&ixdPWg7ZJGF%@8W z-lz%un#cOdS!S1um7T5OSVk;59;SSsPR2$6-_|f4SRD9o7{5C)@a4vf`noP#$>#$S zRD`zhj{4nZDJ+jiEv&wT1=MLC^OccxKk;94f6u5ouo}&?hv!nj@Z7CEa~vY0q9Om9 z`8L{AW(RxODdky^{HbwRtVMLdj`32GWSMHMpdnS-BI`yY<=rdKa?wXfcYdOT8Z%wT zNU3W>8# zs@K;2oADCwvV&>Bn*bj86qdSB%lZ;U&dj8LeQmfsrr5VAl}_YblQ|^ILC~pvaZbyO z)%>(AYEP*HNuB!EV%Tf{i`bAA-hB9W?(+w*<0N4u zmnEK+=TZ4IX@q)rrq^B2-K*(^e(28EM0Th<8F%@Sj4kTZ4cfUScjve5UW(6AbZTYc zY>H1NZ<~7g>T5RjQ?(Kh6x*Wu`=8Gc^9zO4e|K2F$I?^ACcD`iDBvOy{-1q{lE?iIL zB~9d(jJ=<#xe9a4@NTY2llb}IXIWeditE|8FFB7f&hu9veXH%&hW5TL8PZVKn--Yj z(J@`TX-gg%_R!vbo|tOs><+&0{KA#Dox@!zSzh2vqW`MB1MJ-)zS^s}2 zDaep4Ln)o2q5B^q@gtwVhU>53k>&GYi~OM&t^J%~_?1hrtb7pB?{hzMj+PEGt_UTu zq$It_y86e-x0()cRM40E*CIwLas)x$sO!Bqc~bo|$Tyn>!9tu2I?xQY}e zP%p9`rmj$Xf(1Gc^A=B_ck&G7Z{TA0pv^Hd3)0#Iy zIgd>csL}RMxMR9JbD|9Q@iu-F<}7f3>`fFld?hpt_#^SxhzGeIQmVM5#{aX6tFA?= z5cWb5$h=={9($StGD-{uLfUy!N6q%>6I` zcm53JW?0=;fAs!z&suQ2-+49nyTsTv`)(p2&$sMc1v3odDiznSRMDKD`Xd%c_Uo>Z z_<#!cJpJQ(1X}wiUgMBf-z+Jl9t0J#E7fZ!Ct(3!1BmXtWpRL;aJ2p{&PYgC_w43@ zFngt56N0-=KI7gAvy$G)LZ?Z@VPomgp2h6)``bZuJm*U8B>az?tTQQHR+pV?6unCN zy7G`DZt80F`(GLyyAm02{vzE|(3voTV96L~3VVCdXeB!6ogM|KG(`JgsHZ^InrI() ze``D8i&ncXAEp1ybG32m?HKj^zV*HqR)nDBM+{)AcR=A0YxmaYp;b!wlZdJuMoto; z31_xgCPv(-e;E*2J6{Z0U8Jk@pI3K?w7XYTfMHVln;`J55@JyPS%D)$EA^s4_`+2> z-arV=QxsTW)n=Eutj?IGcp)esvU!g0h?J@Cs}`VTl3;(Lk|%OnsS>4OABtm;?GSe_ zQ;DCXbYujO(04fZ1}=aIH~0xvurM!uzP;$xzq<8DfDiafdtcl|ICbJg4!YO%&zoB> zw3msFfRUgaGy4p5_dCftjj+6b2#SCKVeO94={y1uCByyroZ+0!;O#5M1rYbOF|65V z3z36hsjE_SsLLYI1*FBxBX}mnu!EV)Z^e!I+nhvEA@ zG2-){Aw$W)0JYv#)M*d<6^Fd%#tGlaqiDj{n<-QYf*kzo5lswWmx1!F<4KGaHm)Jvx%R)oo zl)^3G(;@^;>W1p21x~sMCDb90o#Asx6oHVymHVO{y7xcC5cl8^M>yBHVA$zgSpN~Y zE~U#VJxLAn4N>?$kMkbj>+(B=>Sy9&gsb>v!e8fKyAA}EMy zb5$4*Oq~@39G47s$i$Dq8n7o~gf_2k!b^l3vY2Rq^!=>l#KW-Oz-ZCCq@Hc!RY*(f zcS|W_oOORBzo4emKfntiHM~cb9LRjjL#E~XFmz*}i{#2e+(~xHvP2u)o69qsxIE82 zGe>@rOg3m<0G}*%xJ0}e@459zsbUiLLvH#5Zy9R1E0jLia7?b40}gV(%Z-q#gAroA z(=wWoqxZP`s(IqDUUIpvK_Ka0fiIdw7U2}Hng_*lljDk7-Ts;+ak~XZ2%u8Y-G+xE zan4$9VoP^v34CXq`@o7VScI8t@MPYzOR1IGg_oW^>issIstIWf? zt-ym=YSq9fF41qu?d;#EwR@iPT69K-1Ib#_bi1`1qXTM(KBA_)JQq`aQK@p1GVQA0 zsV(|}OGqDW%5)!pYDrBj_I{o(biIdE;ROT8W z5=}S5Snj2+$1C7BD@hiVJb(Ct!g*?&+NhiS*v2Lv;KADa+xym^c-ikl$1ff1cVu%K zPd6-_unvlKvl)VtKkpc6#E3lXV13kI1=LwJydwd32GBNjmBG#WAh395J+BNN_%<#rR-M_2YbU8}Ry>%1} z7IYB?>Oq^Sz0XY$&tB}**<<}ay1d(XA1BWOhxqqnawz*VKa31zj}mrG{r=yp@+W4* z5r%$ff_aVZWUpm;Y1#UbhQGd3yqFq=*G zab6*AFvVnyn)Eua~P6{PiVK#M9i@mEhhfFT#$d`~!bB>?K$`rHIBMkr-&+9r^n`&=((s0*mn(yNcpKj|kJ1&Y@*(q1A3g4O#fqJs*4zRD4O<&eBr&)Ogn z&yaJ(%8^D-7H|#}4Vlqjvu}Q=&ba)xBu3#K7-NFMb$w}mRYP0~{*=_G_~tPgV>?L6 zr!9M}WgO}2s~_1VXPEs!hTu{pSHgWtR3}Ct1n z-5Jx}14HO=&%9P0J6EGS@WfIH+0K&;jq@f(-x%l5pp<9@>9MN5u4O;4lvH;fu(L(8 zy~_(w`C!d6KMOw_@^t6g32|}+HTIrbWYp*UY)dV=`p)$ceDig1)wl3cCHDw7ElH9A zQjh}(h0KH|F5{V9z&sNnuK_b#{|vhk#u!r<2a%Mca-@`#$~%p*kkhE}l`BWLwS6`q zgtR{oxG!j{k3re=@@M~TEKRC#5-o}rosCi2x7}DjD7Bx=K0$*v)Yk59LFz@8qkeb# zh@V|ZCvTaoE`cr2U39x|*|AqPs}z1le;FbRT_KWi%3|&x6Q59#cwEfEMx9-u=c&r+n59Nu;N8c-$J48?t#pAPgABT z!BngVOPl;Tg~qd?KGt*RH(u3#$x*%^2HyfKKW*vX_Xg#GaECL_ z$=_J+mzH_j@BZxNbI1!NUnfNfr=aK&ShNxXedz`06Ek@>$4I=PYjMsxLFY-nY8r@xJr%Tql{W%oq<^!7Y zEk3Ok9=Kppqq3?O7ZPRem;_rN{OpP==-^!?|3h@MNMTxkT(ZrjBy2UxKquL6%}Sm!BC#pfqGb&T{0 z6O2jM-1up6=dt`6LWZ!dxWz5kD-~)dDPw}y7XDX+aDUmS;j^dhX|uKI6XovX23jb% z34Ib|6u7<{*Uz7#gMrQ_Tu0AZ#AH6v(^B#k^IOZ@o98Ne`*BGArAGGIgjmHkILXSm zSZdVcqLa_5hIaE2h52!V4&8M8LZfu=YLnaA;dLA4cwlh?G_`V#ho-Vpg2w{}m!mk( zXS<7;JtOMr4j*5()DGnW@ZJ%w`2fbnu%SJvt{O^y(kQ`O=vLNi!7Vw*p1+It?**R5 zkRwzsFE-D-waYs>%P|K$VA3$4I>|FHDGaKx$VA4_ zjZnVLvt(4iv~EUR^W=X4IMrKwCEo^n*njg%Je|rh>>tB3Gb8I>`b+TiysV$`O}a=j z_&hbdM5SpF2|7+nV&50=h4(J%fXV4^@Qia{WQK};@oqwrKNXmvcl~dyNuc8i&eirB zpbLtpS{Osc)UuPr&snptqxS_mN(`GAR-nCZjPx){Kha_1_71Kw5a7GndNZ`;*K;nV z9Rk>eUNKNH8_@RpQ%~`?=uItvDm_B516s0n2;?Z|fjC3i7eN#7Hs7<2vt;0Rbloma z5#D=4m5er(79YS^X#eNW6%$!WLb`JVTNn~~PJg%ezUTYd;$q2MV^le^CQv3Ip!cRl zLZFl+R&1l+Q#Onhv800wnkGcUcY3YTje+9*Pe9#5N~RLSXdyl|KFau@HYiBKeTR^Q zZ0^xqNqe)ad>_Gt0Y2z;sS&xc57pN~8WIWQM!?`Hxicc{F6aBu%E@6yJr>cj-}4(j z@xcCY@u`7lp#a8}2i->d{27S3OtAQXQL`|{<7BTyDJJCxJumZC1;OE6o~nwyy|^(y z9fvxv`FL0sN|YPmaD)AQe5SwuuOdy72EfU;J9u?@WO-JJQDReAllSKqcQ) ziEtv5X8&?B+0Unh%Nkx7yp|vY3XD18opW*M`J!SUubGsJQ}shJ<(#jrU=pm;j{qP{ zBu?i(lmCmd<=cN@hN~PX^8@!b+US1Ytvm&CN1Y14k~C@ivF&7rh$ptY+)aIJ-|N#HAZxGtmCGQpF5+tVB_IcQnu@Wf43gC+LC zu-dDcu+8AP=&ypHy;H1L)WBCkCMFIdT(GbpCY}Fq{mL1ab4ckg@pzTG8fHv@gF~7G zJ=6(uJ?nbKkN*H}W_FB8s4L8$(EYO&z%DTzH}3l-!Y7StdpM=zy6`iz2;RCa473eF lK><+O9Q%^Wv^yK|8wYPZ1aw;RPxjuK%uFsBS7B}t{|8Gk0IvW5 diff --git a/doc_src/begin.txt b/doc_src/begin.txt deleted file mode 100644 index dd008bda9..000000000 --- a/doc_src/begin.txt +++ /dev/null @@ -1,46 +0,0 @@ -\section begin begin - start a new block of code - -\subsection begin-synopsis Synopsis -\fish{synopsis} -begin; [COMMANDS...;] end -\endfish - -\subsection begin-description Description - -`begin` is used to create a new block of code. - -A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`. - -The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`. - -`begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command. - - -\subsection begin-example Example - -The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends. - -\fish -begin - set -l PIRATE Yarrr - - ... -end - -echo $PIRATE -# This will not output anything, since the PIRATE variable -# went out of scope at the end of the block -\endfish - -In the following code, all output is redirected to the file out.html. - -\fish -begin - echo $xml_header - echo $html_header - if test -e $file - ... - end - ... -end > out.html -\endfish diff --git a/doc_src/bg.txt b/doc_src/bg.txt deleted file mode 100644 index 13733f58e..000000000 --- a/doc_src/bg.txt +++ /dev/null @@ -1,25 +0,0 @@ -\section bg bg - send jobs to background - -\subsection bg-synopsis Synopsis -\fish{synopsis} -bg [PID...] -\endfish - -\subsection bg-description Description - -`bg` sends jobs to the background, resuming them if they are stopped. - -A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. - -When at least one of the arguments isn't a valid job specifier (i.e. PID), -`bg` will print an error without backgrounding anything. - -When all arguments are valid job specifiers, bg will background all matching jobs that exist. - -\subsection bg-example Example - -`bg 123 456 789` will background 123, 456 and 789. - -If only 123 and 789 exist, it will still background them and print an error about 456. - -`bg 123 banana` or `bg banana 123` will complain that "banana" is not a valid job specifier. diff --git a/doc_src/bind.txt b/doc_src/bind.txt deleted file mode 100644 index d778cd31e..000000000 --- a/doc_src/bind.txt +++ /dev/null @@ -1,170 +0,0 @@ -\section bind bind - handle fish key bindings - -\subsection bind-synopsis Synopsis -\fish{synopsis} -bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] - [--preset | --user] - [(-s | --silent)] [(-k | --key)] SEQUENCE COMMAND [COMMAND...] -bind [(-M | --mode) MODE] [(-k | --key)] [--preset] [--user] SEQUENCE -bind (-K | --key-names) [(-a | --all)] [--preset] [--user] -bind (-f | --function-names) -bind (-L | --list-modes) -bind (-e | --erase) [(-M | --mode) MODE] - [--preset] [--user] - (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...]) -\endfish - -\subsection bind-description Description - -`bind` adds a binding for the specified key sequence to the specified command. - -SEQUENCE is the character sequence to bind to. These should be written as fish escape sequences. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{Control,X} (^X) can be written as `\cx`. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not `fish`. - -The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable. - -If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `terminfo(5)` for more information, or use `bind --key-names` for a list of all available named keys.) If used in conjunction with the `-s` switch, `bind` will silently ignore bindings to named keys that are not found in termcap for the current `$TERMINAL`, otherwise a warning is emitted. - -`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions. - -When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well. - -If a script produces output, it should finish by calling `commandline -f repaint` to tell fish that a repaint is in order. - -When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed. Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from `bind -f`) or all shell script commands (i.e., valid fish script). - -If no `SEQUENCE` is provided, all bindings (or just the bindings in the specified `MODE`) are printed. If `SEQUENCE` is provided without `COMMAND`, just the binding matching that sequence is printed. - -To save custom keybindings, put the `bind` statements into config.fish. Alternatively, fish also automatically executes a function called `fish_user_key_bindings` if it exists. - -Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the `$fish_bind_mode` variable. - -The following parameters are available: - -- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence - -- `-K` or `--key-names` Display a list of available key names. Specifying `-a` or `--all` includes keys that don't have a known mapping - -- `-f` or `--function-names` Display a list of available input functions - -- `-L` or `--list-modes` Display a list of defined bind modes - -- `-M MODE` or `--mode MODE` Specify a bind mode that the bind is used in. Defaults to "default" - -- `-m NEW_MODE` or `--sets-mode NEW_MODE` Change the current mode to `NEW_MODE` after this binding is executed - -- `-e` or `--erase` Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying `-a` or `--all` with `-M` or `--mode` erases all binds in the given mode regardless of sequence. Specifying `-a` or `--all` without `-M` or `--mode` erases all binds in all modes regardless of sequence. - -- `-a` or `--all` See `--erase` and `--key-names` - -- `--preset` and `--user` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all `bind` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time. `--preset` should only be used in full binding sets (like when working on `fish_vi_key_bindings`). - -\subsection bind-functions Special input functions -The following special input functions are available: - -- `accept-autosuggestion`, accept the current autosuggestion completely - -- `backward-char`, moves one character to the left - -- `backward-bigword`, move one whitespace-delimited word to the left - -- `backward-delete-char`, deletes one character of input to the left of the cursor - -- `backward-kill-bigword`, move the whitespace-delimited word to the left of the cursor to the killring - -- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring - -- `backward-kill-path-component`, move one path component to the left of the cursor (everything from the last "/" or whitespace exclusive) to the killring - -- `backward-kill-word`, move the word to the left of the cursor to the killring - -- `backward-word`, move one word to the left - -- `beginning-of-buffer`, moves to the beginning of the buffer, i.e. the start of the first line - -- `beginning-of-history`, move to the beginning of the history - -- `beginning-of-line`, move to the beginning of the line - -- `begin-selection`, start selecting text - -- `capitalize-word`, make the current word begin with a capital letter - -- `complete`, guess the remainder of the current token - -- `complete-and-search`, invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager) - -- `delete-char`, delete one character to the right of the cursor - -- `downcase-word`, make the current word lowercase - -- `end-of-buffer`, moves to the end of the buffer, i.e. the end of the first line - -- `end-of-history`, move to the end of the history - -- `end-of-line`, move to the end of the line - -- `end-selection`, end selecting text - -- `forward-bigword`, move one whitespace-delimited word to the right - -- `forward-char`, move one character to the right - -- `forward-word`, move one word to the right - -- `history-search-backward`, search the history for the previous match - -- `history-search-forward`, search the history for the next match - -- `kill-bigword`, move the next whitespace-delimited word to the killring - -- `kill-line`, move everything from the cursor to the end of the line to the killring - -- `kill-selection`, move the selected text to the killring - -- `kill-whole-line`, move the line to the killring - -- `kill-word`, move the next word to the killring - -- `pager-toggle-search`, toggles the search field if the completions pager is visible. - -- `suppress-autosuggestion`, remove the current autosuggestion - -- `swap-selection-start-stop`, go to the other end of the highlighted text without changing the selection - -- `transpose-chars`, transpose two characters to the left of the cursor - -- `transpose-words`, transpose two words to the left of the cursor - -- `upcase-word`, make the current word uppercase - -- `yank`, insert the latest entry of the killring into the buffer - -- `yank-pop`, rotate to the previous entry of the killring - - -\subsection bind-example Examples - -\fish -bind \\cd 'exit' -\endfish -Causes `fish` to exit when @key{Control,D} is pressed. - -\fish -bind -k ppage history-search-backward -\endfish -Performs a history search when the @key{Page Up} key is pressed. - -\fish -set -g fish_key_bindings fish_vi_key_bindings -bind -M insert \\cc kill-whole-line force-repaint -\endfish -Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line. - - -\subsection special-case-escape Special Case: The escape Character - -The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character. - -fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the `fish_escape_delay_ms` variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session. - -Note: fish 2.2.0 and earlier used a default of 10 milliseconds, and provided no way to configure it. That effectively made it impossible to use escape as a meta key. diff --git a/doc_src/block.txt b/doc_src/block.txt deleted file mode 100644 index 9fbbade83..000000000 --- a/doc_src/block.txt +++ /dev/null @@ -1,46 +0,0 @@ -\section block block - temporarily block delivery of events - -\subsection block-synopsis Synopsis -\fish{synopsis} -block [OPTIONS...] -\endfish - -\subsection block-description Description - -`block` prevents events triggered by `fish` or the `emit` command from being delivered and acted upon while the block is in place. - -In functions, `block` can be useful while performing work that should not be interrupted by the shell. - -The block can be removed. Any events which triggered while the block was in place will then be delivered. - -Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for` - -The following parameters are available: - -- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope - -- `-g` or `--global` Never automatically release the lock - -- `-e` or `--erase` Release global block - - -\subsection block-example Example - -\fish -# Create a function that listens for events -function --on-event foo foo; echo 'foo fired'; end - -# Block the delivery of events -block -g - -emit foo -# No output will be produced - -block -e -# 'foo fired' will now be printed -\endfish - - -\subsection block-notes Notes - -Note that events are only received from the current fish process as there is no way to send events from one fish process to another. diff --git a/doc_src/break.txt b/doc_src/break.txt deleted file mode 100644 index 32672c09f..000000000 --- a/doc_src/break.txt +++ /dev/null @@ -1,25 +0,0 @@ -\section break break - stop the current inner loop - -\subsection break-synopsis Synopsis -\fish{synopsis} -LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end -\endfish - -\subsection break-description Description - -`break` halts a currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement. - -There are no parameters for `break`. - - -\subsection break-example Example -The following code searches all .c files for "smurf", and halts at the first occurrence. - -\fish -for i in *.c - if grep smurf $i - echo Smurfs are present in $i - break - end -end -\endfish diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt deleted file mode 100644 index 8645c18dd..000000000 --- a/doc_src/breakpoint.txt +++ /dev/null @@ -1,14 +0,0 @@ -\section breakpoint breakpoint - Launch debug mode - -\subsection breakpoint-synopsis Synopsis -\fish{synopsis} -breakpoint -\endfish - -\subsection breakpoint-description Description - -`breakpoint` is used to halt a running script and launch an interactive debugging prompt. - -For more details, see Debugging fish scripts in the `fish` manual. - -There are no parameters for `breakpoint`. diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt deleted file mode 100644 index 20664823e..000000000 --- a/doc_src/builtin.txt +++ /dev/null @@ -1,24 +0,0 @@ -\section builtin builtin - run a builtin command - -\subsection builtin-synopsis Synopsis -\fish{synopsis} -builtin [OPTIONS...] BUILTINNAME -builtin --query BUILTINNAMES... -\endfish - -\subsection builtin-description Description - -`builtin` forces the shell to use a builtin command, rather than a function or program. - -The following parameters are available: - -- `-n` or `--names` List the names of all defined builtins -- `-q` or `--query` tests if any of the specified builtins exists. - - -\subsection builtin-example Example - -\fish -builtin jobs -# executes the jobs builtin, even if a function named jobs exists -\endfish diff --git a/doc_src/case.txt b/doc_src/case.txt deleted file mode 100644 index 065c19e9b..000000000 --- a/doc_src/case.txt +++ /dev/null @@ -1,42 +0,0 @@ -\section case case - conditionally execute a block of commands - -\subsection case-synopsis Synopsis -\fish{synopsis} -switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\endfish - -\subsection case-description Description - -`switch` executes one of several blocks of commands, depending on whether a specified value matches one of several values. `case` is used together with the `switch` statement in order to determine which block should be executed. - -Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames. - -Note that fish does not fall through on case statements. Only the first matching case is executed. - -Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. - - -\subsection case-example Example - -Say \$animal contains the name of an animal. Then this code would classify it: - -\fish -switch $animal - case cat - echo evil - case wolf dog human moose dolphin whale - echo mammal - case duck goose albatross - echo bird - case shark trout stingray - echo fish - # Note that the next case has a wildcard which is quoted - case '*' - echo I have no idea what a $animal is -end -\endfish - -If the above code was run with `$animal` set to `whale`, the output -would be `mammal`. - -If `$animal` was set to "banana", it would print "I have no idea what a banana is". diff --git a/doc_src/cd.txt b/doc_src/cd.txt deleted file mode 100644 index 748f0c322..000000000 --- a/doc_src/cd.txt +++ /dev/null @@ -1,33 +0,0 @@ -\section cd cd - change directory - -\subsection cd-synopsis Synopsis -\fish{synopsis} -cd [DIRECTORY] -\endfish - -\subsection cd-description Description -`cd` changes the current working directory. - -If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used. - -If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path. - -Note that the shell will attempt to change directory without requiring `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`). - -Fish also ships a wrapper function around the builtin `cd` that understands `cd -` as changing to the previous directory. See also `prevd`. This wrapper function maintains a history of the 25 most recently visited directories in the `$dirprev` and `$dirnext` global variables. If you make those universal variables your `cd` history is shared among all fish instances. - -As a special case, `cd .` is equivalent to `cd $PWD`, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated. - -\subsection cd-example Examples - -\fish -cd -# changes the working directory to your home directory. - -cd /usr/src/fish-shell -# changes the working directory to /usr/src/fish-shell -\endfish - -\subsection cd-see-also See Also - -See also the `cdh` command for changing to a recently visited directory. diff --git a/doc_src/cdh.txt b/doc_src/cdh.txt deleted file mode 100644 index 7d18acd86..000000000 --- a/doc_src/cdh.txt +++ /dev/null @@ -1,16 +0,0 @@ -\section cdh cdh - change to a recently visited directory - -\subsection cdh-synopsis Synopsis -\fish{synopsis} -cdh [ directory ] -\endfish - -\subsection cdh-description Description - -`cdh` with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press @key{tab} to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to `cd directory`. - -Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates. If you make those universal variables your `cd` history is shared among all fish instances. - -\subsection cdh-see-also See Also - -See also the `prevd` and `pushd` commands which also work with the recent `cd` history and are provided for compatibility with other shells. diff --git a/doc_src/command.txt b/doc_src/command.txt deleted file mode 100644 index 673522587..000000000 --- a/doc_src/command.txt +++ /dev/null @@ -1,30 +0,0 @@ -\section command command - run a program - -\subsection command-synopsis Synopsis -\fish{synopsis} -command [OPTIONS] COMMANDNAME [ARGS...] -\endfish - -\subsection command-description Description - -`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name. - -The following options are available: - -- `-a` or `--all` returns all the external commands that are found in `$PATH` in the order they are found. - -- `-q` or `--quiet`, silences the output and prints nothing, setting only the exit code. Implies `--search`. - -- `-s` or `--search` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the `$PATH`. - -With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like `type -q`, for testing only the exit status. - -For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`. - -\subsection command-example Examples - -`command ls` causes fish to execute the `ls` program, even if an `ls` function exists. - -`command -s ls` returns the path to the `ls` program. - -`command -q git; and command git log` runs `git log` only if `git` exists. diff --git a/doc_src/commandline.txt b/doc_src/commandline.txt deleted file mode 100644 index d97001709..000000000 --- a/doc_src/commandline.txt +++ /dev/null @@ -1,82 +0,0 @@ -\section commandline commandline - set or get the current command line buffer - -\subsection commandline-synopsis Synopsis -\fish{synopsis} -commandline [OPTIONS] [CMD] -\endfish - -\subsection commandline-description Description - -`commandline` can be used to set or get the current contents of the command line buffer. - -With no parameters, `commandline` returns the current value of the command line. - -With `CMD` specified, the command line buffer is erased and replaced with the contents of `CMD`. - -The following options are available: - -- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position. - -- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read. - -The following options change the way `commandline` updates the command line buffer: - -- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it - -- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position - -- `-r` or `--replace` remove the current commandline and replace it with the specified string (default) - -The following options change what part of the commandline is printed or updated: - -- `-b` or `--current-buffer` select the entire buffer, including any displayed autosuggestion (default) - -- `-j` or `--current-job` select the current job - -- `-p` or `--current-process` select the current process - -- `-s` or `--current-selection` selects the current selection - -- `-t` or `--current-token` select the current token - -The following options change the way `commandline` prints the current commandline buffer: - -- `-c` or `--cut-at-cursor` only print selection up until the current cursor position - -- `-o` or `--tokenize` tokenize the selection and print one string-type token per line - -If `commandline` is called during a call to complete a given string using `complete -C STRING`, `commandline` will consider the specified string to be the current contents of the command line. - -The following options output metadata about the commandline state: - -- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1 - -- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search - -- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions - - -\subsection commandline-example Example - -`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history. - -If the commandline contains -\fish ->_ echo $fl___ounder >&2 | less; and echo $catfish -\endfish - -(with the cursor on the "o" of "flounder") - -Then the following invocations behave like this: -\fish ->_ commandline -t -$flounder ->_ commandline -ct -$fl ->_ commandline -b # or just commandline -echo $flounder >&2 | less; and echo $catfish ->_ commandline -p -echo $flounder >&2 ->_ commandline -j -echo $flounder >&2 | less -\endfish diff --git a/doc_src/commands.hdr.in b/doc_src/commands.hdr.in deleted file mode 100644 index f31c96e55..000000000 --- a/doc_src/commands.hdr.in +++ /dev/null @@ -1,38 +0,0 @@ -/** -\page commands Commands -\htmlonly[block] -
- -
-\endhtmlonly -@command_list_toc@ - -\htmlonly[block] -
-
-
-

Command reference

-\endhtmlonly -`fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below. - -Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so: - -\fish -echo -h -echo --help -# Prints help to the terminal window - -man echo -# Displays the man page in the system pager -# (normally 'less', 'more' or 'most'). - -help echo -# Open a web browser to show the relevant documentation -\endfish - -@command_list@ - -\htmlonly[block] -
-\endhtmlonly -*/ diff --git a/doc_src/complete.txt b/doc_src/complete.txt deleted file mode 100644 index d295d1381..000000000 --- a/doc_src/complete.txt +++ /dev/null @@ -1,131 +0,0 @@ -\section complete complete - edit command specific tab-completions - -\subsection complete-synopsis Synopsis -\fish{synopsis} -complete ( -c | --command | -p | --path ) COMMAND - [( -c | --command | -p | --path ) COMMAND]... - [( -e | --erase )] - [( -s | --short-option ) SHORT_OPTION]... - [( -l | --long-option | -o | --old-option ) LONG_OPTION]... - [( -a | --arguments ) OPTION_ARGUMENTS] - [( -k | --keep-order )] - [( -f | --no-files )] - [( -r | --require-parameter )] - [( -x | --exclusive )] - [( -w | --wraps ) WRAPPED_COMMAND]... - [( -n | --condition ) CONDITION] - [( -d | --description ) DESCRIPTION] -complete ( -C[STRING] | --do-complete[=STRING] ) -\endfish - -\subsection complete-description Description - -For an introduction to specifying completions, see Writing your own completions in -the fish manual. - -- `COMMAND` is the name of the command for which to add a completion. - -- `SHORT_OPTION` is a one character option for the command. - -- `LONG_OPTION` is a multi character option for the command. - -- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain command substitutions. - -- `DESCRIPTION` is a description of what the option and/or option arguments do. - -- `-c COMMAND` or `--command COMMAND` specifies that `COMMAND` is the name of the command. - -- `-p COMMAND` or `--path COMMAND` specifies that `COMMAND` is the absolute path of the program (optionally containing wildcards). - -- `-e` or `--erase` deletes the specified completion. - -- `-s SHORT_OPTION` or `--short-option=SHORT_OPTION` adds a short option to the completions list. - -- `-l LONG_OPTION` or `--long-option=LONG_OPTION` adds a GNU style long option to the completions list. - -- `-o LONG_OPTION` or `--old-option=LONG_OPTION` adds an old style long option to the completions list (See below for details). - -- `-a OPTION_ARGUMENTS` or `--arguments=OPTION_ARGUMENTS` adds the specified option arguments to the completions list. - -- `-k` or `--keep-order` preserves the order of the `OPTION_ARGUMENTS` specified via `-a` or `--arguments` instead of sorting alphabetically. - -- `-f` or `--no-files` specifies that the options specified by this completion may not be followed by a filename. - -- `-r` or `--require-parameter` specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option. - -- `-x` or `--exclusive` implies both `-r` and `-f`. - -- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command (See below for details). - -- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases. - -- `-CSTRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string. - -- `-C` or `--do-complete` with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned. - -- `-A` and `--authoritative` no longer do anything and are silently ignored. - -- `-u` and `--unauthoritative` no longer do anything and are silently ignored. - -Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are: - -- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`'). - -- Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`'). - -- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style shell`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h'). - -The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands. - -The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call. - -Invoking `complete` multiple times for the same command adds the new definitions on top of any existing completions defined for the command. - -When `-a` or `--arguments` is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified options. If `-a` or `--arguments` is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with `-r` or `--require-parameter`). - -Command substitutions found in `OPTION_ARGUMENTS` are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with `-d` or `--description`. - -The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options. Note that wrapping only works for completions specified with `-c` or `--command` and are ignored when specifying completions with `-p` or `--path`. - -When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option. - - -\subsection complete-example Example - -The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing: - -\fish -complete -c gcc -s o -r -\endfish - -The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing: - -\fish -complete -c grep -s d -x -a "read skip recurse" -\endfish - -The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as: - -\fish -complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)" -\endfish - -The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch. - -This can be written as: - -\fish -complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" -\endfish - -where `__fish_contains_opt` is a function that checks the command line buffer for the presence of a specified set of options. - -To implement an alias, use the `-w` or `--wraps` option: - -\fish -complete -c hub -w git -\endfish - -Now hub inherits all of the completions from git. Note this can also be specified in a function declaration. - diff --git a/doc_src/contains.txt b/doc_src/contains.txt deleted file mode 100644 index c65292c09..000000000 --- a/doc_src/contains.txt +++ /dev/null @@ -1,48 +0,0 @@ -\section contains contains - test if a word is present in a list - -\subsection contains-synopsis Synopsis -\fish{synopsis} -contains [OPTIONS] KEY [VALUES...] -\endfish - -\subsection contains-description Description - -`contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1. - -The following options are available: - -- `-i` or `--index` print the word index - -Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below. - -\subsection contains-example Example - -If $animals is a list of animals, the following will test if it contains a cat: - -\fish -if contains cat $animals - echo Your animal list is evil! -end -\endfish - -This code will add some directories to $PATH if they aren't yet included: - -\fish -for i in ~/bin /usr/local/bin - if not contains $i $PATH - set PATH $PATH $i - end -end -\endfish - -While this will check if `hasargs` was run with the `-q` option: - -\fish -function hasargs - if contains -- -q $argv - echo '$argv contains a -q option' - end -end -\endfish - -The `--` here stops `contains` from treating `-q` to an option to itself. Instead it treats it as a normal string to check. diff --git a/doc_src/continue.txt b/doc_src/continue.txt deleted file mode 100644 index 26346be6a..000000000 --- a/doc_src/continue.txt +++ /dev/null @@ -1,26 +0,0 @@ -\section continue continue - skip the remainder of the current iteration of the current inner loop - -\subsection continue-synopsis Synopsis -\fish{synopsis} -LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end -\endfish - -\subsection continue-description Description - -`continue` skips the remainder of the current iteration of the current inner loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement. - -\subsection continue-example Example - -The following code removes all tmp files that do not contain the word smurf. - -\fish -for i in *.tmp - if grep smurf $i - continue - end - # This "rm" is skipped over if "continue" is executed. - rm $i - # As is this "echo" - echo $i -end -\endfish diff --git a/doc_src/count.txt b/doc_src/count.txt deleted file mode 100644 index bf11a6350..000000000 --- a/doc_src/count.txt +++ /dev/null @@ -1,25 +0,0 @@ -\section count count - count the number of elements of an array - -\subsection count-synopsis Synopsis -\fish{synopsis} -count $VARIABLE -\endfish - -\subsection count-description Description - -`count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains. - -`count` does not accept any options, not even `-h` or `--help`. - -`count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed. - - -\subsection count-example Example - -\fish -count $PATH -# Returns the number of directories in the users PATH variable. - -count *.txt -# Returns the number of files in the current working directory ending with the suffix '.txt'. -\endfish \ No newline at end of file diff --git a/doc_src/design.hdr b/doc_src/design.hdr deleted file mode 100644 index bbd3ef5a0..000000000 --- a/doc_src/design.hdr +++ /dev/null @@ -1,110 +0,0 @@ -/** -\page design Design document -\htmlonly[block] -
-
-

Design documentation

-\endhtmlonly - -\section design-overview Overview - -This is a description of the design principles that have been used to design fish. The fish design has three high level goals. These are: - --# Everything that can be done in other shell languages should be possible to do in fish, though fish may rely on external commands in doing so. - --# Fish should be user friendly, but not at the expense of expressiveness. Most tradeoffs between power and ease of use can be avoided with careful design. - --# Whenever possible without breaking the above goals, fish should follow the Posix syntax. - -To achieve these high-level goals, the fish design relies on a number of more specific design principles. These are presented below, together with a rationale and a few examples for each. - - -\section ortho The law of orthogonality - -The shell language should have a small set of orthogonal features. Any situation where two features are related but not identical, one of them should be removed, and the other should be made powerful and general enough to handle all common use cases of either feature. - -Rationale: - -Related features make the language larger, which makes it harder to learn. It also increases the size of the source code, making the program harder to maintain and update. - -Examples: - -- Here documents are too similar to using echo inside of a pipeline. - -- Subshells, command substitution and process substitution are strongly related. `fish` only supports command substitution, the others can be achieved either using a block or the psub shellscript function. - -- Having both aliases and functions is confusing, especially since both of them have limitations and problems. `fish` functions have none of the drawbacks of either syntax. - -- The many Posix quoting styles are silly, especially $''. - - -\section design-response The law of responsiveness - -The shell should attempt to remain responsive to the user at all times, even in the face of contended or unresponsive filesystems. It is only acceptable to block in response to a user initiated action, such as running a command. - -Rationale: -Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating. - -Examples: - -- Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously. - -- Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load. - -\section design-configurability Configurability is the root of all evil - -Every configuration option in a program is a place where the program is too stupid to figure out for itself what the user really wants, and should be considered a failure of both the program and the programmer who implemented it. - -Rationale: -Different configuration options are a nightmare to maintain, since the number of potential bugs caused by specific configuration combinations quickly becomes an issue. Configuration options often imply assumptions about the code which change when reimplementing the code, causing issues with backwards compatibility. But mostly, configuration options should be avoided since they simply should not exist, as the program should be smart enough to do what is best, or at least a good enough approximation of it. - -Examples: - -- Fish allows the user to set various syntax highlighting colors. This is needed because fish does not know what colors the terminal uses by default, which might make some things unreadable. The proper solution would be for text color preferences to be defined centrally by the user for all programs, and for the terminal emulator to send these color properties to fish. - -- Fish does not allow you to set the number of history entries, different language substyles or any number of other common shell configuration options. - -A special note on the evils of configurability is the long list of very useful features found in some shells, that are not turned on by default. Both zsh and bash support command-specific completions, but no such completions are shipped with bash by default, and they are turned off by default in zsh. Other features that zsh supports that are disabled by default include tab-completion of strings containing wildcards, a sane completion pager and a history file. - -\section user The law of user focus - -When designing a program, one should first think about how to make an intuitive and powerful program. Implementation issues should only be considered once a user interface has been designed. - -Rationale: - -This design rule is different than the others, since it describes how one should go about designing new features, not what the features should be. The problem with focusing on what can be done, and what is easy to do, is that too much of the implementation is exposed. This means that the user must know a great deal about the underlying system to be able to guess how the shell works, it also means that the language will often be rather low-level. - -Examples: -- There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all performed through regular commands. - -- The differences between built-in commands and shellscript functions should be made as small as possible. Built-ins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any I/O redirection. - -- Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping. - -- All blocks end with the `end` built-in. - -\section disc The law of discoverability - -A program should be designed to make its features as easy as possible to discover for the user. - -Rationale: -A program whose features are discoverable turns a new user into an expert in a shorter span of time, since the user will become an expert on the program simply by using it. - -The main benefit of a graphical program over a command-line-based program is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guessing what the different buttons, menus and other widgets do. The traditional way to discover features in command-line programs is through manual pages. This requires both that the user starts to use a different program, and then they remember the new information until the next time they use the same program. - -Examples: -- Everything should be tab-completable, and every tab completion should have a description. - -- Every syntax error and error in a built-in command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter. - -- The help manual should be easy to read, easily available from the shell, complete and contain many examples - -- The language should be uniform, so that once the user understands the command/argument syntax, they will know the whole language, and be able to use tab-completion to discover new features. - - -\htmlonly[block] -
-
-\endhtmlonly - -*/ diff --git a/doc_src/dirh.txt b/doc_src/dirh.txt deleted file mode 100644 index 77e03e185..000000000 --- a/doc_src/dirh.txt +++ /dev/null @@ -1,14 +0,0 @@ -\section dirh dirh - print directory history - -\subsection dirh-synopsis Synopsis -\fish{synopsis} -dirh -\endfish - -\subsection dirh-description Description - -`dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable. - -`dirh` does not accept any parameters. - -Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables. diff --git a/doc_src/dirs.txt b/doc_src/dirs.txt deleted file mode 100644 index c3da6e84f..000000000 --- a/doc_src/dirs.txt +++ /dev/null @@ -1,15 +0,0 @@ -\section dirs dirs - print directory stack - -\subsection dirs-synopsis Synopsis -\fish{synopsis} -dirs -dirs -c -\endfish - -\subsection dirs-description Description - -`dirs` prints the current directory stack, as created by the `pushd` command. - -With "-c", it clears the directory stack instead. - -`dirs` does not accept any parameters. diff --git a/doc_src/disown.txt b/doc_src/disown.txt deleted file mode 100644 index 45f5c025a..000000000 --- a/doc_src/disown.txt +++ /dev/null @@ -1,24 +0,0 @@ -\section disown disown - remove a process from the list of jobs - -\subsection disown-synopsis Synopsis -\fish{synopsis} -disown [ PID ... ] -\endfish - -\subsection disown-description Description - -`disown` removes the specified job from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer. - -Jobs in the list of jobs are sent a hang-up signal when fish terminates, which usually causes the job to terminate; `disown` allows these processes to continue regardless. - -If no process is specified, the most recently-used job is removed (like `bg` and `fg`). If one or more `PID`s are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed. - -If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the `bg` builtin to continue a job once it has been disowned. - -`disown` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered. - -\subsection disown-example Example - -`firefox &; disown` will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed. - -`disown (jobs -p)` removes all jobs from the job list without terminating them. diff --git a/doc_src/echo.txt b/doc_src/echo.txt deleted file mode 100644 index 69d6df4ef..000000000 --- a/doc_src/echo.txt +++ /dev/null @@ -1,60 +0,0 @@ -\section echo echo - display a line of text - -\subsection echo-synopsis Synopsis -\fish{synopsis} -echo [OPTIONS] [STRING] -\endfish - -\subsection echo-description Description - -`echo` displays a string of text. - -The following options are available: - -- `-n`, Do not output a newline - -- `-s`, Do not separate arguments with spaces - -- `-E`, Disable interpretation of backslash escapes (default) - -- `-e`, Enable interpretation of backslash escapes - -\subsection echo-escapes Escape Sequences - -If `-e` is used, the following sequences are recognized: - -- `\` backslash - -- `\a` alert (BEL) - -- `\b` backspace - -- `\c` produce no further output - -- `\e` escape - -- `\f` form feed - -- `\n` new line - -- `\r` carriage return - -- `\t` horizontal tab - -- `\v` vertical tab - -- `\0NNN` byte with octal value NNN (1 to 3 digits) - -- `\xHH` byte with hexadecimal value HH (1 to 2 digits) - -\subsection echo-example Example - -\fish -echo 'Hello World' -\endfish -Print hello world to stdout - -\fish -echo -e 'Top\\nBottom' -\endfish -Print Top and Bottom on separate lines, using an escape sequence diff --git a/doc_src/else.txt b/doc_src/else.txt deleted file mode 100644 index 76e0c61f3..000000000 --- a/doc_src/else.txt +++ /dev/null @@ -1,23 +0,0 @@ -\section else else - execute command if a condition is not met - -\subsection else-synopsis Synopsis -\fish{synopsis} -if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end -\endfish - -\subsection else-description Description - -`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If it is not 0 and `else` is given, `COMMANDS_FALSE` will be executed. - - -\subsection else-example Example - -The following code tests whether a file `foo.txt` exists as a regular file. - -\fish -if test -f foo.txt - echo foo.txt exists -else - echo foo.txt does not exist -end -\endfish diff --git a/doc_src/emit.txt b/doc_src/emit.txt deleted file mode 100644 index 78f8e2467..000000000 --- a/doc_src/emit.txt +++ /dev/null @@ -1,28 +0,0 @@ -\section emit emit - Emit a generic event - -\subsection emit-synopsis Synopsis -\fish{synopsis} -emit EVENT_NAME [ARGUMENTS...] -\endfish - -\subsection emit-description Description - -`emit` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments. - - -\subsection emit-example Example - -The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. - -\fish -function event_test --on-event test_event - echo event test: $argv -end - -emit test_event something -\endfish - - -\subsection emit-notes Notes - -Note that events are only sent to the current fish process as there is no way to send events from one fish process to another. diff --git a/doc_src/end.txt b/doc_src/end.txt deleted file mode 100644 index 2b035930c..000000000 --- a/doc_src/end.txt +++ /dev/null @@ -1,19 +0,0 @@ -\section end end - end a block of commands. - -\subsection end-synopsis Synopsis -\fish{synopsis} -begin; [COMMANDS...] end -if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end -while CONDITION; COMMANDS...; end -for VARNAME in [VALUES...]; COMMANDS...; end -switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\endfish - -\subsection end-description Description - -`end` ends a block of commands. - -For more information, read the -documentation for the block constructs, such as `if`, `for` and `while`. - -The `end` command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command. diff --git a/doc_src/eval.txt b/doc_src/eval.txt deleted file mode 100644 index 5e7785077..000000000 --- a/doc_src/eval.txt +++ /dev/null @@ -1,21 +0,0 @@ -\section eval eval - evaluate the specified commands - -\subsection eval-synopsis Synopsis -\fish{synopsis} -eval [COMMANDS...] -\endfish - -\subsection eval-description Description -`eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator. - -If your command does not need access to stdin, consider using `source` instead. - -\subsection eval-example Example - -The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this. - -\fish -set cmd ls -eval $cmd -\endfish - diff --git a/doc_src/exec.txt b/doc_src/exec.txt deleted file mode 100644 index f8936101a..000000000 --- a/doc_src/exec.txt +++ /dev/null @@ -1,15 +0,0 @@ -\section exec exec - execute command in current process - -\subsection exec-synopsis Synopsis -\fish{synopsis} -exec COMMAND [OPTIONS...] -\endfish - -\subsection exec-description Description - -`exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline. - - -\subsection exec-example Example - -`exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate. diff --git a/doc_src/exit.txt b/doc_src/exit.txt deleted file mode 100644 index b780c4317..000000000 --- a/doc_src/exit.txt +++ /dev/null @@ -1,12 +0,0 @@ -\section exit exit - exit the shell - -\subsection exit-synopsis Synopsis -\fish{synopsis} -exit [STATUS] -\endfish - -\subsection exit-description Description - -`exit` causes fish to exit. If `STATUS` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed. - -If exit is called while sourcing a file (using the source builtin) the rest of the file will be skipped, but the shell itself will not exit. diff --git a/doc_src/false.txt b/doc_src/false.txt deleted file mode 100644 index 1ce5a4619..000000000 --- a/doc_src/false.txt +++ /dev/null @@ -1,10 +0,0 @@ -\section false false - return an unsuccessful result - -\subsection false-synopsis Synopsis -\fish{synopsis} -false -\endfish - -\subsection false-description Description - -`false` sets the exit status to 1. diff --git a/doc_src/faq.hdr b/doc_src/faq.hdr deleted file mode 100644 index d0525239e..000000000 --- a/doc_src/faq.hdr +++ /dev/null @@ -1,306 +0,0 @@ -/** -\page faq Frequently asked questions -\htmlonly[block] -
- -
- -\endhtmlonly - -- How do I set or clear an environment variable? -- How do I run a command every login? What's fish's equivalent to `.bashrc`? -- How do I set my prompt? -- How do I run a command from history? -- How do I run a subcommand? The backtick doesn't work! -- My command (pkg-config) gives its output as a single long string? -- How do I get the exit status of a command? -- How do I set an environment variable for just one command? -- Why doesn't `set -Ux` (exported universal variables) seem to work? -- How do I customize my syntax highlighting colors? -- How do I update man page completions? -- I accidentally entered a directory path and fish changed directory. What happened? -- The open command doesn't work. -- How do I make fish my default shell? -- I'm seeing weird output before each prompt when using screen. What's wrong? -- How do I change the greeting message? -- Why doesn't history substitution ("!$" etc.) work? -- How can I use `-` as a shortcut for `cd -`? -- How do I uninstall fish? -- Where can I find extra tools for fish? - -\htmlonly[block] -
-
-
-

Frequently Asked Questions

-\endhtmlonly - - -\section faq-envvar How do I set or clear an environment variable? - -Use the `set` command: - -\fish{cli-dark} -set -x key value -set -e key -\endfish - - -\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc? - -Edit the file `~/.config/fish/config.fish`, creating it if it does not exist (Note the leading period). - -
-\section faq-prompt How do I set my prompt? - -The prompt is the output of the `fish_prompt` function. Put it in `~/.config/fish/functions/fish_prompt.fish`. For example, a simple prompt is: - -\fish{cli-dark} -function fish_prompt - set_color $fish_color_cwd - echo -n (prompt_pwd) - set_color normal - echo -n ' > ' -end -\endfish - -You can also use the Web configuration tool, `fish_config`, to preview and choose from a gallery of sample prompts. - - -\section faq-cmd-history How do I run a command from history? - -Type some part of the command, and then hit the @cursor_key{↑,up} or @cursor_key{↓,down} arrow keys to navigate through history matches. - -
-\section faq-subcommand How do I run a subcommand? The backtick doesn't work! - -`fish` uses parentheses for subcommands. For example: - -\fish{cli-dark} -for i in (ls) - echo $i -end -\endfish - -\section faq-pkg-config My command (pkg-config) gives its output as a single long string? - -Unlike other shells, fish splits command substitutions only on newlines, not spaces or tabs or the characters in $IFS. - -That means if you run - -\fish{cli-dark} -echo x(printf '%s ' a b c)x -\endfish - -It will print `xa b c x`. But if you do - -\fish{cli-dark} -echo x(printf '%s\n' a b c)x -\endfish - -it will print `xax xbx xcx`. - -In the overwhelming majority of cases, splitting on spaces is unwanted, so this is an improvement. - -However sometimes, especially with `pkg-config` and related tools, splitting on spaces is needed. - -In these cases use `string split " "` like: - -\fish{cli-dark} -g++ example_01.cpp (pkg-config --cflags --libs gtk+-2.0 | string split " ") -\endfish - -\section faq-exit-status How do I get the exit status of a command? - -Use the `$status` variable. This replaces the `$?` variable used in some other shells. - -\fish{cli-dark} -somecommand -if test $status -eq 7 - echo "That's my lucky number!" -end -\endfish - -If you are just interested in success or failure, you can run the command directly as the if-condition: - -\fish{cli-dark} -if somecommand - echo "Command succeeded" -else - echo "Command failed" -end -\endfish - -See the documentation for `test` and `if` for more information. - -
-\section faq-single-env How do I set an environment variable for just one command? - -`SOME_VAR=1 command` produces an error: `Unknown command "SOME_VAR=1"`. - -Use the `env` command. - -`env SOME_VAR=1 command` - -You can also declare a local variable in a block: - -\fish{cli-dark} -begin - set -lx SOME_VAR 1 - command -end -\endfish - -\section faq-exported-uvar Why doesn't `set -Ux` (exported universal variables) seem to work? - -A global variable of the same name already exists. - -Environment variables such as `EDITOR` or `TZ` can be set universally using `set -Ux`. However, if -there is an environment variable already set before fish starts (such as by login scripts or system -administrators), it is imported into fish as a global variable. The variable scopes are searched from the "inside out", which -means that local variables are checked first, followed by global variables, and finally universal -variables. - -This means that the global value takes precedence over the universal value. - -To avoid this problem, consider changing the setting which fish inherits. If this is not possible, -add a statement to your user initialization file (usually -`~/.config/fish/config.fish`): - -\fish{cli-dark} -set -gx EDITOR vim -\endfish - -\section faq-customize-colors How do I customize my syntax highlighting colors? - -Use the web configuration tool, `fish_config`, or alter the `fish_color` family of environment variables. - -
-\section faq-update-manpage-completions How do I update man page completions? - -Use the `fish_update_completions` command. - -
-\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened? - -If fish is unable to locate a command with a given name, and it starts with '`.`', '`/`' or '`~`', fish will test if a directory of that name exists. If it does, it is implicitly assumed that you want to change working directory. For example, the fastest way to switch to your home directory is to simply press `~` and enter. - -
-\section faq-open The open command doesn't work. - -The `open` command uses the MIME type database and the `.desktop` files used by Gnome and KDE to identify filetypes and default actions. If at least one of these environments is installed, but the open command is not working, this probably means that the relevant files are installed in a non-standard location. Consider asking for more help. - -
-\section faq-default How do I make fish my default shell? - -If you installed fish manually (e.g. by compiling it, not by using a package manager), you first need to add fish to the list of shells by executing the following command (assuming you installed fish in /usr/local): - -\fish{cli-dark} -echo /usr/local/bin/fish | sudo tee -a /etc/shells -\endfish - -If you installed a prepackaged version of fish, the package manager should have already done this for you. - -In order to change your default shell, type: - -\fish{cli-dark} -chsh -s /usr/local/bin/fish -\endfish - -You may need to adjust the above path to e.g. `/usr/bin/fish`. Use the command `which fish` if you are unsure of where fish is installed. - -Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again. - -
-\section faq-titlebar I'm seeing weird output before each prompt when using screen. What's wrong? - -Quick answer: - -Run the following command in fish: - -\fish{cli-dark} -function fish_title; end; funcsave fish_title -\endfish - -Problem solved! - -The long answer: - -Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortunately, when the underlying terminal doesn't support setting the titlebar, screen simply passes through the escape codes and text to the underlying terminal instead of ignoring them. It is impossible to detect and resolve this problem from inside fish since fish has no way of knowing what the underlying terminal type is. For now, the only way to fix this is to unset the titlebar message, as suggested above. - -Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work. - -
-\section faq-greeting How do I change the greeting message? - -Change the value of the variable `fish_greeting` or create a `fish_greeting` function. For example, to remove the greeting use: - -\fish{cli-dark} -set fish_greeting -\endfish - -
-\section faq-history Why doesn't history substitution ("!$" etc.) work? - -Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Fish drops it in favor of perfecting the interactive history recall interface. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then type "sudo ". - -Fish history recall is very simple yet effective: - -- As in any modern shell, the Up arrow, @cursor_key{↑,Up} recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like. - - - If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like. - -- @key{Alt,↑,Up} recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like. - - - If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press @key{Alt,↑,Up}. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient! - - - If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (@key{Alt,D} and @key{Alt,Backspace} are your friends). - -See documentation for more details about line editing in fish. - -
-\section faq-cd-minus How can I use `-` as a shortcut for `cd -`? - -In fish versions prior to 2.5.0 it was possible to create a function named `-` that would do `cd -`. Changes in the 2.5.0 release included several bug fixes that enforce the rule that a bare hyphen is not a valid function (or variable) name. However, you can achieve the same effect via an abbreviation: - -\fish{cli-dark} -abbr -a -- - 'cd -' -\endfish - -
-\section faq-uninstalling Uninstalling fish - -Should you wish to uninstall fish, first ensure fish is not set as your shell. Run `chsh -s /bin/bash` if you are not sure. - -Next, do the following (assuming fish was installed to /usr/local): - -\fish{cli-dark} -rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish -rm /usr/local/share/man/man1/fish*.1 -cd /usr/local/bin -rm -f fish fish_indent -\endfish - -
-\section faq-reserved-chars Unicode private-use characters reserved by fish - -Fish reserves the Unicode private-use character range from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish). - -
-\section faq-third-party Where can I find extra tools for fish? - -The fish user community extends fish in unique and useful ways via scripts that aren't always appropriate for bundling with the fish package. Typically because they solve a niche problem unlikely to appeal to a broad audience. You can find those extensions, including prompts, themes and useful functions, in various third-party repositories. These include: - -- Fisher -- Fundle -- Oh My Fish -- Tacklebox - -This is not an exhaustive list and the fish project has no opinion regarding the merits of the repositories listed above or the scripts found therein. - -\htmlonly[block] -
-\endhtmlonly - -*/ diff --git a/doc_src/fg.txt b/doc_src/fg.txt deleted file mode 100644 index a27a0ad6b..000000000 --- a/doc_src/fg.txt +++ /dev/null @@ -1,15 +0,0 @@ -\section fg fg - bring job to foreground - -\subsection fg-synopsis Synopsis -\fish{synopsis} -fg [PID] -\endfish - -\subsection fg-description Description - -`fg` brings the specified job to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground. - - -\subsection fg-example Example - -`fg` will put the last job in the foreground. diff --git a/doc_src/fish.txt b/doc_src/fish.txt deleted file mode 100644 index 5e22e526d..000000000 --- a/doc_src/fish.txt +++ /dev/null @@ -1,34 +0,0 @@ -\section fish fish - the friendly interactive shell - -\subsection fish-synopsis Synopsis -\fish{synopsis} -fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]] -\endfish - -\subsection fish-description Description - -`fish` is a command-line shell written mainly with interactive use in mind. The full manual is available in HTML by using the help command from inside fish. - -The following options are available: - -- `-c` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline - -- `-C` or `--init-command=COMMANDS` evaluate the specified commands after reading the configuration, before running the command specified by `-c` or reading interactive input - -- `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1. - -- `-i` or `--interactive` specify that fish is to run in interactive mode - -- `-l` or `--login` specify that fish is to run as a login shell - -- `-n` or `--no-execute` do not execute any commands, only perform syntax checking - -- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file - -- `-v` or `--version` display version and exit - -- `-D` or `--debug-stack-frames=DEBUG_LEVEL` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. - -- `-f` or `--features=FEATURES` enables one or more feature flags (separated by a comma). These are how fish stages changes that might break scripts. - -The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127. diff --git a/doc_src/fish_breakpoint_prompt.txt b/doc_src/fish_breakpoint_prompt.txt deleted file mode 100644 index b56c7e0ac..000000000 --- a/doc_src/fish_breakpoint_prompt.txt +++ /dev/null @@ -1,30 +0,0 @@ -\section fish_breakpoint_prompt fish_breakpoint_prompt - define the appearance of the command line prompt when in the context of a `breakpoint` command - -\subsection fish_breakpoint_prompt-synopsis Synopsis -\fish{synopsis} -function fish_breakpoint_prompt - ... -end -\endfish - -\subsection fish_breakpoint_prompt-description Description - -By defining the `fish_breakpoint_prompt` function, the user can choose a custom prompt when asking for input in response to a `breakpoint` command. The `fish_breakpoint_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt. - -The exit status of commands within `fish_breakpoint_prompt` will not modify the value of $status outside of the `fish_breakpoint_prompt` function. - -`fish` ships with a default version of this function that displays the function name and line number of the current execution context. - - -\subsection fish_breakpoint_prompt-example Example - -A simple prompt that is a simplified version of the default debugging prompt: - -\fish -function fish_breakpoint_prompt -d "Write out the debug prompt" - set -l function (status current-function) - set -l line (status current-line-number) - set -l prompt "$function:$line >" - echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' ' -end -\endfish diff --git a/doc_src/fish_config.txt b/doc_src/fish_config.txt deleted file mode 100644 index 4fa242651..000000000 --- a/doc_src/fish_config.txt +++ /dev/null @@ -1,18 +0,0 @@ -\section fish_config fish_config - start the web-based configuration interface - -\subsection fish_config-description Description - -`fish_config` starts the web-based configuration interface. - -The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration. - -`fish_config` starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session. - -`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab. - -If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default. - - -\subsection fish_config-example Example - -`fish_config` opens a new web browser window and allows you to configure certain fish settings. diff --git a/doc_src/fish_git_prompt.txt b/doc_src/fish_git_prompt.txt deleted file mode 100644 index a4867d7c5..000000000 --- a/doc_src/fish_git_prompt.txt +++ /dev/null @@ -1,93 +0,0 @@ -\section fish_git_prompt fish_git_prompt - output git information for use in a prompt - -\subsection fish_git_prompt-description Description - -The fish_git_prompt function can be used to display information about the current git repository, if any. - -For obvious reasons, it requires having git installed. - -There are numerous configuration options, either as fish variables or git config variables. If a git config variable is supported, it will be used if set, and the fish variable will only be used if it isn't. - -- $__fish_git_prompt_showdirtystate or the git config option "bash.showDirtyState" can be set to show if the repository is "dirty", i.e. has uncommitted changes. - -- $__fish_git_prompt_showuntrackedfiles or the git config option "bash.showUntrackedFiles" can be set to show if the repository has untracked files (that aren't ignored). - -- $__fish_git_prompt_show_informative_status or the git config option "bash.showInformativeStatus" can be set to enable the "informative" display, which will show a large amount of information - the number of untracked files, dirty files, unpushed/unpulled commits, etc... In large repositories, this can take a lot of time, so it is recommended to disable it there. - -- $__fish_git_prompt_showupstream can be set to a number of values to determine how changes between HEAD and upstream are shown: - - verbose show number of commits ahead/behind (+/-) upstream - name if verbose, then also show the upstream abbrev name - informative similar to verbose, but shows nothing when equal (fish only) - git always compare HEAD to @{upstream} - svn always compare HEAD to your SVN upstream - none disables (fish only, useful with show_informative_status) - -- $__fish_git_prompt_showstashstate can be set to display the state of the stash. - -- $__fish_git_prompt_shorten_branch_len can be set to the number of characters that the branch name will be shortened to. - -- $__fish_git_prompt_describe_style can be set to a number of styles that describe the current HEAD: - - contains - branch - describe - default - -- $__fish_git_prompt_showcolorhints can be set to enable coloring for certain things. - -A number of variables to set characters and color used to indicate things. - -- $__fish_git_prompt_char_cleanstate -- $__fish_git_prompt_char_dirtystate -- $__fish_git_prompt_char_invalidstate -- $__fish_git_prompt_char_stagedstate -- $__fish_git_prompt_char_stashstate -- $__fish_git_prompt_char_stateseparator -- $__fish_git_prompt_char_untrackedfiles -- $__fish_git_prompt_char_upstream_ahead -- $__fish_git_prompt_char_upstream_behind -- $__fish_git_prompt_char_upstream_diverged -- $__fish_git_prompt_char_upstream_equal -- $__fish_git_prompt_char_upstream_prefix -- $__fish_git_prompt_color -- $__fish_git_prompt_color_prefix -- $__fish_git_prompt_color_suffix -- $__fish_git_prompt_color_bare -- $__fish_git_prompt_color_merging -- $__fish_git_prompt_color_cleanstate -- $__fish_git_prompt_color_invalidstate -- $__fish_git_prompt_color_upstream - -Colors used with showcolorhints: - -- $__fish_git_prompt_color_flags -- $__fish_git_prompt_color_branch -- $__fish_git_prompt_color_dirtystate -- $__fish_git_prompt_color_stagedstate -- $__fish_git_prompt_color_flags -- $__fish_git_prompt_color_branch -- $__fish_git_prompt_color_dirtystate -- $__fish_git_prompt_color_stagedstate -- $__fish_git_prompt_color_branch_detached - -Colors used with their respective flags enabled: -- $__fish_git_prompt_color_stashstate -- $__fish_git_prompt_color_untrackedfiles - -Note that all colors can also have a corresponding "_done" color. E.g. $__fish_git_prompt_color_upstream_done, used right _after_ the upstream. - -See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn. - -\subsection fish_git_prompt-example Example - -A simple prompt that displays git info: - -\fish -function fish_prompt - ... - set -g __fish_git_prompt_showupstream auto - printf '%s %s$' $PWD (fish_git_prompt) -end -\endfish - diff --git a/doc_src/fish_hg_prompt.txt b/doc_src/fish_hg_prompt.txt deleted file mode 100644 index 044af98c3..000000000 --- a/doc_src/fish_hg_prompt.txt +++ /dev/null @@ -1,45 +0,0 @@ -\section fish_hg_prompt fish_hg_prompt - output mercurial information for use in a prompt - -\subsection fish_hg_prompt-description Description - -The fish_hg_prompt function can be used to display information about the current mercurial repository, if any. - -For obvious reasons, it requires having hg installed. - -There are numerous configuration options: - -- $fish_color_hg_clean, $fish_color_hg_modified and $fish_color_hg_dirty: The color to use when the repo has the respective status - -Some colors for status symbols: - -- $fish_color_hg_added -- $fish_color_hg_renamed -- $fish_color_hg_copied -- $fish_color_hg_deleted -- $fish_color_hg_untracked -- $fish_color_hg_unmerged - -And the status symbols themselves: - -- $fish_prompt_hg_status_added, default '✚' -- $fish_prompt_hg_status_modified, default '*' -- $fish_prompt_hg_status_copied, default '⇒' -- $fish_prompt_hg_status_deleted, default '✖' -- $fish_prompt_hg_status_untracked, default '?' -- $fish_prompt_hg_status_unmerged, default '!' - -And $fish_prompt_hg_status_order, which can be used to change the order the status symbols appear in. It defaults to `added modified copied deleted untracked unmerged`. - -See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn. - -\subsection fish_hg_prompt-example Example - -A simple prompt that displays hg info: - -\fish -function fish_prompt - ... - printf '%s %s$' $PWD (fish_hg_prompt) -end -\endfish - diff --git a/doc_src/fish_indent.txt b/doc_src/fish_indent.txt deleted file mode 100644 index 2cc429fb7..000000000 --- a/doc_src/fish_indent.txt +++ /dev/null @@ -1,28 +0,0 @@ -\section fish_indent fish_indent - indenter and prettifier - -\subsection fish_indent-synopsis Synopsis -\fish{synopsis} -fish_indent [OPTIONS] -\endfish - -\subsection fish_indent-description Description - -`fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output or a specified file. - -The following options are available: - -- `-w` or `--write` indents a specified file and immediately writes to that file. - -- `-i` or `--no-indent` do not indent commands; only reformat to one job per line. - -- `-v` or `--version` displays the current fish version and then exits. - -- `--ansi` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as `$fish_color_command`). - -- `--html` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as `fish_color_command`. - -- `-d` or `--debug-level=DEBUG_LEVEL` enables debug output and specifies a verbosity level (like `fish -d`). Defaults to 0. - -- `-D` or `--debug-stack-frames=DEBUG_LEVEL` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. - -- `--dump-parse-tree` dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code. diff --git a/doc_src/fish_key_reader.txt b/doc_src/fish_key_reader.txt deleted file mode 100644 index d1d5db2ab..000000000 --- a/doc_src/fish_key_reader.txt +++ /dev/null @@ -1,35 +0,0 @@ -\section fish_key_reader fish_key_reader - explore what characters keyboard keys send - -\subsection fish_key_reader-synopsis Synopsis -\fish{synopsis} -fish_key_reader [OPTIONS] -\endfish - -\subsection fish_key_reader-description Description - -`fish_key_reader` is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed. - -The tool will write an example `bind` command matching the character sequence captured to stdout. If the character sequence matches a special key name (see `bind --key-names`), both `bind CHARS ...` and `bind -k KEYNAME ...` usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr. - -The following options are available: - -- `-c` or `--continuous` begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence. - -- `-d` or `--debug-level=DEBUG_LEVEL` enables debug output and specifies a verbosity level (like `fish -d`). Defaults to 0. - -- `-D` or `--debug-stack-frames=DEBUG_LEVEL` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128. - -- `-h` or `--help` prints usage information. - -- `-v` or `--version` prints fish_key_reader's version and exits. - -\subsection fish_key_reader-usage-notes Usage Notes - -The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal `fish_escape_delay_ms` setting or learn the amount of lag introduced by tools like `ssh`, `mosh` or `tmux`. - -`fish_key_reader` intentionally disables handling of many signals. To terminate `fish_key_reader` in `--continuous` mode do: - -- press `Ctrl-C` twice, or -- press `Ctrl-D` twice, or -- type `exit`, or -- type `quit` diff --git a/doc_src/fish_mode_prompt.txt b/doc_src/fish_mode_prompt.txt deleted file mode 100644 index c397d2c33..000000000 --- a/doc_src/fish_mode_prompt.txt +++ /dev/null @@ -1,37 +0,0 @@ -\section fish_mode_prompt fish_mode_prompt - define the appearance of the mode indicator - -\subsection fish_mode_prompt-synopsis Synopsis - -The fish_mode_prompt function will output the mode indicator for use in vi-mode. - -\subsection fish_mode_prompt-description Description - -The default `fish_mode_prompt` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty `fish_mode_prompt` function to remove the Vi mode indicators. The `$fish_bind_mode variable` can be used to determine the current mode. It -will be one of `default`, `insert`, `replace_one`, or `visual`. - -\subsection fish_mode_prompt-example Example - -\fish -function fish_mode_prompt - switch $fish_bind_mode - case default - set_color --bold red - echo 'N' - case insert - set_color --bold green - echo 'I' - case replace_one - set_color --bold green - echo 'R' - case visual - set_color --bold brmagenta - echo 'V' - case '*' - set_color --bold red - echo '?' - end - set_color normal -end -\endfish - -Outputting multiple lines is not supported in `fish_mode_prompt`. diff --git a/doc_src/fish_opt.txt b/doc_src/fish_opt.txt deleted file mode 100644 index 24967d24a..000000000 --- a/doc_src/fish_opt.txt +++ /dev/null @@ -1,54 +0,0 @@ -\section fish_opt fish_opt - create an option spec for the argparse command - -\subsection fish_opt-synopsis Synopsis -\fish{synopsis} -fish_opt [ -h | --help ] -fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \ - [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ] -\endfish - -\subsection fish_opt-description Description - -This command provides a way to produce option specifications suitable for use with the `argparse` command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides. - -The following `argparse` options are available: - -- `-s` or `--short` takes a single letter that is used as the short flag in the option being defined. This option is mandatory. - -- `-l` or `--long` takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec. - -- `--long-only` means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., `--short` must be specified) but it cannot be used when parsing args using this option spec. - -- `-o` or `--optional` means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by `argparse` will zero elements if no value was given with the option else it will have exactly one element. - -- `-r` or `--required` means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by `argparse` will have exactly one element. - -- `--multiple-vals` means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by `argparse` will have one element for each instance of this option in the args. - -- `-h` or `--help` displays help about using this command. - -\subsection fish_opt-examples Examples - -Define a single option spec for the boolean help flag: - -\fish -set -l options (fish_opt -s h -l help) -argparse $options -- $argv -\endfish - -Same as above but with a second flag that requires a value: - -\fish -set -l options (fish_opt -s h -l help) -set options $options (fish_opt -s m -l max --required-val) -argparse $options -- $argv -\endfish - -Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (`--token`) can be used: - -\fish -set -l options (fish_opt --short=h --long=help) -set options $options (fish_opt --short=m --long=max --required-val) -set options $options (fish_opt --short=t --long=token --multiple-vals --long-only) -argparse $options -- $argv -\endfish diff --git a/doc_src/fish_prompt.txt b/doc_src/fish_prompt.txt deleted file mode 100644 index 1beb5304e..000000000 --- a/doc_src/fish_prompt.txt +++ /dev/null @@ -1,29 +0,0 @@ -\section fish_prompt fish_prompt - define the appearance of the command line prompt - -\subsection fish_prompt-synopsis Synopsis -\fish{synopsis} -function fish_prompt - ... -end -\endfish - -\subsection fish_prompt-description Description - -By defining the `fish_prompt` function, the user can choose a custom prompt. The `fish_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt. - -The exit status of commands within `fish_prompt` will not modify the value of $status outside of the `fish_prompt` function. - -`fish` ships with a number of example prompts that can be chosen with the `fish_config` command. - - -\subsection fish_prompt-example Example - -A simple prompt: - -\fish -function fish_prompt -d "Write out the prompt" - printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \ - (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) -end -\endfish - diff --git a/doc_src/fish_right_prompt.txt b/doc_src/fish_right_prompt.txt deleted file mode 100644 index 87de31139..000000000 --- a/doc_src/fish_right_prompt.txt +++ /dev/null @@ -1,26 +0,0 @@ -\section fish_right_prompt fish_right_prompt - define the appearance of the right-side command line prompt - -\subsection fish_right_prompt-synopsis Synopsis -\fish{synopsis} -function fish_right_prompt - ... -end -\endfish - -\subsection fish_right_prompt-description Description - -`fish_right_prompt` is similar to `fish_prompt`, except that it appears on the right side of the terminal window. - -Multiple lines are not supported in `fish_right_prompt`. - - -\subsection fish_right_prompt-example Example - -A simple right prompt: - -\fish -function fish_right_prompt -d "Write out the right prompt" - date '+%m/%d/%y' -end -\endfish - diff --git a/doc_src/fish_svn_prompt.txt b/doc_src/fish_svn_prompt.txt deleted file mode 100644 index e5561ecad..000000000 --- a/doc_src/fish_svn_prompt.txt +++ /dev/null @@ -1,82 +0,0 @@ -\section fish_svn_prompt fish_svn_prompt - output svn information for use in a prompt - -\subsection fish_svn_prompt-description Description - -The fish_svn_prompt function can be used to display information about the current svn repository, if any. - -For obvious reasons, it requires having svn installed. - -There are numerous configuration options: - - -- $__fish_svn_prompt_color_revision, the colour of the revision number to display in the prompt -# setting the prompt status separator character -- $__fish_svn_prompt_char_separator, the separator between status characters - -And -- $__fish_svn_prompt_char_added_display -- $__fish_svn_prompt_char_added_color - -- $__fish_svn_prompt_char_conflicted_display -- $__fish_svn_prompt_char_conflicted_color - -- $__fish_svn_prompt_char_deleted_display -- $__fish_svn_prompt_char_deleted_color - -- $__fish_svn_prompt_char_ignored_display -- $__fish_svn_prompt_char_ignored_color - -- $__fish_svn_prompt_char_modified_display -- $__fish_svn_prompt_char_modified_color - -- $__fish_svn_prompt_char_replaced_display -- $__fish_svn_prompt_char_replaced_color - -- $__fish_svn_prompt_char_unversioned_external_display -- $__fish_svn_prompt_char_unversioned_external_color - -- $__fish_svn_prompt_char_unversioned_display -- $__fish_svn_prompt_char_unversioned_color - -- $__fish_svn_prompt_char_missing_display -- $__fish_svn_prompt_char_missing_color - -- $__fish_svn_prompt_char_versioned_obstructed_display -- $__fish_svn_prompt_char_versioned_obstructed_color - -- $__fish_svn_prompt_char_locked_display -- $__fish_svn_prompt_char_locked_color - -- $__fish_svn_prompt_char_scheduled_display -- $__fish_svn_prompt_char_scheduled_color - -- $__fish_svn_prompt_char_switched_display -- $__fish_svn_prompt_char_switched_color - -- $__fish_svn_prompt_char_token_present_display -- $__fish_svn_prompt_char_token_present_color - -- $__fish_svn_prompt_char_token_other_display -- $__fish_svn_prompt_char_token_other_color - -- $__fish_svn_prompt_char_token_stolen_display -- $__fish_svn_prompt_char_token_stolen_color - -- $__fish_svn_prompt_char_token_broken_display -- $__fish_svn_prompt_char_token_broken_color - -to choose the color and symbol for different parts of the prompt. - -See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn. - -\subsection fish_svn_prompt-example Example - -A simple prompt that displays svn info: - -\fish -function fish_prompt - ... - printf '%s %s$' $PWD (fish_svn_prompt) -end -\endfish - diff --git a/doc_src/fish_update_completions.txt b/doc_src/fish_update_completions.txt deleted file mode 100644 index 684dac0d8..000000000 --- a/doc_src/fish_update_completions.txt +++ /dev/null @@ -1,9 +0,0 @@ -\section fish_update_completions fish_update_completions - Update completions using manual pages - -\subsection fish_update_completions-description Description - -`fish_update_completions` parses manual pages installed on the system, and attempts to create completion files in the `fish` configuration directory. - -This does not overwrite custom completions. - -There are no parameters for `fish_update_completions`. diff --git a/doc_src/fish_vcs_prompt.txt b/doc_src/fish_vcs_prompt.txt deleted file mode 100644 index fd743473e..000000000 --- a/doc_src/fish_vcs_prompt.txt +++ /dev/null @@ -1,28 +0,0 @@ -\section fish_vcs_prompt fish_vcs_prompt - output vcs information for use in a prompt - -\subsection fish_vcs_prompt-description Description - -The fish_vcs_prompt function can be used to display information about the current vcs repository, if any. - -It calls out to vcs-specific functions. The currently supported ones are: - -- fish_git_prompt -- fish_hg_prompt -- fish_svn_prompt - -If a vcs isn't installed, the respective function does nothing. - -For more information, see their documentation. - -\subsection fish_vcs_prompt-example Example - -A simple prompt that displays vcs info: - -\fish -function fish_prompt - ... - set -g __fish_git_prompt_showupstream auto - printf '%s %s$' $PWD (fish_vcs_prompt) -end -\endfish - diff --git a/doc_src/fish_vi_mode.txt b/doc_src/fish_vi_mode.txt deleted file mode 100644 index d39697c8f..000000000 --- a/doc_src/fish_vi_mode.txt +++ /dev/null @@ -1,12 +0,0 @@ -\section fish_vi_mode fish_vi_mode - Enable vi mode - -\subsection fish_vi_mode-synopsis Synopsis -\fish{synopsis} -fish_vi_mode -\endfish - -\subsection fish_vi_mode-description Description - -This function is deprecated. Please call `fish_vi_key_bindings directly` - -`fish_vi_mode` enters a vi-like command editing mode. To always start in vi mode, add `fish_vi_mode` to your `config.fish` file. diff --git a/doc_src/for.txt b/doc_src/for.txt deleted file mode 100644 index 508a3ac2d..000000000 --- a/doc_src/for.txt +++ /dev/null @@ -1,36 +0,0 @@ -\section for for - perform a set of commands multiple times. - -\subsection for-synopsis Synopsis -\fish{synopsis} -for VARNAME in [VALUES...]; COMMANDS...; end -\endfish - -\subsection for-description 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. - -\subsection for-example Example - -\fish -for i in foo bar baz; echo $i; end - -# would output: -foo -bar -baz -\endfish - -\subsection for-notes 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: - -\fish -for var in a b c - if break_from_loop - break - end -end -echo $var -\endfish - -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. diff --git a/doc_src/funced.txt b/doc_src/funced.txt deleted file mode 100644 index b8a7db530..000000000 --- a/doc_src/funced.txt +++ /dev/null @@ -1,20 +0,0 @@ -\section funced funced - edit a function interactively - -\subsection funced-synopsis Synopsis -\fish{synopsis} -funced [OPTIONS] NAME -\endfish - -\subsection funced-description Description - -`funced` provides an interface to edit the definition of the function `NAME`. - -If the `$VISUAL` environment variable is set, it will be used as the program to edit the function. If `$VISUAL` is unset but `$EDITOR` is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press @key{Alt,Enter}. Pressing @key{Enter} signals that you are done editing the function. This does not apply to an external editor like emacs or vim. - -If there is no function called `NAME` a new function will be created with the specified name - -- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, `-e vi`). The special command `fish` will use the built-in editor (same as specifying `-i`). - -- `-i` or `--interactive` Force opening the function body in the built-in editor even if `$VISUAL` or `$EDITOR` is defined. - -- `-s` or `--save` Automatically save the function after successfully editing it. diff --git a/doc_src/funcsave.txt b/doc_src/funcsave.txt deleted file mode 100644 index 32b3f4f31..000000000 --- a/doc_src/funcsave.txt +++ /dev/null @@ -1,12 +0,0 @@ -\section funcsave funcsave - save the definition of a function to the user's autoload directory - -\subsection funcsave-synopsis Synopsis -\fish{synopsis} -funcsave FUNCTION_NAME -\endfish - -\subsection funcsave-description Description - -`funcsave` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use. - -Note that because fish loads functions on-demand, saved functions will not function as event handlers until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your shell initialization file instead of using `funcsave`. diff --git a/doc_src/function.txt b/doc_src/function.txt deleted file mode 100644 index b6db339e9..000000000 --- a/doc_src/function.txt +++ /dev/null @@ -1,101 +0,0 @@ -\section function function - create a function - -\subsection function-synopsis Synopsis -\fish{synopsis} -function NAME [OPTIONS]; BODY; end -\endfish - -\subsection function-description Description - -`function` creates a new function `NAME` with the body `BODY`. - -A function is a list of commands that will be executed when the name of the function is given as a command. - -The following options are available: - -- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES. - -- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description. - -- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for `complete` for more information. - -- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt. - -- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value. - -- `-j PGID` or `--on-job-exit PGID` tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution. - -- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process - with process ID PID exits. Instead of a PID, for backward compatibility, - "`%self`" can be specified as an alias for `$fish_pid`, and the function will be run when the - current fish instance exits. - -- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP). - -- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function. - -- `-V` or `--inherit-variable NAME` snapshots the value of the variable `NAME` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the `function notify` example below for how this might be used. - -If the user enters any additional arguments after the function, they are inserted into the environment variable array `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option. - -By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the emit builtin. Fish generates the following named events: - -- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed. - -- `fish_command_not_found`, which is emitted whenever a command lookup failed. - -- `fish_preexec`, which is emitted right before executing an interactive command. The commandline is passed as the first parameter. - - Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines. - -- `fish_postexec`, which is emitted right after executing an interactive command. The commandline is passed as the first parameter. - - Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines. - -- `fish_exit` is emitted right before fish exits. - -\subsection function-example Example - -\fish -function ll - ls -l $argv -end -\endfish - -will run the `ls` command, using the `-l` option, while passing on any additional files and switches to `ls`. - -\fish -function mkdir -d "Create a directory and set CWD" - command mkdir $argv - if test $status = 0 - switch $argv[(count $argv)] - case '-*' - - case '*' - cd $argv[(count $argv)] - return - end - end -end -\endfish - -This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created. - -\fish -function notify - set -l job (jobs -l -g) - or begin; echo "There are no jobs" >&2; return 1; end - - function _notify_job_$job --on-job-exit $job --inherit-variable job - echo -n \a # beep - functions -e _notify_job_$job - end -end -\endfish - -This will beep when the most recent job completes. - - -\subsection function-notes Notes - -Note that events are only received from the current fish process as there is no way to send events from one fish process to another. diff --git a/doc_src/functions.txt b/doc_src/functions.txt deleted file mode 100644 index 2b4b067e8..000000000 --- a/doc_src/functions.txt +++ /dev/null @@ -1,69 +0,0 @@ -\section functions functions - print or erase functions - -\subsection functions-synopsis Synopsis -\fish{synopsis} -functions [ -a | --all ] [ -n | --names ] -functions [ -D | --details ] [ -v ] FUNCTION -functions -c OLDNAME NEWNAME -functions -d DESCRIPTION FUNCTION -functions [ -e | -q ] FUNCTIONS... -\endfish - -\subsection functions-description Description - -`functions` prints or erases functions. - -The following options are available: - -- `-a` or `--all` lists all functions, even those whose name starts with an underscore. - -- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function. - -- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function. - -- `-e` or `--erase` causes the specified functions to be erased. - -- `-D` or `--details` reports the path name where each function is defined or could be autoloaded, `stdin` if the function was defined interactively or on the command line or by reading stdin, and `n/a` if the function isn't available. If the `--verbose` option is also specified then five lines are written: - - -# the pathname as already described, - -# `autoloaded`, `not-autoloaded` or `n/a`, - -# the line number within the file or zero if not applicable, - -# `scope-shadowing` if the function shadows the vars in the calling function (the normal case if it wasn't defined with `--no-scope-shadowing`), else `no-scope-shadowing`, or `n/a` if the function isn't defined, - -# the function description minimally escaped so it is a single line or `n/a` if the function isn't defined. - -You should not assume that only five lines will be written since we may add additional information to the output in the future. - -- `-n` or `--names` lists the names of all defined functions. - -- `-q` or `--query` tests if the specified functions exist. - -- `-v` or `--verbose` will make some output more verbose. - -- `-H` or `--handlers` will show all event handlers. - -- `-t` or `--handlers-type TYPE` will show all event handlers matching the given type - -The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output. - -If any non-option parameters are given, the definition of the specified functions are printed. - -Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions. - -Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function. - -Only one function's description can be changed in a single invocation of `functions -d`. - -The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option. - - -\subsection functions-example Examples -\fish -functions -n -# Displays a list of currently-defined functions - -functions -c foo bar -# Copies the 'foo' function to a new function called 'bar' - -functions -e bar -# Erases the function `bar` -\endfish diff --git a/doc_src/help.txt b/doc_src/help.txt deleted file mode 100644 index 9665dba27..000000000 --- a/doc_src/help.txt +++ /dev/null @@ -1,23 +0,0 @@ -\section help help - display fish documentation - -\subsection help-synopsis Synopsis -\fish{synopsis} -help [SECTION] -\endfish - -\subsection help-description Description - -`help` displays the fish help documentation. - -If a `SECTION` is specified, the help for that command is shown. - -If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser. - -If you prefer to use a different browser (other than as described above) for fish help, you can set the fish_help_browser variable. This variable may be set as an array, where the first element is the browser command and the rest are browser options. - -Note that most builtin commands display their help in the terminal when given the `--help` option. - - -\subsection help-example Example - -`help fg` shows the documentation for the `fg` builtin. diff --git a/doc_src/history.txt b/doc_src/history.txt deleted file mode 100644 index 192bfd191..000000000 --- a/doc_src/history.txt +++ /dev/null @@ -1,79 +0,0 @@ -\section history history - Show and manipulate command history - -\subsection history-synopsis Synopsis -\fish{synopsis} -history search [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ -R | --reverse ] [ "search string"... ] -history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"... -history merge -history save -history clear -history ( -h | --help ) -\endfish - -\subsection history-description Description - -`history` is used to search, delete, and otherwise manipulate the history of interactive commands. - -The following operations (sub-commands) are available: - -- `search` returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say `history search` if you wish to search for one of the subcommands. The `--contains` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the `--reverse` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout. - -- `delete` deletes history items. Without the `--prefix` or `--contains` options, the exact match of the specified text will be deleted. If you don't specify `--exact` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports `--exact --case-sensitive` deletion. - -- `merge` immediately incorporates history changes from other sessions. Ordinarily `fish` ignores history changes from sessions started after the current one. This command applies those changes immediately. - -- `save` immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user. - -- `clear` clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless `builtin history` is used. - -The following options are available: - -These flags can appear before or immediately after one of the sub-commands listed above. - -- `-C` or `--case-sensitive` does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive. - -- `-c` or `--contains` searches or deletes items in the history that contain the specified text string. This is the default for the `--search` flag. This is not currently supported by the `delete` subcommand. - -- `-e` or `--exact` searches or deletes items in the history that exactly match the specified text string. This is the default for the `delete` subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the `-C` or `--case-sensitive` flag. - -- `-p` or `--prefix` searches or deletes items in the history that begin with the specified text string. This is not currently supported by the `--delete` flag. - -- `-t` or `--show-time` prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format `# %c%n`. You can specify another format; e.g., `--show-time="%Y-%m-%d %H:%M:%S "` or `--show-time="%a%I%p"`. The short option, `-t`, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including `%s` to get the raw UNIX seconds since the epoch. - -- `-z` or `--null` causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by `read -z` to correctly handle multiline history entries. - -- `-` `-n ` or `--max=` limits the matched history items to the first "n" matching entries. This is only valid for `history search`. - -- `-R` or `--reverse` causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest. - -- `-h` or `--help` display help for this command. - -\subsection history-examples Example - -\fish -history clear -# Deletes all history items - -history search --contains "foo" -# Outputs a list of all previous commands containing the string "foo". - -history delete --prefix "foo" -# Interactively deletes commands which start with "foo" from the history. -# You can select more than one entry by entering their IDs separated by a space. -\endfish - -\subsection customizing-the-histfile Customizing the name of the history file - -By default interactive commands are logged to `$XDG_DATA_HOME/fish/fish_history` (typically `~/.local/share/fish/fish_history`). - -You can set the `fish_history` variable to another name for the current shell session. The default value (when the variable is unset) is `fish` which corresponds to `$XDG_DATA_HOME/fish/fish_history`. If you set it to e.g. `fun`, the history would be written to `$XDG_DATA_HOME/fish/fun_history`. An empty string means history will not be stored at all. This is similar to the private session features in web browsers. - -You can change `fish_history` at any time (by using `set -x fish_history "session_name"`) and it will take effect right away. If you set it to `"default"`, it will use the default session name (which is `"fish"`). - -Other shells such as bash and zsh use a variable named `HISTFILE` for a similar purpose. Fish uses a different name to avoid conflicts and signal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than `fish` or `default` it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensitive history when giving a presentation. - -\subsection history-notes Notes - -If you specify both `--prefix` and `--contains` the last flag seen is used. - -Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than `history search` you can type `history --search`. Those long options are deprecated and will be removed in a future release. diff --git a/doc_src/if.txt b/doc_src/if.txt deleted file mode 100644 index 61ba387c1..000000000 --- a/doc_src/if.txt +++ /dev/null @@ -1,39 +0,0 @@ -\section if if - conditionally execute a command - -\subsection if-synopsis Synopsis -\fish{synopsis} -if CONDITION; COMMANDS_TRUE...; -[else if CONDITION2; COMMANDS_TRUE2...;] -[else; COMMANDS_FALSE...;] -end -\endfish - -\subsection if-description Description - -`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If the exit status is not 0 and `else` is given, `COMMANDS_FALSE` will be executed. - -You can use `and` or `or` in the condition. See the second example below. - -The exit status of the last foreground command to exit can always be accessed using the $status variable. - -\subsection if-example Example - -The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`. - -\fish -if test -f foo.txt - echo foo.txt exists -else if test -f bar.txt - echo bar.txt exists -else - echo foo.txt and bar.txt do not exist -end -\endfish - -The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable -\fish -if test -f foo.txt - and test -r foo.txt - echo "foo.txt exists and is readable" -end -\endfish diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in deleted file mode 100644 index 5defee884..000000000 --- a/doc_src/index.hdr.in +++ /dev/null @@ -1,1641 +0,0 @@ -/** -\mainpage Documentation -\htmlonly[block] -
- -
-\endhtmlonly -@toc@ - -\htmlonly[block] -
-
-
-

Documentation

-\endhtmlonly - - -\section introduction Introduction - -This is the documentation for *fish* the f riendly i nteractive sh ell. - -A shell is a commandline interpreter. It reads text input from the commandline and interpretes it as commands to operating system, see: What is a Shell. - -So shells serve as user-interface between applications and the operating system. There are many different shells. They differ on how this interface is implemented. *fish* specializes in the following ways: - -- Extensive UI: *fish* supports the user with syntax highlighting, autosuggestions, tab completions and selections lists, that can be navigated and filtered, see: Autosuggestions and Tab Completions. - -- No further configuration is needed: *fish* comes preconfigured so that it will be an efficient helper on the commandline out of the box. - -- Add new commands easily: in *fish* new commands can be added on the fly. The syntax is easy to learn and there is no administrative overhead, see: Functions. - -- Interactive shell: *fish* focuses on commands that will be run in an interactive session: While it supports job control for external commands, its own commands share the process of the shell, that started them. - -<-
- - -\section shell What is a Shell - -This section is about the basics of shells. *fish* is a shell and shells have a lot in common: - -- Shell Standards: Why shells adjust to standards -- Manual Pages: Commands usually come with a standardized manual page -- Command Syntax: Shell commands have a standard syntax -- Commands versus Programs: Commands differ from normal programs -- Shebang Line: How the shell knows the language of a script - -\subsection shell-standards Shell Standards - -A shell is an interface to the operating system that reads from the commandline of a terminal. A shell's task is to identify and interpret commands. The commands can come from different applications and can be written in different programming languages. - -This can only work smoothly if shells adapt to some common standards. For shells there is the POSIX standard, see Command-line interpreters. `fish` tries to satisfy the POSIX standard wherever it does not get into the way of its own design principles, see `fish` Design. - -\subsection man-page Manual Pages - -There is a common standard on how to receive help on shell commands: applications provide a manual page to their commands that can be opened with the `man` command: - -\fish ->man COMMAND -\endfish - -This convention helps to make sure help can be found on commands no matter where they originate from. *fish*'s internal commands all come with a manual page. - -\subsection shell-syntax Command Syntax - -Shells also support some common syntax for executing commands. That way a command can be started in the same way, regardless of the application, where it comes from, and the shell, where it is executed in. - -The pattern below is a basic pattern: - -\fish -COMMAND [OPTIONS] ARGUMENTS -\endfish - -- `COMMAND`: the name of the executeable - -- `[OPTIONS]`: options can change the behaviour of a command - -- `ARGUMENTS`: input to the command - -For external commands the executable is usually stored on file and the file path must be included in the variable `$PATH`, so that the file can be found: see Special Variables. - -Options come in two forms: a short name, that is a hyphen with a single letter; or a long name, consisting of two hyphens with words connected by hyphens. Example: `-h` and `--help` are often used to print a help message. Options are a fixed set, described in the manual pages of the command, see Manual Pages - -Arguments are the arbitrary input part of a command: often it is a file or directory name, sometimes it is a string or a list. - -Example: - -\fish ->echo -s Hallo World! -HalloWorld! -\endfish - -- both `Hallo` and `World!` are arguments to the echo command -- `-s` is an option that suppresses spaces in the output of the command - -\subsection shell-programming Commands versus Programs - -Programs in other languages can often be regarded as black boxes: they get complex input and return complex output. Sometimes they produce side effects such as writing to a file or reporting an error, but the emphasis is on: arguments in and return values out: - -Arguments → |Program| → Return Values - -Shell commands are different: - -- the side effects take the center of the stage: they transform an input stream of data into an output stream of data. Both of these streams are usually the terminal, but they can be redirected. -- the arguments become options or switches paired with data: the switches influence the behaviour of the command -- the return value shrinks to an exit code: this exit code is 0 when the command executes normally and between 1 and 255 otherwise. - - -
Input Stream ⇒|Shell Command|⇒ Output Stream -
switch and data as arguments →→ exit code -
- -This leads to another way of programming and especially of combining commands: - -There are two ways to combine shell commands: - -- Commands can pass on their streams to each other: one command takes the output stream of another command as its input stream and the two commands execute in parallel. This is called piping, see Piping. - -Example: - -\fish -# Every line of the `ls` command is immediatelly passed on to the `grep` command ->ls -l | grep "my topic" -\endfish - -- Commands can pass on all their output as a chunk: the output stream of one command is bundled and taken as data argument for the second command. This is called command substitution, see Command Substitution. - -Example: -\fish -# the output of the inner `ls` command is taken as the input argument for the outer `echo` command ->echo (ls a*) -\endfish - -\subsection shebang-line Shebang Line - -Since script for shell commands can be written in many different languages, they need to carry information about what interpreter is needed to execute them: For this they are expected to have a first line, the shebang line, which names an executable for this purpose: - -Example: - -A scripts written in `bash` it would need a first line like this: - -``` -#!/bin/bash -``` - -- this line tells the shell to execute the file with the *bash* interpreter, that is located at the path `/bin/bash`. - -For a script, written in another language, just replace the interpreter `/bin/bash` with the language interpreter of that other language (for example `/bin/python` for a `python` script) - -This line is only needed when scripts are executed by another interpreter, so for *fish* internal commands, that are executed by *fish* the shebang line is not necessary. - -<-
- - -\section install Installation and Start - -This section is on how to install, uninstall, start and exit a *fish* shell and on how to make *fish* the default shell: - -- Install: How to install *fish* -- Default Shell: How to switch to *fish* as the default shell -- Starting and Exiting: How to start and exit a *fish* shell -- Uninstall: How to uninstall *fish* -- Executing Bash: How to execute *bash* commands in *fish* - -\subsection installation Installation - -Instructions for installing fish are on the fish homepage. Search that page for "Go fish". - -To install the development version of *fish* see the instructions at the project's GitHub page. - -\subsection default-shell Default Shell - -You can make *fish* your default shell by adding *fish*'s executable in two places: -- add `/usr/local/bin/fish` to `/etc/shells` -- change your default shell with `chsh -s` to `/usr/local/bin/fish` - -For for detailed instructions see Switching to *fish*. - -\subsection uninstall Uninstalling - -For uninstalling *fish*: see FAQ: Uninstalling *fish* - -\subsection start Starting and Exiting - -Once *fish* has been installed, open a terminal. If *fish* is not the default shell: - -- Enter `fish` to start a *fish* shell: - -\fish ->fish -\endfish - -- Enter `exit` to exit a *fish* shell: - -\fish ->exit -\endfish - -\subsection bash Executing Bash - -If *fish* is your default shell and you want to copy commands from the internet, that are written in a different shell language, *bash* for example, you can proceed in the following way: - -Consider, that `bash` is also a command. With `man bash` you can see that there are two ways to do this: - -- `bash` has a switch `-c` to read from a string: - -\fish ->bash -c SomeBashCommand -\endfish - -- or `bash` without a switch, opens a *bash* shell that you can use and `exit` afterwards. - -<-
- - -\section syntax Syntax overview - -Shells like fish are used by giving them commands. Every `fish` command follows the same simple syntax. - -A command is executed by writing the name of the command followed by any arguments. - -Example: - -\fish -echo hello world -\endfish - -This calls the `echo` command. `echo` is a command which will write its arguments to the screen. In the example above, the output will be 'hello world'. Everything in fish is done with commands. There are commands for performing a set of commands multiple times, commands for assigning variables, commands for treating a group of commands as a single command, etc.. And every single command follows the same simple syntax. - -If you want to find out more about the echo command used above, read the manual page for the echo command by writing: `man echo` - -`man` is a command for displaying a manual page on a given topic. The man command takes the name of the manual page to display as an argument. There are manual pages for almost every command on most computers. There are also manual pages for many other things, such as system libraries and important files. - -Every program on your computer can be used as a command in `fish`. If the program file is located in one of the directories in the `PATH`, it is sufficient to type the name of the program to use it. Otherwise the whole filename, including the directory (like `/home/me/code/checkers/checkers` or `../checkers`) has to be used. - -Here is a list of some useful commands: - -- `cd`, change the current directory -- `ls`, list files and directories -- `man`, display a manual page on the screen -- `mv`, move (rename) files -- `cp`, copy files -- `open`, open files with the default application associated with each filetype -- `less`, list the contents of files - -Commands and parameters are separated by the space character ' '. Every command ends with either a newline (i.e. by pressing the return key) or a semicolon '`;`'. More than one command can be written on the same line by separating them with semicolons. - -A switch is a very common special type of argument. Switches almost always start with one or more hyphens '`-`' and alter the way a command operates. For example, the '`ls`' command usually lists all the files and directories in the current working directory, but by using the '`-l`' switch, the behavior of '`ls`' is changed to not only display the filename, but also the size, permissions, owner and modification time of each file. - -Switches differ between commands and are documented in the manual page for each command. Some switches are common to most command though, for example '`--help`' will usually display a help text, '`-i`' will often turn on interactive prompting before taking action, while '`-f`' will turn it off. - - -\subsection quotes Quotes - -Sometimes features such as parameter expansion and character escapes get in the way. When that happens, the user can write a parameter within quotes, either `'` (single quote) or `"` (double quote). There is one important difference between single quoted and double quoted strings: When using double quoted string, variable expansion still takes place. Other than that, no other kind of expansion (including brace expansion and parameter expansion) will take place, the parameter may contain spaces, and escape sequences are ignored. The only backslash escape accepted within single quotes is `\'`, which escapes a single quote and `\\`, which escapes the backslash symbol. The only backslash escapes accepted within double quotes are `\"`, which escapes a double quote, `\$`, which escapes a dollar character, `\` followed by a newline, which deletes the backslash and the newline, and lastly `\\`, which escapes the backslash symbol. Single quotes have no special meaning within double quotes and vice versa. - -Example: - -\fish -rm "cumbersome filename.txt" -\endfish - -Will remove the file 'cumbersome filename.txt', while - -\fish -rm cumbersome filename.txt -\endfish - -would remove the two files 'cumbersome' and 'filename.txt'. - - -\subsection escapes Escaping characters - -Some characters can not be written directly on the command line. For these characters, so called escape sequences are provided. These are: - -- '\\a' represents the alert character -- '\\b' represents the backspace character -- '\\e' represents the escape character -- '\\f' represents the form feed character -- '\\n' represents a newline character -- '\\r' represents the carriage return character -- '\\t' represents the tab character -- '\\v' represents the vertical tab character -- '\\ ' escapes the space character -- '\\$' escapes the dollar character -- '\\\\' escapes the backslash character -- '\\*' escapes the star character -- '\\?' escapes the question mark character -- '\\~' escapes the tilde character -- '\\#' escapes the hash character -- '\\(' escapes the left parenthesis character -- '\\)' escapes the right parenthesis character -- '\\{' escapes the left curly bracket character -- '\\}' escapes the right curly bracket character -- '\\[' escapes the left bracket character -- '\\]' escapes the right bracket character -- '\\\<' escapes the less than character -- '\\\>' escapes the more than character -- '\\^' escapes the circumflex character -- '\\&' escapes the ampersand character -- '\\|' escapes the vertical bar character -- '\\;' escapes the semicolon character -- '\\"' escapes the quote character -- '\\'' escapes the apostrophe character - -- '\\xxx', where xx is a hexadecimal number, represents the ascii character with the specified value. For example, `\x9` is the tab character. - -- '\\Xxx', where xx is a hexadecimal number, represents a byte of data with the specified value. If you are using a multibyte encoding, this can be used to enter -invalid strings. Only use this if you know what you are doing. - -- '\\ooo', where ooo is an octal number, represents the ascii character with the specified value. For example, `\011` is the tab character. - -- '\\uxxxx', where xxxx is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, `\u9` is the tab character. - -- '\\Uxxxxxxxx', where xxxxxxxx is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, `\U9` is the tab character. - -- '\\cx', where x is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, `\ci` is the tab character - - -\subsection redirects Input/Output (IO) redirection - -Most programs use three input/output (IO) streams, each represented by a number called a file descriptor (FD). These are: - -- Standard input, FD 0, for reading, defaults to reading from the keyboard. - -- Standard output, FD 1, for writing, defaults to writing to the screen. - -- Standard error, FD 2, for writing errors and warnings, defaults to writing to the screen. - -The reason for providing for two output file descriptors is to allow separation of errors and warnings from regular program output. - -Any file descriptor can be directed to a different output than its default through a simple mechanism called a redirection. - -An example of a file redirection is `echo hello > output.txt`, which directs the output of the echo command to the file output.txt. - -- To read standard input from a file, write `DESTINATION` -- To write standard error to a file, write `2>DESTINATION` -- To append standard output to a file, write `>>DESTINATION_FILE` -- To append standard error to a file, write `2>>DESTINATION_FILE` - -- To not overwrite ("clobber") an existing file, write '>?DESTINATION' or '2>?DESTINATION' - -`DESTINATION` can be one of the following: - -- A filename. The output will be written to the specified file. - -- An ampersand (`&`) followed by the number of another file descriptor. The output will be written to that file descriptor instead. - -- An ampersand followed by a minus sign (`&-`). The file descriptor will be closed. - -Example: - -To redirect both standard output and standard error to the file 'all_output.txt', you can write `echo Hello > all_output.txt 2>&1`. - -Any file descriptor can be redirected in an arbitrary way by prefixing the redirection with the file descriptor. - -- To redirect input of FD N, write `NDESTINATION` -- To append the output of FD N to a file, write `N>>DESTINATION_FILE` - -Example: `echo Hello 2>output.stderr` writes the standard error (file descriptor 2) of the target program to `output.stderr`. - -\subsection piping Piping - -The user can string together multiple commands into a so called pipeline. This means that the standard output of one command will be read in as standard input into the next command. This is done by separating the commands by the pipe character '`|`'. For example - -\fish -cat foo.txt | head -\endfish - -will call the `cat` program with the parameter 'foo.txt', which will print the contents of the file 'foo.txt'. The contents of foo.txt will then be filtered through the program 'head', which will pass on the first ten lines of the file to the screen. For more information on how to combine commands through pipes, read the manual pages of the commands you want to use using the `man` command. If you want to find out more about the `cat` program, type `man cat`. - -Pipes usually connect file descriptor 1 (standard output) of the first process to file descriptor 0 (standard input) of the second process. It is possible to use a different output file descriptor by prepending the desired FD number and then output redirect symbol to the pipe. For example: - -\fish -make fish 2>| less -\endfish - -will attempt to build the fish program, and any errors will be shown using the less pager. - - -\subsection syntax-background Background jobs - -When you start a job in `fish`, `fish` itself will pause, and give control of the terminal to the program just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an \& (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface. - -Example: - -\fish -emacs & -\endfish - -will start the emacs text editor in the background. - - -\subsection syntax-job-control Job control - -Most programs allow you to suspend the program's execution and return control to `fish` by pressing @key{Control,Z} (also referred to as `^Z`). Once back at the `fish` commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the `fg` (foreground) command. - -If you instead want to put a suspended job into the background, use the `bg` command. - -To get a listing of all currently started jobs, use the `jobs` command. - - -\subsection syntax-function Functions - -Functions are programs written in the fish syntax. They group together one or more commands and their arguments using a single name. It can also be used to start a specific command with additional arguments. - -For example, the following is a function definition that calls the command `ls` with the argument '`-l`' to print a detailed listing of the contents of the current directory: - -\fish -function ll - ls -l $argv -end -\endfish - -The first line tells fish that a function by the name of `ll` is to be defined. To use it, simply write `ll` on the commandline. The second line tells fish that the command `ls -l $argv` should be called when `ll` is invoked. '`$argv`' is an array variable, which always contains all arguments sent to the function. In the example above, these are simply passed on to the `ls` command. For more information on functions, see the documentation for the function builtin. - - -\subsubsection syntax-function-wrappers Defining aliases - -One of the most common uses for functions is to slightly alter the behavior of an already existing command. For example, one might want to redefine the `ls` command to display colors. The switch for turning on colors on GNU systems is '`--color=auto`'. An alias, or wrapper, around `ls` might look like this: - -\fish -function ls - command ls --color=auto $argv -end -\endfish - -There are a few important things that need to be noted about aliases: - -- Always take care to add the `$argv` variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command. - -- If the alias has the same name as the aliased command, it is necessary to prefix the call to the program with `command` in order to tell fish that the function should not call itself, but rather a command with the same name. Failing to do so will cause infinite recursion bugs. - -- Autoloading isn't applicable to aliases. Since, by definition, the function is created at the time the alias command is executed. You cannot autoload aliases. - -To easily create a function of this form, you can use the alias command. - - -\subsubsection syntax-function-autoloading Autoloading functions - -Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This method of defining functions has several advantages. An autoloaded function becomes available automatically to all running shells. If the function definition is changed, all running shells will automatically reload the altered version. Startup time and memory usage is improved, etc. - -Fish automatically searches through any directories in the array variable `$fish_function_path`, and any functions defined are automatically loaded when needed. A function definition file must have a filename consisting of the name of the function plus the suffix '`.fish`'. - -By default, Fish searches the following for functions, using the first available file that it finds: -- A directory for end-users to keep their own functions, usually `~/.config/fish/functions` (controlled by the `XDG_CONFIG_HOME` environment variable). -- A directory for systems administrators to install functions for all users on the system, usually `/etc/fish/functions`. -- A directory for third-party software vendors to ship their own functions for their software, usually `/usr/share/fish/vendor_functions.d`. -- The functions shipped with fish, usually installed in `/usr/share/fish/functions`. - -These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. - -This wide search may be confusing. If you are unsure, your functions probably belong in `~/.config/fish/functions`. - -It is very important that function definition files only contain the definition for the specified function and nothing else. Otherwise, it is possible that autoloading a function files requires that the function already be loaded, which creates a circular dependency. - -Autoloading also won't work for event handlers, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the event handlers section for more information. - -Autoloading is not applicable to functions created by the `alias` command. For functions simple enough that you prefer to use the `alias` command to define them you'll need to put those commands in your `~/.config/fish/config.fish` script or some other script run when the shell starts. - -If you are developing another program, you may wish to install functions which are available for all users of the fish shell on a system. They can be installed to the "vendor" functions directory. As this path may vary from system to system, the `pkgconfig` framework should be used to discover this path with the output of `pkg-config --variable functionsdir fish`. - - -\subsubsection syntax-conditional Conditional execution of code and flow control - -There are four fish builtins that let you execute commands only if a specific criterion is met. These builtins are `if`, `switch`, `and` and `or`. - -The `switch` command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for switch for more information. - -The other conditionals use the exit status of a command to decide if a command or a block of commands should be executed. See the documentation for `if`, `and` and `or` for more information. - - -\subsection syntax-words Some common words - -This is a short explanation of some of the commonly used words in fish. - -- argument a parameter given to a command - -- builtin a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands. - -- command a program that the shell can run. - -- function a block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command. - -- job a running pipeline or command - -- pipeline a set of commands stringed together so that the output of one command is the input of the next command - -- redirection an operation that changes one of the input/output streams associated with a job - -- switch a special flag sent as an argument to a command that will alter the behavior of the command. A switch almost always begins with one or two hyphens. - - -\section docs Help - -`fish` has an extensive help system. Use the `help` command to obtain help on a specific subject or command. For instance, writing `help syntax` displays the syntax section of this documentation. - -`fish` also has man pages for its commands. For example, `man set` will show the documentation for `set` as a man page. - -Help on a specific builtin can also be obtained with the `-h` parameter. For instance, to obtain help on the `fg` builtin, either type `fg -h` or `help fg`. - - -\section autosuggestions Autosuggestions - -fish suggests commands as you type, based on command history, completions, and valid file paths. As you type commands, you will see a suggestion offered after the cursor, in a muted gray color (which can be changed with the `fish_color_autosuggestion` variable). - -To accept the autosuggestion (replacing the command line contents), press right arrow or @key{Control,F}. To accept the first suggested word, press @key{Alt,→,Right} or @key{Alt,F}. If the autosuggestion is not what you want, just ignore it: it won't execute unless you accept it. - -Autosuggestions are a powerful way to quickly summon frequently entered commands, by typing the first few characters. They are also an efficient technique for navigating through directory hierarchies. - - -\section completion Tab completion - -Tab completion is one of the most time saving features of any modern shell. By tapping the tab key, the user asks `fish` to guess the rest of the command or parameter that the user is currently typing. If `fish` can only find one possible completion, `fish` will write it out. If there is more than one completion, `fish` will write out the longest prefix that all completions have in common. If the completions differ on the first character, a list of all possible completions is printed. The list features descriptions of the completions and if the list doesn't fit the screen, it is scrollable by using the arrow keys, the page up/page down keys, the tab key or the space bar. - -If the list is visible, pressing control-S (or the `pager-toggle-search` binding) will allow filtering the list. Shift-tab (or the `complete-and-search` binding) will trigger completion with the search field immediately visible. - -These are the general purpose tab completions that `fish` provides: - -- Completion of commands (builtins, functions and regular programs). - -- Completion of shell variable names. - -- Completion of usernames for tilde expansion. - -- Completion of filenames, even on strings with wildcards such as '`*`', '`**`' and '`?`'. - -`fish` provides a large number of program specific completions. Most of these completions are simple options like the `-l` option for `ls`, but some are more advanced. The latter include: - -- The programs `man` and `whatis` show all installed manual pages as completions. - -- The `make` program uses all targets in the Makefile in the current directory as completions. - -- The `mount` command uses all mount points specified in fstab as completions. - -- The `ssh` command uses all hosts that are stored in the known_hosts file as completions. (See the ssh documentation for more information) - -- The `su` command uses all users on the system as completions. - -- The `apt-get`, `rpm` and `yum` commands use all installed packages as completions. - - -\subsection completion-own Writing your own completions - -Specifying your own completions is not difficult. To specify a completion, use the `complete` command. `complete` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program `myprog`, one would start the completion command with `complete -c myprog ...` - -To provide a list of possible completions for myprog, use the `-a` switch. If `myprog` accepts the arguments start and stop, this can be specified as `complete -c myprog -a 'start stop'`. The argument to the `-a` switch is always a single string. At completion time, it will be tokenized on spaces and tabs, and variable expansion, command substitution and other forms of parameter expansion will take place. - -`fish` has a special syntax to support specifying switches accepted by a command. The switches `-s`, `-l` and `-o` are used to specify a short switch (single character, such as `-l`), a gnu style long switch (such as '`--color`') and an old-style long switch (like '`-shuffle`'), respectively. If the command 'myprog' has an option '-o' which can also be written as '`--output`', and which can take an additional value of either 'yes' or 'no', this can be specified by writing: - -\fish -complete -c myprog -s o -l output -a "yes no" -\endfish - -There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc.. For a complete description of the various switches accepted by the `complete` command, see the documentation for the complete builtin, or write `complete --help` inside the `fish` shell. - -For examples of how to write your own complex completions, study the completions in `/usr/share/fish/completions`. (The exact path depends on your chosen installation prefix and may be slightly different) - - -\subsection completion-func Useful functions for writing completions - -`fish` ships with several functions that are very useful when writing command specific completions. Most of these functions name begins with the string '`__fish_`'. Such functions are internal to `fish` and their name and interface may change in future fish versions. Still, some of them may be very useful when writing completions. A few of these functions are described here. Be aware that they may be removed or changed in future versions of fish. - -Functions beginning with the string `__fish_print_` print a newline separated list of strings. For example, `__fish_print_filesystems` prints a list of all known file systems. Functions beginning with `__fish_complete_` print out a newline separated list of completions with descriptions. The description is separated from the completion by a tab character. - -- `__fish_complete_directories STRING DESCRIPTION` performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION. - -- `__fish_complete_path STRING DESCRIPTION` performs path completion on STRING, giving them the description DESCRIPTION. - -- `__fish_complete_groups` prints a list of all user groups with the groups members as description. - -- `__fish_complete_pids` prints a list of all processes IDs with the command name as description. - -- `__fish_complete_suffix SUFFIX` performs file completion allowing only files ending in SUFFIX, with an optional description. - -- `__fish_complete_users` prints a list of all users with their full name as description. - -- `__fish_print_filesystems` prints a list of all known file systems. Currently, this is a static list, and not dependent on what file systems the host operating system actually understands. - -- `__fish_print_hostnames` prints a list of all known hostnames. This functions searches the fstab for nfs servers, ssh for known hosts and checks the `/etc/hosts` file. - -- `__fish_print_interfaces` prints a list of all known network interfaces. - -- `__fish_print_packages` prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages. - - -\subsection completion-path Where to put completions - -Completions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. Fish automatically searches through any directories in the array variable `$fish_complete_path`, and any completions defined are automatically loaded when needed. A completion file must have a filename consisting of the name of the command to complete and the suffix '`.fish`'. - -By default, Fish searches the following for completions, using the first available file that it finds: -- A directory for end-users to keep their own completions, usually `~/.config/fish/completions` (controlled by the `XDG_CONFIG_HOME` environment variable); -- A directory for systems administrators to install completions for all users on the system, usually `/etc/fish/completions`; -- A directory for third-party software vendors to ship their own completions for their software, usually `/usr/share/fish/vendor_completions.d`; -- The completions shipped with fish, usually installed in `/usr/share/fish/completions`; and -- Completions automatically generated from the operating system's manual, usually stored in `~/.local/share/fish/generated_completions`. - -These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. - -This wide search may be confusing. If you are unsure, your completions probably belong in `~/.config/fish/completions`. - -If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in Further help and development. - -If you are developing another program and would like to ship completions with your program, install them to the "vendor" completions directory. As this path may vary from system to system, the `pkgconfig` framework should be used to discover this path with the output of `pkg-config --variable completionsdir fish`. - - -\section expand Parameter expansion (Globbing) - -When an argument for a program is given on the commandline, it undergoes the process of parameter expansion before it is sent on to the command. Parameter expansion is a powerful mechanism that allows you to expand the parameter in various ways, including performing wildcard matching on files, inserting the value of a shell variable into the parameter or even using the output of another command as a parameter list. - - -\subsection expand-wildcard Wildcards - -If a star (`*`) or a question mark (`?`) is present in the parameter, `fish` attempts to match the given parameter to any files in such a way that: - -- `?` can match any single character except '/'. - -- `*` can match any string of characters not containing '/'. This includes matching an empty string. - -- `**` matches any string of characters. This includes matching an empty string. The matched string may include the `/` character; that is, it recurses into subdirectories. Note that augmenting this wildcard with other strings will not match files in the current working directory (`$PWD`) if you separate the strings with a slash ("/"). This is unlike other shells such as zsh. For example, `**\/*.fish` in zsh will match `.fish` files in the PWD but in fish will only match such files in a subdirectory. In fish you should type `**.fish` to match files in the PWD as well as subdirectories. - -Other shells, such as zsh, provide a rich glob syntax for restricting the files matched by globs. For example, `**(.)`, to only match regular files. Fish prefers to defer such features to programs, such as `find`, rather than reinventing the wheel. Thus, if you want to limit the wildcard expansion to just regular files the fish approach is to define and use a function. For example, - -\fish{cli-dark} -function ff --description 'Like ** but only returns plain files.' - # This also ignores .git directories. - find . \( -name .git -type d -prune \) -o -type f | \ - sed -n -e '/^\.\/\.git$/n' -e 's/^\.\///p' -end -\endfish - -You would then use it in place of `**` like this, `my_prog (ff)`, to pass only regular files in or below $PWD to `my_prog`. - -Wildcard matches are sorted case insensitively. When sorting matches containing numbers, consecutive digits are considered to be one element, so that the strings '1' '5' and '12' would be sorted in the order given. - -File names beginning with a dot are not considered when wildcarding unless a dot is specifically given as the first character of the file name. - -Examples: - -- `a*` matches any files beginning with an 'a' in the current directory. - -- `???` matches any file in the current directory whose name is exactly three characters long. - -- `**` matches any files and directories in the current directory and all of its subdirectories. - -Note that for most commands, if any wildcard fails to expand, the command is not executed, `$status` is set to nonzero, and a warning is printed. This behavior is consistent with setting `shopt -s failglob` in bash. There are exactly 3 exceptions, namely `set`, `count` and `for`. Their globs are permitted to expand to zero arguments, as with `shopt -s nullglob` in bash. - -Examples: -\fish -ls *.foo -# Lists the .foo files, or warns if there aren't any. - -set foos *.foo -if count $foos >/dev/null - ls $foos -end -# Lists the .foo files, if any. -\endfish - -\subsection expand-command-substitution Command substitution - -The output of a series of commands can be used as the parameters to another command. If a parameter contains a set of parenthesis, the text enclosed by the parenthesis will be interpreted as a list of commands. On expansion, this list is executed, and substituted by the output. If the output is more than one line long, each line will be expanded to a new parameter. Setting `IFS` to the empty string will disable line splitting. - -The exit status of the last run command substitution is available in the status variable if the substitution occurs in the context of a `set` command. - -Only part of the output can be used, see index range expansion for details. - -Fish has a default limit of 10 MiB on the amount of data a command substitution can output. If the limit is exceeded the entire command, not just the substitution, is failed and `$status` is set to 122. You can modify the limit by setting the `fish_read_limit` variable at any time including in the environment before fish starts running. If you set it to zero then no limit is imposed. This is a safety mechanism to keep the shell from consuming too much memory if a command outputs an unreasonable amount of data. Note that this limit also affects how much data the `read` command will process. - -Examples: - -\fish -echo (basename image.jpg .jpg).png -# Outputs 'image.png'. - -for i in *.jpg; convert $i (basename $i .jpg).png; end -# Convert all JPEG files in the current directory to the -# PNG format using the 'convert' program. - -begin; set -l IFS; set data (cat data.txt); end -# Set the `data` variable to the contents of 'data.txt' -# without splitting it into an array. -\endfish - - -\subsection expand-brace Brace expansion - -A comma separated list of characters enclosed in curly braces will be expanded so each element of the list becomes a new parameter. - -Examples: -\fish -echo input.{c,h,txt} -# Outputs 'input.c input.h input.txt' - -mv *.{c,h} src/ -# Moves all files with the suffix '.c' or '.h' to the subdirectory src. -\endfish - -A literal "{}" will not be used as a brace expansion: - -\fish -echo foo-{} -# Outputs foo-{} - -echo foo-{$undefinedvar} -# Output is an empty line - see the cartesian product section -\endfish - -If there is nothing between a brace and a comma or two commas, it's interpreted as an empty element. - -So: -\fish -echo {,,/usr}/bin -# Output /bin /bin /usr/bin -\endfish - -To use a "," as an element, quote or escape it. - -\subsection expand-variable Variable expansion - -A dollar sign followed by a string of characters is expanded into the value of the shell variable with the same name. For an introduction to the concept of shell variables, read the Shell variables section. - -Undefined and empty variables expand to nothing. - -To separate a variable name from text encase the variable within double-quotes or braces. - -Examples: -\fish -echo $HOME -# Prints the home directory of the current user. - -echo $nonexistentvariable -# Prints no output. - -echo The plural of $WORD is "$WORD"s -# Prints "The plural of cat is cats" when $WORD is set to cat. -echo The plural of $WORD is {$WORD}s -# ditto -\endfish - -Note that without the quotes or braces, fish will try to expand a variable called `$WORDs`, which may not exist. - -The latter syntax `{$WORD}` works by exploiting brace expansion. - - -In these cases, the expansion eliminates the string, as a result of the implicit cartesian product. - -If, in the example above, $WORD is undefined or an empty list, the "s" is not printed. However, it is printed, if $WORD is the empty string. - -Unlike all other expanions, variable expansion also happens in double quoted strings. Inside double quotes (`"these"`), variables will always expand to exactly one argument. If they are empty or undefined, it will result in an empty string. If they have one element, they'll expand to that element. If they have more than that, the elements will be joined with spaces. - -Outside of double quotes, variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple elements will expand to each of those elements separately. - -When two unquoted expansions directly follow each other, you need to watch out for expansions that expand to nothing. This includes undefined variables and empty lists, but also command substitutions with no output. See the cartesian product section for more information. - -The `$` symbol can also be used multiple times, as a kind of "dereference" operator (the `*` in C or C++), like in the following code: - -\fish -set foo a b c -set a 10; set b 20; set c 30 -for i in (seq (count $$foo)) - echo $$foo[$i] -end - -# Output is: -# 10 -# 20 -# 30 -\endfish - -When using this feature together with array brackets, the brackets will always match the innermost `$` dereference. Thus, `$$foo[5]` will always mean the fifth element of the `foo` variable should be dereferenced, not the fifth element of the doubly dereferenced variable `foo`. The latter can instead be expressed as `$$foo[1][5]`. - - -\subsection cartesian-product Cartesian Products - -Lists adjacent to other lists or strings are expanded as cartesian products: - -Examples: -\fish{cli-dark} ->_ echo {good,bad}" apples" -good apples bad apples - ->_ set -l a x y z ->_ set -l b 1 2 3 - ->_ echo $a$b -x1 y1 z1 x2 y2 z2 x3 y3 z3 - ->_ echo $a"-"$b -x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3 - ->_ echo {x,y,z}$b -x1 y1 z1 x2 y2 z2 x3 y3 z3 - ->_ echo {$b}word -1word 2word 3word - ->_ echo {$c}word -# Output is an empty line -\endfish - -Be careful when you try to use braces to separate variable names from text. The problem shown above can be avoided by wrapping the variable in double quotes instead of braces (`echo "$c"word`). - -This also happens after command substitution. Therefore strings might be eliminated. This can be avoided by making the inner command return a trailing newline. - -E.g. - -\fish{cli-dark} ->_ echo (printf '%s' '')banana # the printf prints literally nothing ->_ echo (printf '%s\n' '')banana # the printf prints just a newline, so the command substitution expands to an empty string -banana -# After command substitution, the previous line looks like: ->_ echo ""banana -\endfish - -Examples: -\fish{cli-dark} ->_ set b 1 2 3 ->_ echo (echo x)$b -x1 x2 x3 -\endfish - -\subsection expand-index-range Index range expansion - -Both command substitution and shell variable expansion support accessing only specific items by providing a set of indices in square brackets. It's often needed to access a sequence of elements. To do this, use the range operator '`..`' for this. A range '`a..b`', where range limits 'a' and 'b' are integer numbers, is expanded into a sequence of indices '`a a+1 a+2 ... b`' or '`a a-1 a-2 ... b`' depending on which of 'a' or 'b' is higher. The negative range limits are calculated from the end of the array or command substitution. Note that invalid indexes for either end are silently clamped to one or the size of the array as appropriate. - -Range expansion will go in reverse if the end element is earlier in the list than the start and forward if the end is later than the start, unless exactly one of the given indices is negative. This is to enable clamping without changing direction if the list has fewer elements than expected. - -Some examples: - -\fish -# Limit the command substitution output -echo (seq 10)[2..5] -# Uses elements from 2 to 5 -# Output is: 2 3 4 5 - -# Use overlapping ranges: -echo (seq 10)[2..5 1..3] -# Takes elements from 2 to 5 and then elements from 1 to 3 -# Output is: 2 3 4 5 1 2 3 - -# Reverse output -echo (seq 10)[-1..1] -# Uses elements from the last output line to -# the first one in reverse direction -# Output is: 10 9 8 7 6 5 4 3 2 1 - -# The command substitution has only one line, -# so these will result in empty output: -echo (echo one)[2..-1] -echo (echo one)[-3..1] -\endfish - -The same works when setting or expanding variables: - -\fish -# Reverse path variable -set PATH $PATH[-1..1] -# or -set PATH[-1..1] $PATH - -# Use only n last items of the PATH -set n -3 -echo $PATH[$n..-1] -\endfish - -Variables can be used as indices for expansion of variables, like so: -\fish -set index 2 -set letters a b c d -echo $letters[$index] # returns 'b' -\endfish -However using variables as indices for command substitution is currently not supported, so -\fish -echo (seq 5)[$index] # This won't work - -set sequence (seq 5) # It needs to be written on two lines like this. -echo $sequence[$index] # returns '2' -\endfish - -\subsection expand-home Home directory expansion - -The `~` (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone `~`, or a `~` followed by a slash, is expanded into the home directory of the process owner. - - -\subsection combine Combining different expansions - -All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created. - -When combining multiple parameter expansions, expansions are performed in the following order: - -- Command substitutions -- Variable expansions -- Bracket expansion -- Wildcard expansion - -Expansions are performed from right to left, nested bracket expansions are performed from the inside and out. - -Example: - -If the current directory contains the files 'foo' and 'bar', the command `echo a(ls){1,2,3} ` will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'. - - -\section identifiers Shell variable and function names - -The names given to shell objects such as variables and function names are known as "identifiers". Each type of identifier has rules that define the valid sequence of characters which compose the identifier. - -A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters. - -A function name cannot be empty. It may not begin with a hyphen ("-") and may not contain a slash ("/"). All other characters, including a space, are valid. - -A bind mode name (e.g., `bind -m abc ...`) is restricted to the rules for valid variable names. - - -\section variables Shell variables - -Shell variables are named pieces of data, which can be created, deleted and their values changed and used by the user. Variables may optionally be "exported", so that a copy of the variable is available to any subprocesses the shell creates. An exported variable is referred to as an "environment variable". - -To set a variable value, use the `set` command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters. - -Example: - -To set the variable `smurf_color` to the value `blue`, use the command `set smurf_color blue`. - -After a variable has been set, you can use the value of a variable in the shell through variable expansion. - -Example: - -To use the value of the variable `smurf_color`, write `$` (dollar symbol) followed by the name of the variable, like `echo Smurfs are usually $smurf_color`, which would print the result 'Smurfs are usually blue'. - - -\subsection variables-scope Variable scope - -There are three kinds of variables in fish: universal, global and local variables. Universal variables are shared between all fish sessions a user is running on one computer. Global variables are specific to the current fish session, but are not associated with any specific block scope, and will never be erased unless the user explicitly requests it using `set -e`. Local variables are specific to the current fish session, and associated with a specific block of commands, and is automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the commands `for`, `while` , `if`, `function`, `begin` or `switch`, and ends with the command `end`. The user can specify that a variable should have either global or local scope using the `-g/--global` or `-l/--local` switches. - -Variables can be explicitly set to be universal with the `-U` or `--universal` switch, global with the `-g` or `--global` switch, or local with the `-l` or `--local` switch. The scoping rules when creating or updating a variable are: - --# If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed. - --# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the variable scope is not changed. - --# If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the `-l` or `--local` flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global. - -There may be many variables with the same name, but different scopes. When using a variable, the variable scope will be searched from the inside out, i.e. a local variable will be used rather than a global variable with the same name, a global variable will be used rather than a universal variable with the same name. - -Example: - -The following code will not output anything: - -\fish -begin - # This is a nice local scope where all variables will die - set -l pirate 'There be treasure in them thar hills' -end - -echo $pirate -# This will not output anything, since the pirate was local -\endfish - - -\subsection variables-universal More on universal variables - -Universal variables are variables that are shared between all the users' fish sessions on the computer. Fish stores many of its configuration options as universal variables. This means that in order to change fish settings, all you have to do is change the variable value once, and it will be automatically updated for all sessions, and preserved across computer reboots and login/logout. - -To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them `set fish_color_cwd blue`. Since `fish_color_cwd` is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals. - -Universal variables are stored in the file `.config/fish/fishd.MACHINE_ID`, where MACHINE_ID is typically your MAC address. Do not edit this file directly, as your edits may be overwritten. Edit them through fish scripts or by using fish interactively instead. - -Do not append to universal variables in config.fish, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. - - -\subsection variables-functions Variable scope for functions - -When calling a function, all current local variables temporarily disappear. This shadowing of the local scope is needed since the variable namespace would become cluttered, making it very easy to accidentally overwrite variables from another function. - -For example: - -\fish -function shiver - set phrase 'Shiver me timbers' -end - -function avast - set phrase 'Avast, mateys' - # Calling the shiver function here can not - # change any variables in the local scope - shiver - echo $phrase -end -avast - -# Outputs "Avast, mateys" -\endfish - - -\subsection variables-export Exporting variables - -Variables in fish can be exported. This means the variable will be inherited by any commands started by fish. It is convention that exported variables are in uppercase and unexported variables are in lowercase. - -Variables can be explicitly set to be exported with the `-x` or `--export` switch, or not exported with the `-u` or `--unexport` switch. The exporting rules when creating or updating a variable are identical to the scoping rules for variables: - --# If a variable is explicitly set to either be exported or not exported, that setting will be honored. - --# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept. - --# If a variable is not explicitly set to be either exported or not exported and has never before been defined, the variable will not be exported. - --# If a variable has local scope and is exported, any function called receives a _copy_ of it, so any changes it makes to the variable disappear once the function returns. - --# If a variable has global scope, it is accessible read-write to functions whether it is exported or not. - -\subsection variables-arrays Arrays - -`fish` can store a list of multiple strings inside of a variable. To access one element of an array, use the index of the element inside of square brackets, like this: - -`echo $PATH[3]` - -Note that array indices start at 1 in `fish`, not 0, as is more common in other languages. This is because many common Unix tools like `seq` are more suited to such use. An invalid index is silently ignored resulting in no value being substituted (not an empty string). - -If you do not use any brackets, all the elements of the array will be written as separate items. This means you can easily iterate over an array using this syntax: - -\fish -for i in $PATH; echo $i is in the path; end -\endfish - -To create a variable `smurf`, containing the items `blue` and `small`, simply write: - -\fish -set smurf blue small -\endfish - -It is also possible to set or erase individual elements of an array: - -\fish -# Set smurf to be an array with the elements 'blue' and 'small' -set smurf blue small - -# Change the second element of smurf to 'evil' -set smurf[2] evil - -# Erase the first element -set -e smurf[1] - -# Output 'evil' -echo $smurf -\endfish - -If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array. - -A range of indices can be specified, see index range expansion for details. - -All arrays are one-dimensional and cannot contain other arrays, although it is possible to fake nested arrays using the dereferencing rules of variable expansion. - -When an array is exported as an environment variable, it is either space or colon delimited, depending on whether it is a path variable: -\fish -set -x smurf blue small -set -x smurf_PATH forest mushroom -env | grep smurf - -# smurf=blue small -# smurf_PATH=forest:mushroom - -\endfish - -`fish` automatically creates arrays from all environment variables whose name ends in PATH, by splitting them on colons. Other variables are not automatically split. - -\subsection variables-path PATH variables - -Path variables are a special kind of variable used to support colon-delimited path lists including PATH, CDPATH, MANPATH, PYTHONPATH, etc. All variables that end in `PATH` (case-sensitive) become PATH variables. - -PATH variables act as normal arrays, except they are are implicitly joined and split on colons. -\fish -set MYPATH 1 2 3 -echo "$MYPATH" -# 1:2:3 -set MYPATH "$MYPATH:4:5" -echo $MYPATH -# 1 2 3 4 5 -echo "$MYPATH" -# 1:2:3:4:5 -\endfish - -Variables can be marked or unmarked as PATH variables via the `--path` and `--unpath` options to `set`. - -\subsection variables-special Special variables - -The user can change the settings of `fish` by changing the values of certain variables. - -- A large number of variable starting with the prefixes `fish_color` and `fish_pager_color.` See Variables for changing highlighting colors for more information. - -- `fish_emoji_width` controls the computed width of certain characters, in particular emoji, whose rendered width varies across terminal emulators. This should be set to 1 if your terminal emulator renders emoji single-width, or 2 if double-width. Set this only if you see graphical glitching when printing emoji. - -- `fish_ambiguous_width` controls the computed width of ambiguous East Asian characters. This should be set to 1 if your terminal emulator renders these characters as single-width (typical), or 2 if double-width. - -- `fish_escape_delay_ms` overrides the default timeout of 30ms after seeing an escape character before giving up on matching a key binding. See the documentation for the bind builtin command. This delay facilitates using escape as a meta key. - -- `fish_greeting`, the greeting message printed on startup. - -- `fish_history`, the current history session name. If set, all subsequent commands within an - interactive fish session will be logged to a separate file identified by the value of the - variable. If unset, or set to `default`, the default session name "fish" is used. If set to an - empty string, history is not saved to disk (but is still available within the interactive - session). - -- `fish_user_paths`, an array of directories that are prepended to `PATH`. This can be a universal variable. - -- `umask`, the current file creation mask. The preferred way to change the umask variable is through the umask function. An attempt to set umask to an invalid value will always fail. - -- `BROWSER`, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation. - -- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. - -- `LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. See the section Locale variables for more information. - -- `PATH`, an array of directories in which to search for commands - -`fish` also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables. - -- `_`, the name of the currently running command (though this is deprecated, and the use of `status current-command` is preferred). - -- `argv`, an array of arguments to the shell or function. `argv` is only defined when inside a function call, or if fish was invoked with a list of arguments, like `fish myscript.fish foo bar`. This variable can be changed by the user. - -- `history`, an array containing the last commands that were entered. - -- `HOME`, the user's home directory. This variable can be changed by the user. - -- `hostname`, the machine's hostname. - -- `IFS`, the internal field separator that is used for word splitting with the read builtin. Setting this to the empty string will also disable line splitting in command substitution. This variable can be changed by the user. - -- `PWD`, the current working directory. - -- `status`, the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. - -- `USER`, the current username. This variable can be changed by the user. - -- `CMD_DURATION`, the runtime of the last command in milliseconds. - -- `version`, the version of the currently running fish (also available as `FISH_VERSION` for backward compatibility). - -- `SHLVL`, the level of nesting of shells - -- `COLUMNS` and `LINES`, the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes. - -The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash. - -Variables whose name are in uppercase are generally exported to the commands started by fish, while those in lowercase are not exported (`CMD_DURATION` is an exception, for historical reasons). This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables. `fish` also uses several variables internally. Such variables are prefixed with the string `__FISH` or `__fish.` These should never be used by the user. Changing their value may break fish. - -\subsection variables-status The status variable - -Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem. - -Fish stores the exit status of the last process in the last job to exit in the `status` variable. - -If `fish` encounters a problem while executing a command, the status variable may also be set to a specific value: - -- 0 is generally the exit status of fish commands if they successfully performed the requested operation. - -- 1 is generally the exit status of fish commands if they failed to perform the requested operation. - -- 121 is generally the exit status of fish commands if they were supplied with invalid arguments. - -- 123 means that the command was not executed because the command name contained invalid characters. - -- 124 means that the command was not executed because none of the wildcards in the command produced any matches. - -- 125 means that while an executable with the specified name was located, the operating system could not actually execute the command. - -- 126 means that while a file with the specified name was located, it was not executable. - -- 127 means that no function, builtin or command with the given name could be located. - -If a process exits through a signal, the exit status will be 128 plus the number of the signal. - - -\subsection variables-color Variables for changing highlighting colors - -The colors used by fish for syntax highlighting can be configured by changing the values of a various variables. The value of these variables can be one of the colors accepted by the set_color command. The `--bold` or `-b` switches accepted by `set_color` are also accepted. - -The following variables are available to change the highlighting colors in fish: - -- `fish_color_normal`, the default color - -- `fish_color_command`, the color for commands - -- `fish_color_quote`, the color for quoted blocks of text - -- `fish_color_redirection`, the color for IO redirections - -- `fish_color_end`, the color for process separators like ';' and '&' - -- `fish_color_error`, the color used to highlight potential errors - -- `fish_color_param`, the color for regular command parameters - -- `fish_color_comment`, the color used for code comments - -- `fish_color_match`, the color used to highlight matching parenthesis - -- `fish_color_selection`, the color used when selecting text (in vi visual mode) - -- `fish_color_search_match`, used to highlight history search matches and the selected pager item (must be a background) - -- `fish_color_operator`, the color for parameter expansion operators like '*' and '~' - -- `fish_color_escape`, the color used to highlight character escapes like '\\n' and '\\x70' - -- `fish_color_cwd`, the color used for the current working directory in the default prompt - -- `fish_color_autosuggestion`, the color used for autosuggestions - -- `fish_color_user`, the color used to print the current username in some of fish default prompts - -- `fish_color_host`, the color used to print the current host system in some of fish default prompts - -- `fish_color_cancel`, the color for the '^C' indicator on a canceled command - -Additionally, the following variables are available to change the highlighting in the completion pager: - -- `fish_pager_color_progress`, the color of the progress bar at the bottom left corner - -- `fish_pager_color_background`, the background color of a line - -- `fish_pager_color_prefix`, the color of the prefix string, i.e. the string that is to be completed - -- `fish_pager_color_completion`, the color of the completion itself - -- `fish_pager_color_description`, the color of the completion description - -- `fish_pager_color_secondary_background`, `fish_pager_color_background` of every second unselected completion. Defaults to `fish_pager_color_background` - -- `fish_pager_color_secondary_ prefix`, `fish_pager_color_prefix` of every second unselected completion. Defaults to `fish_pager_color_prefix` - -- `fish_pager_color_secondary_completion`, `fish_pager_color_completion` of every second unselected completion. Defaults to `fish_pager_color_completion` - -- `fish_pager_color_secondary_description`, `fish_pager_color_description` of every second unselected completion. Defaults to `fish_pager_color_description` - -- `fish_pager_color_selected_background`, `fish_pager_color_background` of the selected completion. Defaults to `fish_color_search_match` - -- `fish_pager_color_selected_prefix`, `fish_pager_color_prefix` of the selected completion. Defaults to `fish_pager_color_prefix` - -- `fish_pager_color_selected_completion`, `fish_pager_color_completion` of the selected completion. Defaults to `fish_pager_color_completion` - -- `fish_pager_color_selected_description`, `fish_pager_color_description` of the selected completion. Defaults to `fish_pager_color_description` - -Example: - -To make errors highlighted and red, use: - -\fish -set fish_color_error red --bold -\endfish - - -\subsection variables-locale Locale variables - -The most common way to set the locale to use a command like 'set -x LANG en_GB.utf8', which sets the current locale to be the English language, as used in Great Britain, using the UTF-8 character set. For a list of available locales, use 'locale -a'. - -`LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. These variables work as follows: `LC_ALL` forces all the aspects of the locale to the specified value. If `LC_ALL` is set, all other locale variables will be ignored. The other `LC_` variables set the specified aspect of the locale information. `LANG` is a fallback value, it will be used if none of the `LC_` variables are specified. - - -\section builtin-overview Builtin commands - -Many other shells have a large library of builtin commands. Most of these commands are also available as standalone commands, but have been implemented in the shell anyway. To avoid code duplication, and to avoid the confusion of subtly differing versions of the same command, `fish` generally only implements builtins for actions which cannot be performed by a regular command. - -For a list of all builtins, functions and commands shipped with fish, see the table of contents. The documentation is also available by using the `--help` switch of the command. - - -\section editor Command line editor - -The `fish` editor features copy and paste, a searchable history and many editor functions that can be bound to special keyboard shortcuts. - -Similar to bash, fish has Emacs and Vi editing modes. The default editing mode is Emacs. You can switch to Vi mode with `fish_vi_key_bindings` and switch back with `fish_default_key_bindings`. You can also make your own key bindings by creating a function and setting $fish_key_bindings to its name. For example: - -\fish -function hybrid_bindings --description "Vi-style bindings that inherit emacs-style bindings in all modes" - for mode in default insert visual - fish_default_key_bindings -M $mode - end - fish_vi_key_bindings --no-erase -end -set -g fish_key_bindings hybrid_bindings -\endfish - -\subsection shared-binds Shared bindings - -Some bindings are shared between emacs- and vi-mode because they aren't text editing bindings or because what Vi/Vim does for a particular key doesn't make sense for a shell. - -- @key{Tab} completes the current token. @key{Shift, Tab} completes the current token and starts the pager's search mode. - -- @key{Alt,←,Left} and @key{Alt,→,Right} move the cursor one word left or right (to the next space or punctuation mark), or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, @key{Alt,→,Right} (or @key{Alt,F}) accepts the first word in the suggestion. - -- @key{Shift,←,Left} and @key{Shift,→,Right} move the cursor one word left or right, without stopping on punctuation. - -- @cursor_key{↑,Up} and @cursor_key{↓,Down} (or @key{Control,P} and @key{Control,N} for emacs aficionados) search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the history section for more information on history searching. - -- @key{Alt,↑,Up} and @key{Alt,↓,Down} search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the history section for more information on history searching. - -- @key{Control,C} cancels the entire line. - -- @key{Control,D} delete one character to the right of the cursor. If the command line is empty, @key{Control,D} will exit fish. - -- @key{Control,U} moves contents from the beginning of line to the cursor to the killring. - -- @key{Control,L} clears and repaints the screen. - -- @key{Control,W} moves the previous path component (everything up to the previous "/") to the killring. - -- @key{Control,X} copies the current buffer to the system's clipboard, @key{Control,V} inserts the clipboard contents. - -- @key{Alt,d} moves the next word to the killring. - -- @key{Alt,h} (or @key{F1}) shows the manual page for the current command, if one exists. - -- @key{Alt,l} lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed. - -- @key{Alt,p} adds the string '`| less;`' to the end of the job under the cursor. The result is that the output of the command will be paged. - -- @key{Alt,w} prints a short description of the command under the cursor. - -- @key{Alt,e} edit the current command line in an external editor. The editor is chosen from the first available of the `$VISUAL` or `$EDITOR` variables. - -- @key{Alt,v} Same as @key{Alt,e}. - -\subsection emacs-mode Emacs mode commands - -- @key{Home} or @key{Control,A} moves the cursor to the beginning of the line. - -- @key{End} or @key{Control,E} moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, @key{End} or @key{Control,E} accepts the autosuggestion. - -- @cursor_key{←,Left} (or @key{Control,B}) and @cursor_key{→,Right} (or @key{Control,F}) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, the @cursor_key{→,Right} key and the @key{Control,F} combination accept the suggestion. - -- @key{Delete} and @key{Backspace} removes one character forwards or backwards respectively. - -- @key{Control,K} moves contents from the cursor to the end of line to the killring. - -- @key{Alt,c} capitalizes the current word. - -- @key{Alt,u} makes the current word uppercase. - -- @key{Control,t} transposes the last two characters - -- @key{Alt,t} transposes the last two words - - -You can change these key bindings using the bind builtin command. - - -\subsection vi-mode Vi mode commands - -Vi mode allows for the use of Vi-like commands at the prompt. Initially, insert mode is active. @key{Escape} enters command mode. The commands available in command, insert and visual mode are described below. Vi mode shares some bindings with Emacs mode. - -It is also possible to add all emacs-mode bindings to vi-mode by using something like - -\fish -function fish_user_key_bindings - # Execute this once per mode that emacs bindings should be used in - fish_default_key_bindings -M insert - # Without an argument, fish_vi_key_bindings will default to - # resetting all bindings. - # The argument specifies the initial mode (insert, "default" or visual). - fish_vi_key_bindings insert -end -\endfish - -When in vi-mode, the `fish_mode_prompt` function will display a mode indicator to the left of the prompt. The `fish_vi_cursor` function will be used to change the cursor's shape depending on the mode in supported terminals. To disable this feature, override it with an empty function. To display the mode elsewhere (like in your right prompt), use the output of the `fish_default_mode_prompt` function. - -\subsubsection vi-mode-command Command mode - -Command mode is also known as normal mode. - -- @key{h} moves the cursor left. - -- @key{l} moves the cursor right. - -- @key{i} enters insert mode at the current cursor position. - -- @key{v} enters visual mode at the current cursor position. - -- @key{a} enters insert mode after the current cursor position. - -- @key{Shift,A} enters insert mode at the end of the line. - -- @key{0} (zero) moves the cursor to beginning of line (remaining in command mode). - -- @key{d}@key{d} deletes the current line and moves it to the killring. - -- @key{Shift,D} deletes text after the current cursor position and moves it to the killring. - -- @key{p} pastes text from the killring. - -- @key{u} search history backwards. - -- @key{[} and @key{]} search the command history for the previous/next token containing the token under the cursor before the search was started. See the history section for more information on history searching. - -- @key{Backspace} moves the cursor left. - -\subsubsection vi-mode-insert Insert mode - -- @key{Escape} enters command mode. - -- @key{Backspace} removes one character to the left. - -\subsubsection vi-mode-visual Visual mode - -- @cursor_key{←,Left} and @cursor_key{→,Right} extend the selection backward/forward by one character. - -- @key{b} and @key{w} extend the selection backward/forward by one word. - -- @key{d} and @key{x} move the selection to the killring and enter command mode. - -- @key{Escape} and @key{Control,C} enter command mode. - -\subsection killring Copy and paste (Kill Ring) - -`fish` uses an Emacs style kill ring for copy and paste functionality. Use @key{Control,K} to cut from the current cursor position to the end of the line. The string that is cut (a.k.a. killed) is inserted into a linked list of kills, called the kill ring. To paste the latest value from the kill ring use @key{Control,Y}. After pasting, use @key{Alt,Y} to rotate to the previous kill. - -Copy and paste from outside are also supported, both via the @key{Control,X} / @key{Control,V} bindings and via the terminal's paste function, for which fish enables "Bracketed Paste Mode". When pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the result can be used as a single token simply by closing the quote after. - -\subsection history-search Searchable history - -After a command has been entered, it is inserted at the end of a history list. Any duplicate history items are automatically removed. By pressing the up and down keys, the user can search forwards and backwards in the history. If the current command line is not empty when starting a history search, only the commands containing the string entered into the command line are shown. - -By pressing @key{Alt,↑,Up} and @key{Alt,↓,Down}, a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that under the cursor. - -History searches can be aborted by pressing the escape key. - -Prefixing the commandline with a space will prevent the entire line from being stored in the history. - -The command history is stored in the file `~/.local/share/fish/fish_history` (or -`$XDG_DATA_HOME/fish/fish_history` if that variable is set) by default. However, you can set the -`fish_history` environment variable to change the name of the history session (resulting in a -`_history` file); both before starting the shell and while the shell is running. - -Examples: - -To search for previous entries containing the word 'make', type `make` in the console and press the up key. - -If the commandline reads `cd m`, place the cursor over the `m` character and press @key{Alt,↑,Up} to search for previously typed words containing 'm'. - - -\subsection multiline Multiline editing - -The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line: - -- Pressing the @key{Enter} key while a block of commands is unclosed, such as when one or more block commands such as `for`, `begin` or `if` do not have a corresponding `end` command. - -- Pressing @key{Alt,Enter} instead of pressing the @key{Enter} key. - -- By inserting a backslash (`\`) character before pressing the @key{Enter} key, escaping the newline. - -The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts. - - -\section job-control Running multiple programs - -Normally when `fish` starts a program, this program will be put in the foreground, meaning it will take control of the terminal and `fish` will be stopped until the program finishes. Sometimes this is not desirable. For example, you may wish to start an application with a graphical user interface from the terminal, and then be able to continue using the shell. In such cases, there are several ways in which the user can change fish's behavior. - --# By ending a command with the `&` (ampersand) symbol, the user tells `fish` to put the specified command into the background. A background process will be run simultaneous with `fish`. `fish` will retain control of the terminal, so the program will not be able to read from the keyboard. - --# By pressing @key{Control,Z}, the user stops a currently running foreground program and returns control to `fish`. Some programs do not support this feature, or remap it to another key. GNU Emacs uses @key{Control,X} @key{z} to stop running. - --# By using the `fg` and `bg` builtin commands, the user can send any currently running job into the foreground or background. - -Note that functions cannot be started in the background. Functions that are stopped and then restarted in the background using the `bg` command will not execute correctly. - - -\section initialization Initialization files - -On startup, Fish evaluates a number of configuration files, which can be used to control the behavior of the shell. The location of these configuration variables is controlled by a number of environment variables, and their default or usual location is given below. - -Configuration files are evaluated in the following order: -- Configuration shipped with fish, which should not be edited, in `$__fish_data_dir/config.fish` (usually `/usr/share/fish/config.fish`). -- Configuration snippets in files ending in `.fish`, in the directories: - - `$__fish_config_dir/conf.d` (by default, `~/.config/fish/conf.d/`) - - `$__fish_sysconf_dir/conf.d` (by default, `/etc/fish/conf.d`) - - `/usr/share/fish/vendor_conf.d` (set at compile time; by default, `$__fish_data_dir/conf.d`) - - If there are multiple files with the same name in these directories, only the first will be executed. - They are executed in order of their filename, sorted (like globs) in a natural order (i.e. "01" sorts before "2"). - -- System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to `/etc/profile` for POSIX-style shells - in `$__fish_sysconf_dir` (usually `/etc/fish/config.fish`); -- User initialization, usually in `~/.config/fish/config.fish` (controlled by the `XDG_CONFIG_HOME` environment variable, and accessible as `$__fish_config_dir`). - -These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. - -This wide search may be confusing. If you are unsure where to put your own customisations, use `~/.config/fish/config.fish`. - -Note that ~/.config/fish/config.fish is sourced _after_ the snippets. This is so users can copy snippets and override some of their behavior. - -These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command `status --is-interactive` to determine if the shell is interactive. If you want to run a command only when using a login shell, use `status --is-login` instead. This will speed up the starting of non-interactive or non-login shells. - -If you are developing another program, you may wish to install configuration which is run for all users of the fish shell on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells will not benefit from the Fish-specific configuration. However, if they are absolutely required, you may install them to the "vendor" configuration directory. As this path may vary from system to system, the `pkgconfig` framework should be used to discover this path with the output of `pkg-config --variable confdir fish`. - -Examples: - -If you want to add the directory `~/linux/bin` to your PATH variable when using a login shell, add the following to your `~/.config/fish/config.fish` file: - -\fish -if status --is-login - set -x PATH $PATH ~/linux/bin -end -\endfish - -If you want to run a set of commands when `fish` exits, use an event handler that is triggered by the exit of the shell: - -\fish -function on_exit --on-event fish_exit - echo fish is now exiting -end -\endfish - -\section featureflags Future feature flags - -Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they become opt-out, and eventually the old behavior is removed. - -You can see the current list of features via `status features`: - -\fish -> status features -stderr-nocaret on 3.0 ^ no longer redirects stderr -qmark-noglob off 3.0 ? no longer globs -\endfish - -There are two breaking changes in fish 3.0: caret `^` no longer redirects stderr, and question mark `?` is no longer a glob. These changes are off by default. They can be enabled on a per session basis: - -\fish -> fish --features qmark-noglob,stderr-nocaret -\endfish - -or opted into globally for a user: - -\fish -> set -U fish_features stderr-nocaret qmark-noglob -\endfish - -\section other Other features - - -\subsection color Syntax highlighting - -`fish` interprets the command line as it is typed and uses syntax highlighting to provide feedback to the user. The most important feedback is the detection of potential errors. By default, errors are marked red. - -Detected errors include: - -- Non existing commands. -- Reading from or appending to a non existing file. -- Incorrect use of output redirects -- Mismatched parenthesis - - -When the cursor is over a parenthesis or a quote, `fish` also highlights its matching quote or parenthesis. - -To customize the syntax highlighting, you can set the environment variables listed in the Variables for changing highlighting colors section. - -\subsection title Programmable title - -When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the `fish_title` function. The `fish_title` function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The `status current-command` builtin will always return the name of the job to be put into the foreground (or 'fish' if control is returning to the shell) when the `fish_prompt` function is called. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2. - -Examples: -The default `fish` title is - -\fish -function fish_title - echo (status current-command) ' ' - pwd -end -\endfish - -To show the last command in the title: - -\fish -function fish_title - echo $argv[1] -end -\endfish - -\subsection prompt Programmable prompt - -When fish waits for input, it will display a prompt by evaluating the `fish_prompt` and `fish_right_prompt` functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of `fish_mode_prompt` will be prepended on the left, though the default function only does this when in vi-mode. - -\subsection greeting Configurable greeting - -If a function named `fish_greeting` exists, it will be run when entering interactive mode. Otherwise, if an environment variable named `fish_greeting` exists, it will be printed. - -\subsection private-mode Private mode - -fish supports launching in private mode via `fish --private` (or `fish -P` for short). In private mode, old history is not available and any interactive commands you execute will not be appended to the global history file, making it useful both for avoiding inadvertently leaking personal information (e.g. for screencasts) and when dealing with sensitive information to prevent it being persisted to disk. You can query the global variable `fish_private_mode` (`if set -q fish_private_mode ...`) if you would like to respect the user's wish for privacy and alter the behavior of your own fish scripts. - -\subsection event Event handlers - -When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are: - -- When a signal is delivered -- When a process or job exits -- When the value of a variable is updated -- When the prompt is about to be shown -- When a command lookup fails - -Example: - -To specify a signal handler for the WINCH signal, write: - -\fish -function my_signal_handler --on-signal WINCH - echo Got WINCH signal! -end -\endfish - -Please note that event handlers only become active when a function is loaded, which means you might need to otherwise source or execute a function instead of relying on autoloading. One approach is to put it into your initialization file. - -For more information on how to define new event handlers, see the documentation for the function command. - - -\subsection debugging Debugging fish scripts - -Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using `printf` and `set`. As another example, you can run `status print-stack-trace` to see how this breakpoint was reached. To resume normal execution of the script, simply type `exit` or [ctrl-D]. - -To start a debug session simply run the builtin command `breakpoint` at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the `kill` command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function. - -Note: At the moment the debug prompt is identical to your normal fish prompt. This can make it hard to recognize that you've entered a debug session. Issue 1310 is open to improve this. - - -\section more-help Further help and development - -If you have a question not answered by this documentation, there are several avenues for help: - --# The official mailing list at fish-users@lists.sourceforge.net - --# The Internet Relay Chat channel, \#fish on `irc.oftc.net` - --# The project GitHub page - - -If you have an improvement for fish, you can submit it via the mailing list or the GitHub page. - -\htmlonly[block] -
-\endhtmlonly -*/ diff --git a/doc_src/isatty.txt b/doc_src/isatty.txt deleted file mode 100644 index f6ab500e6..000000000 --- a/doc_src/isatty.txt +++ /dev/null @@ -1,35 +0,0 @@ -\section isatty isatty - test if a file descriptor is a tty. - -\subsection isatty-synopsis Synopsis -\fish{synopsis} -isatty [FILE DESCRIPTOR] -\endfish - -\subsection isatty-description Description - -`isatty` tests if a file descriptor is a tty. - -`FILE DESCRIPTOR` may be either the number of a file descriptor, or one of the strings `stdin`, `stdout`, or `stderr`. - -If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error. - - -\subsection isatty-examples Examples - -From an interactive shell, the commands below exit with a return value of zero: - -\fish -isatty -isatty stdout -isatty 2 -echo | isatty 1 -\endfish - -And these will exit non-zero: - -\fish -echo | isatty -isatty 9 -isatty stdout > file -isatty 2 2> file -\endfish diff --git a/doc_src/jobs.txt b/doc_src/jobs.txt deleted file mode 100644 index df4fd9f10..000000000 --- a/doc_src/jobs.txt +++ /dev/null @@ -1,33 +0,0 @@ -\section jobs jobs - print currently running jobs - -\subsection jobs-synopsis Synopsis -\fish{synopsis} -jobs [OPTIONS] [PID] -\endfish - -\subsection jobs-description Description - -`jobs` prints a list of the currently running jobs and their status. - -jobs accepts the following switches: - -- `-c` or `--command` prints the command name for each process in jobs. - -- `-g` or `--group` only prints the group ID of each job. - -- `-l` or `--last` prints only the last job to be started. - -- `-p` or `--pid` prints the process ID for each process in all jobs. - -- `-q` or `--quiet` prints no output for evaluation of jobs by exit code only. - -On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%. - -The exit code of the `jobs` builtin is `0` if there are running background jobs and `1` otherwise. - -\subsection prints no output. - - -\subsection jobs-example Example - -`jobs` outputs a summary of the current jobs. diff --git a/doc_src/license.hdr b/doc_src/license.hdr deleted file mode 100644 index 11d670eec..000000000 --- a/doc_src/license.hdr +++ /dev/null @@ -1,400 +0,0 @@ -/** \page license Licenses - -\htmlonly[block] -
-
-

Licenses for fish

- -\endhtmlonly - -`fish` Copyright © 2005-2009 Axel Liljencrantz. `fish` is released under the GNU General Public License, version 2. - -`fish` includes other code licensed under the GNU General Public License, version 2, including GNU `printf`. - -Copyright © 1990-2007 Free Software Foundation, Inc. Printf (from GNU Coreutils 6.9) is released under the GNU General Public License, version 2. - -The GNU General Public License agreement follows. - -## GNU GENERAL PUBLIC LICENSE - -Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -## Preamble - -The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. - -To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. - -For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. - -We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. - -Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. - -Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. - -The precise terms and conditions for copying, distribution and modification follow. - - -## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -- This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". - - Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. - -1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. - - You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - - -# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. - - -# You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. - - -# If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) - - These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. - - In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. - -3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: - - -# Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - - -# Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - - -# Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) - - The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. - - If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. - -4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. - -5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. - -6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. - -7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. - - If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. - - It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. - -8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. - -9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. - -10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. - - __NO WARRANTY__ - -11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - ----- - -## License for PCRE2 - -`fish` contains code from the [PCRE2](http://www.pcre.org) library to support regular expressions. This code, created by Philip Hazel, is distributed under the terms of the BSD license. Copyright © 1997-2015 University of Cambridge. - -The BSD license follows. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - - -# Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - -# Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - - -# Neither the name of the University of Cambridge nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ----- - -## License for CMake - -The `fish` source code contains files from [CMake](https://cmake.org) to support the build system. -This code is distributed under the terms of a BSD-style license. Copyright 2000-2017 Kitware, Inc. -and Contributors. - -The BSD license for CMake follows. - -CMake - Cross Platform Makefile Generator -Copyright 2000-2017 Kitware, Inc. and Contributors -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -* Neither the name of Kitware, Inc. nor the names of Contributors - may be used to endorse or promote products derived from this - software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ----- - -## License for wcslcpy and code derived from tmux - -`fish` also contains small amounts of code under the OpenBSD license, namely a version of the function strlcpy, modified for use with wide character strings. This code is copyrighted by Todd C. Miller (1998). It also contains code from [tmux](http://tmux.sourceforge.net), copyrighted by Nicholas Marriott (2007), and made available under an identical license. - -The OpenBSD license is included below. - -Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - ----- - -## License for glibc - -Fish contains code from the glibc library, namely the wcstok function. This code is licensed under the LGPL, version 2 or later. Version 2 of the LPGL license agreement is included below. - -## GNU LESSER GENERAL PUBLIC LICENSE - -Version 2.1, February 1999 - - Copyright (C) 1991, 1999 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -[This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.] - -## Preamble - -The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. - -This license, the Lesser General Public License, applies to some specially designated software packages - typically libraries - of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below. - -When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. - -To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. - -For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights. - -We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library. - -To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others. - -Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license. - -Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs. - -When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. - -We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. - -For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License. - -In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system. - -Although the Lesser General Public License is Less protective of the users'freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library. - -The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run. - -## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -- This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you". - - A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. - - The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) - - "Source code for a work" means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. - - Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. - -1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. - - You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - - -# The modified work must itself be a software library. - - -# You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. - - -# You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. - - -# If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. - - (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) - - These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. - - In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. - -3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. - - Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of the Library into a program that is not a library. - -4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. - -5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. - - However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. - - When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. - -6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: - - -# Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine- readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) - - -# Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. - - -# Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. - - -# If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. - - -# Verify that the user has already received a copy of these materials or that you have already sent this user a copy. - - For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. - - It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. - -7. You may place library facilities that are a work based on the Library side- by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: - - -# Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. - - -# Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. - -8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. - -9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. - -10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients'exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. - -11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. - - If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. - - It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. - -12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. - -13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. - -14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. - - __NO WARRANTY__ - -15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - ----- - -## License for UTF8 - -`fish` also contains small amounts of code under the ISC license, namely the UTF-8 conversion functions. This code is copyright © 2007 Alexey Vatchenko \. - -The ISC license agreement follows. - -Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - ----- - -## License for flock - -`fish` also contains small amounts of code from NetBSD, namely the `flock` fallback function. This code is copyright 2001 The NetBSD Foundation, Inc., and derived from software contributed to The NetBSD Foundation by Todd Vierling. - -The NetBSD license follows. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS -``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS -BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - ----- - -## MIT License - -`fish` includes a copy of AngularJS, which is copyright 2010-2012 Google, Inc. and licensed under the MIT License. - -The MIT license follows. - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -\htmlonly[block] -
-
-\endhtmlonly -*/ diff --git a/doc_src/math.txt b/doc_src/math.txt deleted file mode 100644 index 566b561cd..000000000 --- a/doc_src/math.txt +++ /dev/null @@ -1,106 +0,0 @@ -\section math math - Perform mathematics calculations - -\subsection math-synopsis Synopsis -\fish{synopsis} -math [-sN | --scale=N] [--] EXPRESSION -\endfish - -\subsection math-description Description - -`math` is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as functions like `abs()`, `sqrt()` and `log2()`. - -By default, the output is as a float with trailing zeroes trimmed. To get a fixed representation, the `--scale` option can be used, including `--scale=0` for integer output. - -Keep in mind that parameter expansion takes before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (`()`) and the asterisk (`*`) glob character have to be escaped or quoted. - -`math` ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so `math 2 +2` and `math "2 + 2"` work the same. `math 2 2` is an error. - -The following options are available: - -- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer or the word "max" for the maximum scale. A scale of zero causes results to be rounded down to the nearest integer. So `3/2` returns `1` rather than `2` which `1.5` would normally round to. This is for compatibility with `bc` which was the basis for this command prior to fish 3.0.0. Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places. - -\subsection return-values Return Values - -If the expression is successfully evaluated and doesn't over/underflow or return NaN the return `status` is zero (success) else one. - -\subsection math-syntax Syntax - -`math` knows some operators, constants, functions and can (obviously) read numbers. - -For numbers, `.` is always the radix character regardless of locale - `2.5`, not `2,5`. Scientific notation (`10e5`) is also available. - -\subsection math-operators Operators - -`math` knows the following operators: - -- `+` for addition and `-` for subtraction. - -- `*` for multiplication, `/` for division. (Note that `*` is the glob character and needs to be quoted or escaped) - -- `^` for exponentiation. - -- `%` for modulo. - -- `(` and `)` for grouping. (These need to be quoted or escaped because `()` denotes a command substitution.) - -They are all used in an infix manner - `5 + 2`, not `+ 5 2`. - -\subsection math-constants Constants - -`math` knows the following constants: - -- `e` - Euler's number. -- `pi` - You know that one. Half of Tau. (Tau is not implemented) - -Use them without a leading `$` - `pi - 3` should be about 0. - -\subsection math-functions Functions - -`math` supports the following functions: - -- `abs` -- `acos` -- `asin` -- `atan` -- `atan2` -- `ceil` -- `cos` -- `cosh` -- `exp` - the base-e exponential function -- `fac` - factorial -- `floor` -- `ln` -- `log` or `log10` - the base-10 logarithm -- `ncr` -- `npr` -- `pow(x,y)` returns x to the y (and can be written as `x ^ y`) -- `round` - rounds to the nearest integer, away from 0 -- `sin` -- `sinh` -- `sqrt` -- `tan` -- `tanh` - -All of the trigonometric functions use radians. - -\subsection math-example Examples - -`math 1+1` outputs 2. - -`math $status - 128` outputs the numerical exit status of the last command minus 128. - -`math 10 / 6` outputs `1.666667`. - -`math -s0 10.0 / 6.0` outputs `1`. - -`math -s3 10 / 6` outputs `1.666`. - -`math "sin(pi)"` outputs `0`. - -`math 5 \* 2` or `math "5 * 2"` or `math 5 "*" 2` all output `10`. - -\subsection math-notes Compatibility notes - -Fish 1.x and 2.x releases relied on the `bc` command for handling `math` expressions. Starting with fish 3.0.0 fish uses the tinyexpr library and evaluates the expression without the involvement of any external commands. - -You don't need to use `--` before the expression even if it begins with a minus sign which might otherwise be interpreted as an invalid option. If you do insert `--` before the expression it will cause option scanning to stop just like for every other command and it won't be part of the expression. diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt deleted file mode 100644 index 61e01f1ef..000000000 --- a/doc_src/nextd.txt +++ /dev/null @@ -1,32 +0,0 @@ -\section nextd nextd - move forward through directory history - -\subsection nextd-synopsis Synopsis -\fish{synopsis} -nextd [ -l | --list ] [POS] -\endfish - -\subsection nextd-description Description - -`nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed. - -If the `-l` or `--list` flag is specified, the current directory history is also displayed. - -Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates. - -You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. - -\subsection nextd-example Example - -\fish -cd /usr/src -# Working directory is now /usr/src - -cd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell - -prevd -# Working directory is now /usr/src - -nextd -# Working directory is now /usr/src/fish-shell -\endfish diff --git a/doc_src/not.txt b/doc_src/not.txt deleted file mode 100644 index 7848d2dc9..000000000 --- a/doc_src/not.txt +++ /dev/null @@ -1,23 +0,0 @@ -\section not not - negate the exit status of a job - -\subsection not-synopsis Synopsis -\fish{synopsis} -not COMMAND [OPTIONS...] -\endfish - -\subsection not-description Description - -`not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0. - - -\subsection not-example Example - -The following code reports an error and exits if no file named spoon can be found. - -\fish -if not test -f spoon - echo There is no spoon - exit 1 -end -\endfish - diff --git a/doc_src/open.txt b/doc_src/open.txt deleted file mode 100644 index 7207fc172..000000000 --- a/doc_src/open.txt +++ /dev/null @@ -1,17 +0,0 @@ -\section open open - open file in its default application - -\subsection open-synopsis Synopsis -\fish{synopsis} -open FILES... -\endfish - -\subsection open-description Description - -`open` opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional `xdg-open` utility, from the `xdg-utils` package. - -Note that this function will not be used if a command by this name exists (which is the case on macOS or Haiku). - - -\subsection open-example Example - -`open *.txt` opens all the text files in the current directory using your system's default text editor. diff --git a/doc_src/or.txt b/doc_src/or.txt deleted file mode 100644 index b79e707d6..000000000 --- a/doc_src/or.txt +++ /dev/null @@ -1,23 +0,0 @@ -\section or or - conditionally execute a command - -\subsection or-synopsis Synopsis -\fish{synopsis} -COMMAND1; or COMMAND2 -\endfish - -\subsection or-description Description - -`or` is used to execute a command if the previous command was not successful (returned a status of something other than 0). - -`or` statements may be used as part of the condition in an `and` or `while` block. See the documentation -for `if` and `while` for examples. - -`or` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the $status variable. - -\subsection or-example Example - -The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process. - -\fish -make; and make install; or make clean -\endfish diff --git a/doc_src/popd.txt b/doc_src/popd.txt deleted file mode 100644 index 93dd4da37..000000000 --- a/doc_src/popd.txt +++ /dev/null @@ -1,28 +0,0 @@ -\section popd popd - move through directory stack - -\subsection popd-synopsis Synopsis -\fish{synopsis} -popd -\endfish - -\subsection popd-description Description - -`popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use `pushd` to add directories to the stack. - -You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. - -\subsection popd-example Example - -\fish -pushd /usr/src -# Working directory is now /usr/src -# Directory stack contains /usr/src - -pushd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src /usr/src/fish-shell - -popd -# Working directory is now /usr/src -# Directory stack contains /usr/src -\endfish diff --git a/doc_src/prevd.txt b/doc_src/prevd.txt deleted file mode 100644 index 191d95890..000000000 --- a/doc_src/prevd.txt +++ /dev/null @@ -1,32 +0,0 @@ -\section prevd prevd - move backward through directory history - -\subsection prevd-synopsis Synopsis -\fish{synopsis} -prevd [ -l | --list ] [POS] -\endfish - -\subsection prevd-description Description - -`prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed. - -If the `-l` or `--list` flag is specified, the current history is also displayed. - -Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates. - -You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. - -\subsection prevd-example Example - -\fish -cd /usr/src -# Working directory is now /usr/src - -cd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell - -prevd -# Working directory is now /usr/src - -nextd -# Working directory is now /usr/src/fish-shell -\endfish diff --git a/doc_src/printf.txt b/doc_src/printf.txt deleted file mode 100644 index 26b60618c..000000000 --- a/doc_src/printf.txt +++ /dev/null @@ -1,70 +0,0 @@ -\section printf printf - display text according to a format string - -\subsection printf-synopsis Synopsis -\fish{synopsis} -printf format [argument...] -\endfish - -\subsection printf-description Description -printf formats the string FORMAT with ARGUMENT, and displays the result. - -The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function `printf(3)`. - -Unlike `echo`, `printf` does not append a new line unless it is specified as part of the string. - -Valid format specifiers are: - -- `%%d`: Argument will be used as decimal integer (signed or unsigned) - -- `%%i`: Argument will be used as a signed integer - -- `%%o`: An octal unsigned integer - -- `%%u`: An unsigned decimal integer - -- `%%x` or `%%X`: An unsigned hexadecimal integer - -- `%%f`, `%%g` or `%%G`: A floating-point number - -- `%%e` or `%%E`: A floating-point number in scientific (XXXeYY) notation - -- `%%s`: A string - -- `%%b`: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo. - -`%%` signifies a literal "%". - -Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error. - -printf also knows a number of backslash escapes: -- `\"` double quote -- `\\` backslash -- `\a` alert (bell) -- `\b` backspace -- `\c` produce no further output -- `\e` escape -- `\f` form feed -- `\n` new line -- `\r` carriage return -- `\t` horizontal tab -- `\v` vertical tab -- `\ooo` octal number (ooo is 1 to 3 digits) -- `\xhh` hexadecimal number (hhh is 1 to 2 digits) -- `\uhhhh` 16-bit Unicode character (hhhh is 4 digits) -- `\Uhhhhhhhh` 32-bit Unicode character (hhhhhhhh is 8 digits) - -The `format` argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, `printf '%d' "102.234"` produces an error, as "102.234" cannot be formatted as an integer. - -This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try `command printf`. - -\subsection printf-example Example - -\fish -printf '%s\\t%s\\n' flounder fish -\endfish -Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character. - -\fish -printf '%s: %d' "Number of bananas in my pocket" 42 -\endfish -Will print "Number of bananas in my pocket: 42", _without_ a newline. diff --git a/doc_src/prompt_pwd.txt b/doc_src/prompt_pwd.txt deleted file mode 100644 index 0eafbf994..000000000 --- a/doc_src/prompt_pwd.txt +++ /dev/null @@ -1,31 +0,0 @@ -\section prompt_pwd prompt_pwd - Print pwd suitable for prompt - -\subsection prompt_pwd-synopsis Synopsis -\fish{synopsis} -prompt_pwd -\endfish - -\subsection prompt_pwd-description Description - -prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character. - -To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. - -\subsection prompt_pwd-example Examples - -\fish{cli-dark} ->_ cd ~/ ->_ echo $PWD -/home/alfa - ->_ prompt_pwd -~ - ->_ cd /tmp/banana/sausage/with/mustard ->_ prompt_pwd -/t/b/s/w/mustard - ->_ set -g fish_prompt_pwd_dir_length 3 ->_ prompt_pwd -/tmp/ban/sau/wit/mustard -\endfish diff --git a/doc_src/psub.txt b/doc_src/psub.txt deleted file mode 100644 index d0c59e0ac..000000000 --- a/doc_src/psub.txt +++ /dev/null @@ -1,28 +0,0 @@ -\section psub psub - perform process substitution - -\subsection psub-synopsis Synopsis -\fish{synopsis} -COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX]) -\endfish - -\subsection psub-description Description - -Some shells (e.g., ksh, bash) feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. `psub` combined with a regular command substitution provides the same functionality. - -The following options are available: - -- `-f` or `--file` will cause psub to use a regular file instead of a named pipe to communicate with the calling process. This will cause `psub` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default. - -- `-F` or `--fifo` will cause psub to use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur. - -- `-s` or `--suffix` will append SUFFIX to the filename. - -\subsection psub-example Example - -\fish -diff (sort a.txt | psub) (sort b.txt | psub) -# shows the difference between the sorted versions of files `a.txt` and `b.txt`. - -source-highlight -f esc (cpp main.c | psub -f -s .c) -# highlights `main.c` after preprocessing as a C source. -\endfish diff --git a/doc_src/pushd.txt b/doc_src/pushd.txt deleted file mode 100644 index 43d62c6dd..000000000 --- a/doc_src/pushd.txt +++ /dev/null @@ -1,44 +0,0 @@ -\section pushd pushd - push directory to directory stack - -\subsection pushd-synopsis Synopsis -\fish{synopsis} -pushd [DIRECTORY] -\endfish - -\subsection pushd-description Description - -The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. `popd` will pop it off and return to the original directory. - -Without arguments, it exchanges the top two directories in the stack. - -`pushd +NUMBER` rotates the stack counter-clockwise i.e. from bottom to top - -`pushd -NUMBER` rotates clockwise i.e. top to bottom. - -See also `dirs` and `dirs -c`. - -You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. - -\subsection pushd-example Example - -\fish -pushd /usr/src -# Working directory is now /usr/src -# Directory stack contains /usr/src - -pushd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src /usr/src/fish-shell - -pushd /tmp/ -# Working directory is now /tmp -# Directory stack contains /tmp /usr/src /usr/src/fish-shell - -pushd +1 -# Working directory is now /usr/src -# Directory stack contains /usr/src /usr/src/fish-shell /tmp - -popd -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src/fish-shell /tmp -\endfish diff --git a/doc_src/pwd.txt b/doc_src/pwd.txt deleted file mode 100644 index b3860498e..000000000 --- a/doc_src/pwd.txt +++ /dev/null @@ -1,16 +0,0 @@ -\section pwd pwd - output the current working directory - -\subsection pwd-synopsis Synopsis -\fish{synopsis} -pwd -\endfish - -\subsection pwd-description Description - -`pwd` outputs (prints) the current working directory. - -The following options are available: - -- `-L`, Output the logical working directory, without resolving symlinks (default behavior). - -- `-P`, Output the physical working directory, with symlinks resolved. diff --git a/doc_src/random.txt b/doc_src/random.txt deleted file mode 100644 index 28f140152..000000000 --- a/doc_src/random.txt +++ /dev/null @@ -1,44 +0,0 @@ -\section random random - generate random number - -\subsection random-synopsis Synopsis -\fish{synopsis} -random -random SEED -random START END -random START STEP END -random choice [ITEMS...] -\endfish - -\subsection random-description Description - -`RANDOM` generates a pseudo-random integer from a uniform distribution. The -range (inclusive) is dependent on the arguments passed. -No arguments indicate a range of [0; 32767]. -If one argument is specified, the internal engine will be seeded with the -argument for future invocations of `RANDOM` and no output will be produced. -Two arguments indicate a range of [START; END]. -Three arguments indicate a range of [START; END] with a spacing of STEP -between possible outputs. -`RANDOM choice` will select one random item from the succeeding arguments. - -Note that seeding the engine will NOT give the same result across different -systems. - -You should not consider `RANDOM` cryptographically secure, or even -statistically accurate. - -\subsection random-example Example - -The following code will count down from a random even number between 10 and 20 to 1: - -\fish -for i in (seq (random 10 2 20) -1 1) - echo $i -end -\endfish - -And this will open a random picture from any of the subdirectories: - -\fish -open (random choice **jpg) -\endfish diff --git a/doc_src/read.txt b/doc_src/read.txt deleted file mode 100644 index c898cca59..000000000 --- a/doc_src/read.txt +++ /dev/null @@ -1,94 +0,0 @@ -\section read read - read line of input into variables - -\subsection read-synopsis Synopsis -\fish{synopsis} -read [OPTIONS] [VARIABLE ...] -\endfish - -\subsection read-description Description - -`read` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, `read` 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. Unlike other shells, there is no default variable (such as `REPLY`) for storing the result - instead, it is printed on standard output. - -The following options are available: - -- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`. - -- `-d DELIMITER` or `--delimiter=DELIMITER` splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of characters. - -- `-g` or `--global` makes the variables global. - -- `-s` or `--silent` masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information. - -- `-l` or `--local` makes the variables local. - -- `-n NCHARS` or `--nchars=NCHARS` makes `read` return after reading NCHARS characters or the end of - the line, whichever comes first. - -- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is set_color green; echo read; set_color normal; echo "> ". - -- `-P PROMPT_STR` or `--prompt-str=PROMPT_STR` uses the string as the prompt for the interactive mode. It is equivalent to echo PROMPT_STR and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the echo command. - -- `-R RIGHT_PROMPT_CMD` or `--right-prompt=RIGHT_PROMPT_CMD` uses the output of the shell command `RIGHT_PROMPT_CMD` as the right prompt for the interactive mode. There is no default right prompt command. - -- `-S` or `--shell` 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 `--shell` was `-s`, but it has been changed for compatibility with bash's `-s` short opt for `--silent`. - -- `-u` or `--unexport` prevents the variables from being exported to child processes (default behaviour). - -- `-U` or `--universal` causes the specified shell variable to be made universal. - -- `-x` or `--export` exports the variables to child processes. - -- `-a` or `--array` stores the result as an array in a single variable. - -- `-z` or `--null` marks the end of the line with the NUL character, instead of newline. This also - disables interactive mode. - -- `-L` or `--line` reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the `--delimiter` option. - -Without the `--line` option, `read` reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable. - -If the `--delimiter` argument is not given, the variable `IFS` is used as a list of characters to split on. Relying on the use of `IFS` is deprecated and this behaviour will be removed in future versions. The default value of `IFS` contains space, tab and newline characters. As a special case, if `IFS` is set to the empty string, each character of the input is considered a separate token. - -With the `--line` option, `read` reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized. - -If no variable names are provided, `read` enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read data that should be provided via a command line argument from the console instead of hardcoding it in the command itself, allowing the command to both be reused as-is in various contexts with different input values and preventing possibly sensitive text from being included in the shell history: - -`mysql -uuser -p(read)` - -When running in this mode, `read` does not split the input in any way and text is redirected to standard output without any further processing or manipulation. - -If `-a` or `--array` is provided, only one variable name is allowed and the tokens are stored as an array in this variable. - -See the documentation for `set` for more details on the scoping rules for variables. - -When `read` reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1. -Otherwise, it is set to 0. - -In order to protect the shell from consuming too many system resources, `read` will only consume a -maximum of 10 MiB (1048576 bytes); if the terminator is not reached before this limit then VARIABLE -is set to empty and the exit status is set to 122. This limit can be altered with the -`fish_read_limit` variable. If set to 0 (zero), the limit is removed. - -\subsection read-history Using another read history file - -The `read` command supported the `-m` and `--mode-name` flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the `fish_history` variable to specify a history session ID. That will affect both the `read` history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available. - -\subsection read-example Example - -The following code stores the value 'hello' in the shell variable `$foo`. - -\fish -echo hello|read foo - -# This is a neat way to handle command output by-line: -printf '%s\n' line1 line2 line3 line4 | while read -l foo - echo "This is another line: $foo" - end - -# Delimiters given via "-d" are taken as one string -echo a==b==c | read -d == -l a b c -echo $a # a -echo $b # b -echo $c # c - -\endfish diff --git a/doc_src/realpath.txt b/doc_src/realpath.txt deleted file mode 100644 index 35e6503a3..000000000 --- a/doc_src/realpath.txt +++ /dev/null @@ -1,12 +0,0 @@ -\section realpath realpath - Convert a path to an absolute path without symlinks - -\subsection realpath-synopsis Synopsis -\fish{synopsis} -realpath path -\endfish - -\subsection realpath-description Description - -This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin. The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use `realpath`. - -If the path is invalid no translated path will be written to stdout and an error will be reported. diff --git a/doc_src/return.txt b/doc_src/return.txt deleted file mode 100644 index af4ca9aeb..000000000 --- a/doc_src/return.txt +++ /dev/null @@ -1,25 +0,0 @@ -\section return return - stop the current inner function - -\subsection return-synopsis Synopsis -\fish{synopsis} -function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end -\endfish - -\subsection return-description Description - -`return` halts a currently running function. The exit status is set to `STATUS` if it is given. - -It is usually added inside of a conditional block such as an if statement or a switch statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function. - - -\subsection return-example Example - -The following code is an implementation of the false command as a fish function - -\fish -function false - return 1 -end -\endfish - - diff --git a/doc_src/set.txt b/doc_src/set.txt deleted file mode 100644 index fca3bf170..000000000 --- a/doc_src/set.txt +++ /dev/null @@ -1,113 +0,0 @@ -\section set set - display and change shell variables. - -\subsection set-synopsis Synopsis -\fish{synopsis} -set [SCOPE_OPTIONS] -set [OPTIONS] VARIABLE_NAME VALUES... -set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES... -set ( -q | --query ) [SCOPE_OPTIONS] VARIABLE_NAMES... -set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME -set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... -set ( -S | --show ) [SCOPE_OPTIONS] [VARIABLE_NAME]... -\endfish - -\subsection set-description Description - -`set` manipulates shell variables. - -If set is called with no arguments, the names and values of all shell variables are printed in sorted order. If some of the scope or export flags have been given, only the variables matching the specified scope are printed. - -With both variable names and values provided, `set` assigns the variable `VARIABLE_NAME` the values `VALUES...`. - -The following options control variable scope: - -- `-a` or `--append` causes the values to be appended to the current set of values for the variable. This can be used with `--prepend` to both append and prepend at the same time. This cannot be used when assigning to a variable slice. - -- `-p` or `--prepend` causes the values to be prepended to the current set of values for the variable. This can be used with `--append` to both append and prepend at the same time. This cannot be used when assigning to a variable slice. - -- `-l` or `--local` forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local - -- `-g` or `--global` causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends - -- `-U` or `--universal` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell. - -- `-x` or `--export` causes the specified shell variable to be exported to child processes (making it an "environment variable") - -- `-u` or `--unexport` causes the specified shell variable to NOT be exported to child processes - - -The following options are available: - -- `-e` or `--erase` causes the specified shell variable to be erased - -- `-q` or `--query` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined. - -- `-n` or `--names` List only the names of all defined variables, not their value. The names are guaranteed to be sorted. - -- `-S` or `--show` Shows information about the given variables. If no variable names are given then all variables are shown in sorted order. No other flags can be used with this option. The information shown includes whether or not it is set in each of the local, global, and universal scopes. If it is set in one of those scopes whether or not it is exported is reported. The individual elements are also shown along with the length of each element. - -- `-L` or `--long` do not abbreviate long values when printing set variables - - -If a variable is set to more than one value, the variable will be an array with the specified elements. If a variable is set to zero elements, it will become an array with zero elements. - -If the variable name is one or more array elements, such as `PATH[1 3 7]`, only those array elements specified will be changed. If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array. - -The scoping rules when creating or updating a variable are: - --# Variables may be explicitly set to universal, global or local. Variables with the same name in different scopes will not be changed. - --# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previous variable scope is used. - --# If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the `-l` or `--local` flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global. - - -The exporting rules when creating or updating a variable are identical to the scoping rules for variables: - --# Variables may be explicitly set to either exported or not exported. When an exported variable goes out of scope, it is unexported. - --# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept. - --# If a variable is not explicitly set to be either exported or unexported and has never before been defined, the variable will not be exported. - - -In query mode, the scope to be examined can be specified. - -In erase mode, if variable indices are specified, only the specified slices of the array variable will be erased. - -`set` requires all options to come before any other arguments. For example, `set flags -l` will have the effect of setting the value of the variable `flags` to '-l', not making the variable local. - -In assignment mode, `set` does not modify the exit status. This allows simultaneous capture of the output and exit status of a subcommand, e.g. `if set output (command)`. In query mode, the exit status is the number of variables that were not found. In erase mode, `set` exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist. - - -\subsection set-examples Examples -\fish -# Prints all global, exported variables. -set -xg - -# Sets the value of the variable $foo to be 'hi'. -set foo hi - -# Appends the value "there" to the variable $foo. -set -a foo there - -# Does the same thing as the previous two commands the way it would be done pre-fish 3.0. -set foo hi -set foo $foo there - -# Removes the variable $smurf -set -e smurf - -# Changes the fourth element of the $PATH array to ~/bin -set PATH[4] ~/bin - -# Outputs the path to Python if `type -p` returns true. -if set python_path (type -p python) - echo "Python is at $python_path" -end -\endfish - -\subsection set-notes Notes - -Fish versions prior to 3.0 supported the syntax `set PATH[1] PATH[4] /bin /sbin`, which worked like -`set PATH[1 4] /bin /sbin`. This syntax was not widely used, and was ambiguous and inconsistent. diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt deleted file mode 100644 index 8af576458..000000000 --- a/doc_src/set_color.txt +++ /dev/null @@ -1,57 +0,0 @@ -\section set_color set_color - set the terminal color - -\subsection set_color-synopsis Synopsis -\fish{synopsis} -set_color [OPTIONS] VALUE -\endfish - -\subsection set_color-description Description - -`set_color` is used to control the color and styling of text in the terminal. `VALUE` corresponds to a reserved color name such as *red* or a RGB color value given as 3 or 6 hexadecimal digits. The *br*-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray. A special keyword *normal* resets text formatting to terminal defaults. - -Valid colors include: - - - *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white* - - *brblack*, *brred*, *brgreen*, *bryellow*, *brblue*, *brmagenta*, *brcyan*, *brwhite* - -An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. `fish` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., `set_color 2BC` is the same as `set_color 22BBCC`. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support `set_color` has for it) the actual color may be approximated by a nearby matching reserved color name or `set_color` may not have an effect on color. A second color may be given as a desired fallback color. e.g. `set_color 124212` *brblue* will instruct set_color to use *brblue* if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color. - -The following options are available: - -- `-b`, `--background` *COLOR* sets the background color. -- `-c`, `--print-colors` prints a list of the 16 named colors. -- `-o`, `--bold` sets bold mode. -- `-d`, `--dim` sets dim mode. -- `-i`, `--italics` sets italics mode. -- `-r`, `--reverse` sets reverse mode. -- `-u`, `--underline` sets underlined mode. - -Using the *normal* keyword will reset foreground, background, and all formatting back to default. - -\subsection set_color-notes Notes - -1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal. -2. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. -3. Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than increasing the weight of text. -4. `set_color` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of `isatty stdout` before using `set_color` can be useful to decide not to colorize output in a script. - -\subsection set_color-example Examples - -\fish -set_color red; echo "Roses are red" -set_color blue; echo "Violets are blue" -set_color 62A; echo "Eggplants are dark purple" -set_color normal; echo "Normal is nice" # Resets the background too -\endfish - -\subsection set_color-detection Terminal Capability Detection - -Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting `fish_term256` to *1*. If `$TERM` contains "256color" (e.g., *xterm-256color*), 256-color support is enabled. If `$TERM` contains *xterm*, 256 color support is enabled (except for MacOS: `$TERM_PROGRAM` and `$TERM_PROGRAM_VERSION` are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports `xterm` and only supports 16 colors. - -If terminfo reports 256 color support for a terminal, support will always be enabled. To debug color palette problems, `tput colors` may be useful to see the number of colors in terminfo for a terminal. Fish launched as `fish -d2` will include diagnostic messages that indicate the color support mode in use. - -Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterm, Gnome Terminal, Konsole, and iTerm2. Fish attempts to detect such terminals through various means in `config.fish` You can explicitly force that support via `set fish_term24bit 1`. - -The `set_color` command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will assume that all terminals can use the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape sequences if the terminfo definition indicates a color below 16 is not supported. - -Support for italics, dim, reverse, and other modes is not guaranteed in all terminal emulators. Fish attempts to determine if the terminal supports these modes even if the terminfo database may not be up-to-date. diff --git a/doc_src/source.txt b/doc_src/source.txt deleted file mode 100644 index 7b32654ee..000000000 --- a/doc_src/source.txt +++ /dev/null @@ -1,29 +0,0 @@ -\section source source - evaluate contents of file. - -\subsection source-synopsis Synopsis -\fish{synopsis} -source FILENAME [ARGUMENTS...] -somecommand | source -\endfish - -\subsection source-description Description - -`source` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. `fish < FILENAME`) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the `$argv` variable. The `$argv` variable will not include the name of the sourced file. - -If no file is specified and stdin is not the terminal, or if the file name '`-`' is used, stdin will be read. - -The return status of `source` is the return status of the last job to execute. If something goes wrong while opening or reading the file, `source` exits with a non-zero status. - -`.` (a single period) is an alias for the `source` command. The use of `.` is deprecated in favour of `source`, and `.` will be removed in a future version of fish. - - -\subsection source-example Example - -\fish -source ~/.config/fish/config.fish -# Causes fish to re-read its initialization file. -\endfish - -\subsection Caveats - -In fish versions prior to 2.3.0 the `$argv` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh. diff --git a/doc_src/status.txt b/doc_src/status.txt deleted file mode 100644 index 052121311..000000000 --- a/doc_src/status.txt +++ /dev/null @@ -1,70 +0,0 @@ -\section status status - query fish runtime information - -\subsection status-synopsis Synopsis -\fish{synopsis} -status -status is-login -status is-interactive -status is-block -status is-breakpoint -status is-command-substitution -status is-no-job-control -status is-full-job-control -status is-interactive-job-control -status current-command -status filename -status fish-path -status function -status line-number -status stack-trace -status job-control CONTROL-TYPE -status features -status test-feature FEATURE -\endfish - -\subsection status-description Description - -With no arguments, `status` displays a summary of the current login and job control status of the shell. - -The following operations (sub-commands) are available: - -- `is-command-substitution` returns 0 if fish is currently executing a command substitution. Also `-c` or `--is-command-substitution`. - -- `is-block` returns 0 if fish is currently executing a block of code. Also `-b` or `--is-block`. - -- `is-breakpoint` returns 0 if fish is currently showing a prompt in the context of a `breakpoint` command. See also the `fish_breakpoint_prompt` function. - -- `is-interactive` returns 0 if fish is interactive - that is, connected to a keyboard. Also `-i` or `--is-interactive`. - -- `is-login` returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. Also `-l` or `--is-login`. - -- `is-full-job-control` returns 0 if full job control is enabled. Also `--is-full-job-control` (no short flag). - -- `is-interactive-job-control` returns 0 if interactive job control is enabled. Also, `--is-interactive-job-control` (no short flag). - -- `is-no-job-control` returns 0 if no job control is enabled. Also `--is-no-job-control` (no short flag). - -- `current-command` prints the name of the currently-running function or command, like the deprecated `_` variable. - -- `filename` prints the filename of the currently running script. Also `current-filename`, `-f` or `--current-filename`. - -- `fish-path` prints the absolute path to the currently executing instance of fish. - -- `function` prints the name of the currently called function if able, when missing displays "Not a - function" (or equivalent translated string). Also `current-function`, `-u` or `--current-function`. - -- `line-number` prints the line number of the currently running script. Also `current-line-number`, `-n` or `--current-line-number`. - -- `stack-trace` prints a stack trace of all function calls on the call stack. Also `print-stack-trace`, `-t` or `--print-stack-trace`. - -- `job-control CONTROL-TYPE` sets the job control type, which can be `none`, `full`, or `interactive`. Also `-j CONTROL-TYPE` or `--job-control=CONTROL-TYPE`. - -- `features` lists all available feature flags. - -- `test-feature FEATURE` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized. - -\subsection status-notes Notes - -For backwards compatibility each subcommand can also be specified as a long or short option. For example, rather than `status is-login` you can type `status --is-login`. The flag forms are deprecated and may be removed in a future release (but not before fish 3.0). - -You can only specify one subcommand per invocation even if you use the flag form of the subcommand. diff --git a/doc_src/string.txt b/doc_src/string.txt deleted file mode 100644 index c4e63b414..000000000 --- a/doc_src/string.txt +++ /dev/null @@ -1,359 +0,0 @@ -\section string string - manipulate strings - -\subsection string-synopsis Synopsis -\fish{synopsis} -string escape [(-n | --no-quoted)] [--style=xxx] [STRING...] -string join [(-q | --quiet)] SEP [STRING...] -string join0 [(-q | --quiet)] [STRING...] -string length [(-q | --quiet)] [STRING...] -string lower [(-q | --quiet)] [STRING...] -string match [(-a | --all)] [(-e | --entire)] [(-i | --ignore-case)] [(-r | --regex)] - [(-n | --index)] [(-q | --quiet)] [(-v | --invert)] PATTERN [STRING...] -string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [(-N | --no-newline)] - [(-q | --quiet)] [STRING...] -string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --regex)] - [(-q | --quiet)] PATTERN REPLACEMENT [STRING...] -string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP - [STRING...] -string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] - [STRING...] -string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] - [STRING...] -string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] - [(-q | --quiet)] [STRING...] -string unescape [--style=xxx] [STRING...] -string upper [(-q | --quiet)] [STRING...] -\endfish - - -\subsection string-description Description - -`string` performs operations on strings. - -STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input. - -Arguments beginning with `-` are normally interpreted as switches; `--` causes the following arguments not to be treated as switches even if they begin with `-`. Switches and required arguments are recognized only on the command line. - -Most subcommands accept a `-q` or `--quiet` switch, which suppresses the usual output but exits with the documented status. - -The following subcommands are available. - -\subsection string-escape "escape" subcommand - -`string escape` escapes each STRING in one of three ways. The first is `--style=script`. This is the default. It alters the string such that it can be passed back to `eval` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If `-n` or `--no-quoted` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise. - -`--style=var` ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded. - -`--style=url` ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded. - -`--style=regex` escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded. - -`string unescape` performs the inverse of the `string escape` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing `string unescape --style=var (string escape --style=var $str)` will return the original string. There is no support for unescaping `--style=regex`. - -\subsection string-join "join" subcommand - -`string join` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise. - -\subsection string-join0 "join0" subcommand - -`string join` joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as `sort -z`. Exit status: 0 if at least one join was performed, or 1 otherwise. - -\subsection string-length "length" subcommand - -`string length` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise. - -\subsection string-lower "lower" subcommand - -`string lower` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the `-q` flag you can readily test whether a string is already lowercase. - -\subsection string-match "match" subcommand - -`string match` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless `-a` or `--all` is given, in which case all matches are reported. - -If you specify the `-e` or `--entire` then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to `grep` without the `-o` flag). You can, obviously, achieve the same result by prepending and appending `*` or `.*` depending on whether or not you have specified the `--regex` flag. The `--entire` flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the `string match` clearer. Without `--entire` and `--regex`, a PATTERN will need to match the entire STRING before it will be reported. - -Matching can be made case-insensitive with `--ignore-case` or `-i`. - -If `--index` or `-n` is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING. - -If `--regex` or `-r` is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless `--entire` is given. - -If `--invert` or `-v` is used the selected lines will be only those which do not match the given glob pattern or regular expression. - -Exit status: 0 if at least one match was found, or 1 otherwise. - -\subsection string-repeat "repeat" subcommand - -`string repeat` repeats the STRING `-n` or `--count` times. The `-m` or `--max` option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with `--count`. If both `--count` and `--max` are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both `--count` and `--max` will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If `-N` or `--no-newline` is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise. - -\subsection string-replace "replace" subcommand - -`string replace` is similar to `string match` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. - -If `-r` or `--regex` is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like `\t` as well as references to capturing groups by number or name as `$n` or `${n}`. - -If you specify the `-f` or `--filter` flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: `a_cmd | string match pattern | string replace pattern new_pattern`. You can instead just write `a_cmd | string replace --filter pattern new_pattern`. - -Exit status: 0 if at least one replacement was performed, or 1 otherwise. - -\subsection string-split "split" subcommand - -`string split` splits each STRING on the separator SEP, which can be an empty string. If `-m` or `--max` is specified, at most MAX splits are done on each STRING. If `-r` or `--right` is given, splitting is performed right-to-left. This is useful in combination with `-m` or `--max`. With `-n` or `--no-empty`, empty results are excluded from consideration (e.g. `hello\n\nworld` would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise. - -See also `read --delimiter`. - -\subsection string-split0 "split0" subcommand - -`string split0` splits each STRING on the zero byte (NUL). Options are the same as `string split` except that no separator is given. - -`split0` has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as `find -print0` or `sort -z`. See split0 examples below. - -\subsection string-sub "sub" subcommand - -`string sub` prints a substring of each string argument. The start of the substring can be specified with `-s` or `--start` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with `-l` or `--length`. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. - -\subsection string-trim "trim" subcommand - -`string trim` removes leading and trailing whitespace from each STRING. If `-l` or `--left` is given, only leading whitespace is removed. If `-r` or `--right` is given, only trailing whitespace is trimmed. The `-c` or `--chars` switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise. - -\subsection string-upper "upper" subcommand - -`string upper` converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the `-q` flag you can readily test whether a string is already uppercase. - -\subsection regular-expressions Regular Expressions - -Both the `match` and `replace` subcommand support regular expressions when used with the `-r` or `--regex` option. The dialect is that of PCRE2. - -In general, special characters are special by default, so `a+` matches one or more "a"s, while `a\+` matches an "a" and then a "+". `(a+)` matches one or more "a"s in a capturing group (`(?:XXXX)` denotes a non-capturing group). For the replacement parameter of `replace`, `$n` refers to the n-th group of the match. In the match parameter, `\n` (e.g. `\1`) refers back to groups. - -Some features include repetitions: -- `*` refers to 0 or more repetitions of the previous expression -- `+` 1 or more -- `?` 0 or 1. -- `{n}` to exactly n (where n is a number) -- `{n,m}` at least n, no more than m. -- `{n,}` n or more - -Character classes, some of the more important: -- `.` any character except newline -- `\d` a decimal digit and `\D`, not a decimal digit -- `\s` whitespace and `\S`, not whitespace -- `\w` a "word" character and `\W`, a "non-word" character -- `[...]` (where "..." is some characters) is a character set -- `[^...]` is the inverse of the given character set -- `[x-y]` is the range of characters from x-y -- `[[:xxx:]]` is a named character set -- `[[:^xxx:]]` is the inverse of a named character set -- `[[:alnum:]]` : "alphanumeric" -- `[[:alpha:]]` : "alphabetic" -- `[[:ascii:]]` : "0-127" -- `[[:blank:]]` : "space or tab" -- `[[:cntrl:]]` : "control character" -- `[[:digit:]]` : "decimal digit" -- `[[:graph:]]` : "printing, excluding space" -- `[[:lower:]]` : "lower case letter" -- `[[:print:]]` : "printing, including space" -- `[[:punct:]]` : "printing, excluding alphanumeric" -- `[[:space:]]` : "white space" -- `[[:upper:]]` : "upper case letter" -- `[[:word:]]` : "same as \w" -- `[[:xdigit:]]` : "hexadecimal digit" - -Groups: -- `(...)` is a capturing group -- `(?:...)` is a non-capturing group -- `\n` is a backreference (where n is the number of the group, starting with 1) -- `$n` is a reference from the replacement expression to a group in the match expression. - -And some other things: -- `\b` denotes a word boundary, `\B` is not a word boundary. -- `^` is the start of the string or line, `$` the end. -- `|` is "alternation", i.e. the "or". - -\subsection string-example Examples - -\fish{cli-dark} ->_ string length 'hello, world' -12 - ->_ set str foo ->_ string length -q $str; echo $status -0 -# Equivalent to test -n $str -\endfish - -\fish{cli-dark} ->_ string sub --length 2 abcde -ab - ->_ string sub -s 2 -l 2 abcde -bc - ->_ string sub --start=-2 abcde -de -\endfish - -\fish{cli-dark} ->_ string split . example.com -example -com - ->_ string split -r -m1 / /usr/local/bin/fish -/usr/local/bin -fish - ->_ string split '' abc -a -b -c -\endfish - -\fish{cli-dark} ->_ seq 3 | string join ... -1...2...3 -\endfish - -\fish{cli-dark} ->_ string trim ' abc ' -abc - ->_ string trim --right --chars=yz xyzzy zany -x -zan -\endfish - -\fish{cli-dark} ->_ echo \\x07 | string escape -cg -\endfish - -\fish{cli-dark} ->_ string escape --style=var 'a1 b2'\\u6161 -a1_20b2__c_E6_85_A1 -\endfish - -\subsection string-example-match-glob Match Glob Examples - -\fish{cli-dark} ->_ string match '?' a -a - ->_ string match 'a*b' axxb -axxb - ->_ string match -i 'a??B' Axxb -Axxb - ->_ echo 'ok?' | string match '*\\?' -ok? - -# Note that only the second STRING will match here. ->_ string match 'foo' 'foo1' 'foo' 'foo2' -foo - ->_ string match -e 'foo' 'foo1' 'foo' 'foo2' -foo1 -foo -foo2 - - ->_ string match 'foo?' 'foo1' 'foo' 'foo2' -foo1 -foo -foo2 - -\endfish - -\subsection string-example-match-regex Match Regex Examples - -\fish{cli-dark} ->_ string match -r 'cat|dog|fish' 'nice dog' -dog - ->_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) -dog1 -dog2 -cat3 -dog3 -cat4 -dog4 - ->_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 -2:34:56 -2 -34 -56 - ->_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur -papa -pa -murmur -mur - ->_ string match -r -a -n at ratatat -2 2 -4 2 -6 2 - ->_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' -0xBadC0de -\endfish - -\subsection string-example-split0 NUL Delimited Examples - -\fish{cli-dark} ->_ # Count files in a directory, without being confused by newlines. ->_ count (find . -print0 | string split0) -42 - ->_ # Sort a list of elements which may contain newlines ->_ set foo beta alpha\\ngamma ->_ set foo (string join0 $foo | sort -z | string split0) ->_ string escape $foo[1] -alpha\\ngamma -\endfish - -\subsection string-example-replace-literal Replace Literal Examples - -\fish{cli-dark} ->_ string replace is was 'blue is my favorite' -blue was my favorite - ->_ string replace 3rd last 1st 2nd 3rd -1st -2nd -last - ->_ string replace -a ' ' _ 'spaces to underscores' -spaces_to_underscores -\endfish - -\subsection string-example-replace-Regex Replace Regex Examples - -\fish{cli-dark} ->_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' -0 3.14 5 - ->_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' -right left $ - ->_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' -put a -here -\endfish - -\subsection string-example-repeat Repeat Examples - -\fish{cli-dark} ->_ string repeat -n 2 'foo ' -foo foo - ->_ echo foo | string repeat -n 2 -foofoo - ->_ string repeat -n 2 -m 5 'foo' -foofo - ->_ string repeat -m 5 'foo' -foofo -\endfish diff --git a/doc_src/suspend.txt b/doc_src/suspend.txt deleted file mode 100644 index 0fc9485b6..000000000 --- a/doc_src/suspend.txt +++ /dev/null @@ -1,15 +0,0 @@ -\section suspend suspend - suspend the current shell - -\subsection suspend-synopsis Synopsis -\fish{synopsis} -suspend [--force] -\endfish - -\subsection suspend-description Description - -`suspend` suspends execution of the current shell by sending it a -SIGTSTP signal, returning to the controlling process. It can be -resumed later by sending it a SIGCONT. In order to prevent suspending -a shell that doesn't have a controlling process, it will not suspend -the shell if it is a login shell. This requirement is bypassed -if the `--force` option is given or the shell is not interactive. \ No newline at end of file diff --git a/doc_src/switch.txt b/doc_src/switch.txt deleted file mode 100644 index 9bba2bb0d..000000000 --- a/doc_src/switch.txt +++ /dev/null @@ -1,39 +0,0 @@ -\section switch switch - conditionally execute a block of commands - -\subsection switch-synopsis Synopsis -\fish{synopsis} -switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\endfish - -\subsection switch-description Description - -`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed. - -Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames. - -Note that fish does not fall through on case statements. Only the first matching case is executed. - -Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. - - -\subsection switch-example Example - -If the variable \$animal contains the name of an animal, the following code would attempt to classify it: - -\fish -switch $animal - case cat - echo evil - case wolf dog human moose dolphin whale - echo mammal - case duck goose albatross - echo bird - case shark trout stingray - echo fish - case '*' - echo I have no idea what a $animal is -end -\endfish - -If the above code was run with `$animal` set to `whale`, the output -would be `mammal`. diff --git a/doc_src/test.txt b/doc_src/test.txt deleted file mode 100644 index 1f54f1b00..000000000 --- a/doc_src/test.txt +++ /dev/null @@ -1,166 +0,0 @@ -\section test test - perform tests on files and text - -\subsection test-synopsis Synopsis -\fish{synopsis} -test [EXPRESSION] -[ [EXPRESSION] ] -\endfish - -\subsection test-description Description - -Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments. - -The first form (`test`) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets (`[ [EXPRESSION ] ]`). - -This test is mostly POSIX-compatible. - -When using a variable as an argument for a test operator you should almost always enclose it in double-quotes. There are only two situations it is safe to omit the quote marks. The first is when the argument is a literal string with no whitespace or other characters special to the shell (e.g., semicolon). For example, `test -b /my/file`. The second is using a variable that expands to exactly one element including if that element is the empty string (e.g., `set x ''`). If the variable is not set, set but with no value, or set to more than one value you must enclose it in double-quotes. For example, `test "$x" = "$y"`. Since it is always safe to enclose variables in double-quotes when used as `test` arguments that is the recommended practice. - -\subsection test-files Operators for files and directories - -- `-b FILE` returns true if `FILE` is a block device. - -- `-c FILE` returns true if `FILE` is a character device. - -- `-d FILE` returns true if `FILE` is a directory. - -- `-e FILE` returns true if `FILE` exists. - -- `-f FILE` returns true if `FILE` is a regular file. - -- `-g FILE` returns true if `FILE` has the set-group-ID bit set. - -- `-G FILE` returns true if `FILE` exists and has the same group ID as the current user. - -- `-k FILE` returns true if `FILE` has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit. - -- `-L FILE` returns true if `FILE` is a symbolic link. - -- `-O FILE` returns true if `FILE` exists and is owned by the current user. - -- `-p FILE` returns true if `FILE` is a named pipe. - -- `-r FILE` returns true if `FILE` is marked as readable. - -- `-s FILE` returns true if the size of `FILE` is greater than zero. - -- `-S FILE` returns true if `FILE` is a socket. - -- `-t FD` returns true if the file descriptor `FD` is a terminal (TTY). - -- `-u FILE` returns true if `FILE` has the set-user-ID bit set. - -- `-w FILE` returns true if `FILE` is marked as writable; note that this does not check if the filesystem is read-only. - -- `-x FILE` returns true if `FILE` is marked as executable. - -\subsection test-strings Operators for text strings - -- `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical. - -- `STRING1 != STRING2` returns true if the strings `STRING1` and `STRING2` are not identical. - -- `-n STRING` returns true if the length of `STRING` is non-zero. - -- `-z STRING` returns true if the length of `STRING` is zero. - -\subsection test-numbers Operators to compare and examine numbers - -- `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal. - -- `NUM1 -ne NUM2` returns true if `NUM1` and `NUM2` are not numerically equal. - -- `NUM1 -gt NUM2` returns true if `NUM1` is greater than `NUM2`. - -- `NUM1 -ge NUM2` returns true if `NUM1` is greater than or equal to `NUM2`. - -- `NUM1 -lt NUM2` returns true if `NUM1` is less than `NUM2`. - -- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`. - -Both integers and floating point numbers are supported. - -\subsection test-combinators Operators to combine expressions - -- `COND1 -a COND2` returns true if both `COND1` and `COND2` are true. - -- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true. - -Expressions can be inverted using the `!` operator: - -- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if `EXPRESSION` is true. - -Expressions can be grouped using parentheses. - -- `( EXPRESSION )` returns the value of `EXPRESSION`. - - Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution. - - -\subsection test-example Examples - -If the `/tmp` directory exists, copy the `/etc/motd` file to it: - -\fish -if test -d /tmp - cp /etc/motd /tmp/motd -end -\endfish - -If the variable `MANPATH` is defined and not empty, print the contents. (If `MANPATH` is not defined, then it will expand to zero arguments, unless quoted.) - -\fish -if test -n "$MANPATH" - echo $MANPATH -end -\endfish - -Parentheses and the `-o` and `-a` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a `/foo` or `/bar` file as well as a `/baz` or `/bat` file. - -\fish -if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) - echo Success. -end. -\endfish - -Numerical comparisons will simply fail if one of the operands is not a number: - -\fish -if test 42 -eq "The answer to life, the universe and everything" - echo So long and thanks for all the fish # will not be executed -end -\endfish - -A common comparison is with $status: - -\fish -if test $status -eq 0 - echo "Previous command succeeded" -end -\endfish - -The previous test can likewise be inverted: - -\fish -if test ! $status -eq 0 - echo "Previous command failed" -end -\endfish - -which is logically equivalent to the following: - -\fish -if test $status -ne 0 - echo "Previous command failed" -end -\endfish - -\subsection test-standards Standards - -`test` implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply: - -- The `<` and `>` operators for comparing strings are not implemented. - -- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the `test` utility in another shell. - - In cases such as this, one can use `command` `test` to explicitly use the system's standalone `test` rather than this `builtin` `test`. diff --git a/doc_src/trap.txt b/doc_src/trap.txt deleted file mode 100644 index 3c8d8a963..000000000 --- a/doc_src/trap.txt +++ /dev/null @@ -1,37 +0,0 @@ -\section trap trap - perform an action when the shell receives a signal - -\subsection trap-synopsis Synopsis -\fish{synopsis} -trap [OPTIONS] [[ARG] REASON ... ] -\endfish - -\subsection trap-description Description - -`trap` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an event handler. - -The following parameters are available: - -- `ARG` is the command to be executed on signal delivery. - -- `REASON` is the name of the event to trap. For example, a signal like `INT` or `SIGINT`, or the special symbol `EXIT`. - -- `-l` or `--list-signals` prints a list of signal names. - -- `-p` or `--print` prints all defined signal handlers. - -If `ARG` and `REASON` are both specified, `ARG` is the command to be executed when the event specified by `REASON` occurs (e.g., the signal is delivered). - -If `ARG` is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If `ARG` is the null string the signal specified by each `REASON` is ignored by the shell and by the commands it invokes. - -If `ARG` is not present and `-p` has been supplied, then the trap commands associated with each `REASON` are displayed. If no arguments are supplied or if only `-p` is given, `trap` prints the list of commands associated with each signal. - -Signal names are case insensitive and the `SIG` prefix is optional. - -The return status is 1 if any `REASON` is invalid; otherwise trap returns 0. - -\subsection trap-example Example - -\fish -trap "status --print-stack-trace" SIGUSR1 -# Prints a stack trace each time the SIGUSR1 signal is sent to the shell. -\endfish diff --git a/doc_src/true.txt b/doc_src/true.txt deleted file mode 100644 index 1418c1ed4..000000000 --- a/doc_src/true.txt +++ /dev/null @@ -1,10 +0,0 @@ -\section true true - return a successful result - -\subsection true-synopsis Synopsis -\fish{synopsis} -true -\endfish - -\subsection true-description Description - -`true` sets the exit status to 0. diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr deleted file mode 100644 index bce1349ab..000000000 --- a/doc_src/tutorial.hdr +++ /dev/null @@ -1,727 +0,0 @@ -/** -\page tutorial Tutorial -\htmlonly[block] -
- -
-\endhtmlonly -- Why fish? -- Getting started -- Learning fish -- Running Commands -- Getting Help -- Syntax Highlighting -- Wildcards -- Pipes and Redirections -- Autosuggestions -- Tab Completions -- Variables -- Exit Status -- Shell Variables -- Lists -- Command Substitutions -- Separating Commands (Semicolon) -- Combiners (And, Or, Not) -- Conditionals (If, Else, Switch) -- Functions -- Loops -- Prompt -- $PATH -- Startup -- Autoloading Functions -- Universal Variables -- Switching to fish -- Ready for more? - -\htmlonly[block] -
-
- -
-

fish tutorial

-\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. - -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_getting_started Getting started - -Once installed, just type in `fish` into your current shell to try it out! - -You will be greeted by the standard fish prompt, -which means you are all set up and can start using fish: - -\fish{cli-dark} -> fish -Welcome to fish, the friendly interactive shell -Type help for instructions on how to use fish -you@hostname ~>____ -\endfish - -This prompt that you see above is the `fish` default prompt: it shows your username, hostname, and working directory. -- to change this prompt see how to change your prompt -- to switch to fish permanently see switch your default shell to fish - -From now on, we'll pretend your prompt is just a '`>`' to save space. - - -\section tut_learning_Fish Learning fish - -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 unlike other shells, which is used to call out important differences. - - -\section tut_running_commands Running Commands - -`fish` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators: - -\fish{cli-dark} ->_ echo hello world -hello world -\endfish - -You can include a literal space in an argument with a backslash, or by using single or double quotes: - -\fish{cli-dark} ->_ mkdir My\ Files ->_ cp ~/Some\ File 'My Files' ->_ ls "My Files" -Some File -\endfish - -Commands can be chained with semicolons. - - -\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 -set - handle shell variables - Synopsis... -\endfish - - -\section tut_syntax_highlighting Syntax Highlighting - -You'll quickly notice that `fish` performs syntax highlighting as you type. Invalid commands are colored red by default: - -\fish{cli-dark} ->_ /bin/mkd -\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: - -\fish{cli-dark} ->_ /bin/mkdir -\endfish - -`fish` will underline valid file paths as you type them: - -\fish{cli-dark} ->_ cat ~/somefi___ -\endfish - -This tells you that there exists a file that starts with '`somefi`', which is useful feedback as you type. - -These colors, and many more, can be changed by running `fish_config`, or by modifying variables directly. - - -\section tut_wildcards Wildcards - -`fish` supports the familiar wildcard `*`. To list all JPEG files: - -\fish{cli-dark} ->_ ls *.jpg -lena.jpg -meena.jpg -santa maria.jpg -\endfish - -You can include multiple wildcards: - -\fish{cli-dark} ->_ ls l*.p* -lena.png -lesson.pdf -\endfish - -Especially powerful is the recursive wildcard ** which searches directories recursively: - -\fish{cli-dark} ->_ ls /var/**.log -/var/log/system.log -/var/run/sntp.log -\endfish - -If that directory traversal is taking a long time, you can @key{Control,C} out of it. - - -\section tut_pipes_and_redirections Pipes and Redirections - -You can pipe between commands with the usual vertical bar: - -\fish{cli-dark} ->_ echo hello world | wc - 1 2 12 -\endfish - -stdin and stdout can be redirected via the familiar < and >. stderr is redirected with a 2>. - -\fish{cli-dark} ->_ grep fish < /etc/shells > ~/output.txt 2> ~/errors.txt -\endfish - - -\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} ->_ /bin/h___ostname -\endfish - -It knows about paths and options: - -\fish{cli-dark} ->_ grep --i___gnore-case -\endfish - -And history too. Type a command once, and you can re-summon it by just typing a few letters: - -\fish{cli-dark} ->_ r<___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo -\endfish - -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. - -\section tut_tab_completions Tab Completions - -`fish` comes with a rich set of tab completions, that work "out of the box." - -Press @key{Tab}, and `fish` will attempt to complete the command, argument, or path: - -\fish{cli-dark} ->_ /pri @key{Tab} → /private/ -\endfish - -If there's more than one possibility, it will list them: - -\fish{cli-dark} ->_ ~/stuff/s @key{Tab} -~/stuff/script.sh (Executable, 4.8kB) \mtch{~/stuff/sources/ (Directory)} -\endfish - -Hit tab again to cycle through the possibilities. - -`fish` can also complete many commands, like git branches: - -\fish{cli-dark} ->_ git merge pr @key{Tab} → git merge prompt_designer ->_ git checkout b @key{Tab} -builtin_list_io_merge (Branch) \mtch{builtin_set_color (Branch) busted_events (Tag)} -\endfish - -Try hitting tab and see what `fish` can do! - -\section tut_variables Variables - -Like other shells, a dollar sign performs variable substitution: - -\fish{cli-dark} ->_ echo My home directory is $HOME -My home directory is /home/tutorial -\endfish - -Variable substitution also occurs in double quotes, but not single quotes: - -\fish{cli-dark} ->_ echo "My current directory is $PWD" -My current directory is /home/tutorial ->_ echo 'My current directory is $PWD' -My current directory is $PWD -\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. - -\fish{cli-dark} ->_ set name 'Mister Noodle' ->_ echo $name -Mister Noodle -\endfish - -(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.) - -Unlike other shells, variables are not further split after substitution: - -\fish{cli-dark} ->_ mkdir $name ->_ ls -Mister Noodle -\endfish - -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. Other shells use the term "arrays", rather than lists. - - -\section tut_exit_status Exit Status - -Unlike other shells, `fish` stores the exit status of the last command in `$status` instead of `$?`. - -\fish{cli-dark} ->_ false ->_ echo $status -1 -\endfish - -Zero is considered success, and non-zero is failure. - - -\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`. - -\fish{cli-dark} ->_ set -x MyVariable SomeValue ->_ env | grep MyVariable -MyVariable=SomeValue -\endfish - -You can erase a variable with `-e` or `--erase` - -\fish{cli-dark} ->_ set -e MyVariable ->_ env | grep MyVariable -(no output) -\endfish - - -\section tut_lists Lists - -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. - -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. - -Other variables, like `$PATH`, really do have multiple values. During variable expansion, the variable expands to become multiple arguments: - -\fish{cli-dark} ->_ echo $PATH -/usr/bin /bin /usr/sbin /sbin /usr/local/bin -\endfish - -Note that there are three environment variables that are automatically split on colons to become lists when fish starts running: `PATH`, `CDPATH`, `MANPATH`. Conversely, they are joined on colons when exported to subcommands. All other environment variables (e.g., `LD_LIBRARY_PATH`) which have similar semantics are treated as simple strings. - -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 -5 -\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: - -\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: - -\fish{cli-dark} ->_ echo $PATH -/usr/bin /bin /usr/sbin /sbin /usr/local/bin ->_ echo $PATH[1] -/usr/bin ->_ echo $PATH[-1] -/usr/local/bin -\endfish - -You can also access ranges of elements, known as "slices:" - -\fish{cli-dark} ->_ echo $PATH[1..2] -/usr/bin /bin ->_ echo $PATH[-1..2] -/usr/local/bin /sbin /usr/sbin /bin -\endfish - -You can iterate over a list (or a slice) with a for loop: - -\fish{cli-dark} ->_ for val in $PATH - echo "entry: $val" - end -entry: /usr/bin/ -entry: /bin -entry: /usr/sbin -entry: /sbin -entry: /usr/local/bin -\endfish - -Lists adjacent to other lists or strings are expanded as cartesian products unless quoted (see Variable expansion): - -\fish{cli-dark} ->_ set a 1 2 3 ->_ set 1 a b c ->_ echo $a$1 -1a 2a 3a 1b 2b 3b 1c 2c 3c ->_ echo $a" banana" -1 banana 2 banana 3 banana ->_ echo "$a banana" -1 2 3 banana -\endfish - -This is similar to Brace expansion. - -\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: - -\fish{cli-dark} ->_ echo In (pwd), running (uname) -In /home/tutorial, running FreeBSD -\endfish - -A common idiom is to capture the output of a command in a variable: - -\fish{cli-dark} ->_ set os (uname) ->_ echo $os -Linux -\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: - -\fish{cli-dark} ->_ touch "testing_"(date +%s)".txt" ->_ ls *.txt -testing_1360099791.txt -\endfish - -Unlike other shells, fish does not split command substitutions on any whitespace (like spaces or tabs), only newlines. This can be an issue with commands like `pkg-config` that print what is meant to be multiple arguments on a single line. To split it on spaces too, use `string split`. - -\fish{cli-dark} ->_ printf '%s\n' (pkg-config --libs gio-2.0) --lgio-2.0 -lgobject-2.0 -lglib-2.0 ->_ printf '%s\n' (pkg-config --libs gio-2.0 | string split " ") --lgio-2.0 --lgobject-2.0 --lglib-2.0 -\endfish - - -\section tut_semicolon Separating Commands (Semicolon) -Like other shells, fish allows multiple commands either on separate lines or the same line. - -To write them on the same line, use the semicolon (";"). That means the following two examples are equivalent: - -\fish -echo fish; echo chips - -# or -echo fish -echo chips -\endfish - - -\section tut_combiners Combiners (And, Or, Not) - -fish supports the familiar `&&` and `||` to combine commands, and `!` to negate them: - -\fish{cli-dark} ->_ ./configure && make && sudo make install -\endfish - -fish also supports `and`, `or`, and `not`. The first two are job modifiers and have lower precedence. Example usage: - -\fish{cli-dark} ->_ cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt ; and echo "Backup successful"; or echo "Backup failed" -Backup failed -\endfish - -As mentioned in the section on the semicolon, this can also be written in multiple lines, like so: - -\fish -cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt -and echo "Backup successful" -or echo "Backup failed" -\endfish - - -\section tut_conditionals Conditionals (If, Else, Switch) - -Use `if`, `else if`, and `else` to conditionally execute code, based on the exit status of a command. - -\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 - -To compare strings or numbers or check file properties (whether a file exists or is writeable and such), use test, like - -\fish{cli-dark} -if test "$fish" = "flounder" - echo FLOUNDER -end - -# or - -if test "$number" -gt 5 - echo $number is greater than five -else - echo $number is five or less -end -\endfish - -Combiners can also be used to make more complex conditions, like - -\fish -if grep fish /etc/shells; and command -sq fish - echo fish is installed and configured -end -\endfish - -For even more complex conditions, use `begin` and `end` to group parts of them. - -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. - - -\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 `$1`, but instead in a single list `$argv`. To create a function, use the `function` builtin: - -\fish{cli-dark} ->_ function say_hello - echo Hello $argv - end ->_ say_hello -Hello ->_ say_hello everybody! -Hello everybody! -\endfish - -Unlike other shells, `fish` does not have aliases or special prompt syntax. Functions take their place. - -You can list the names of all functions with the `functions` keyword (note the plural!). `fish` starts out with a number of functions: - -\fish{cli-dark} ->_ functions -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, trap, type, umask, up-or-search, vared -\endfish - -You can see the source for any function by passing its name to `functions`: - -\fish{cli-dark} ->_ functions ls -function ls --description 'List contents of directory' - command ls -G $argv -end -\endfish - - -\section tut_loops Loops - -While loops: - -\fish{cli-dark} ->_ while true - echo "Loop forever" -end -Loop forever -Loop forever -Loop forever -... -\endfish - -For loops can be used to iterate over a list. For example, a list of files: - -\fish{cli-dark} ->_ for file in *.txt - cp $file $file.bak -end -\endfish - -Iterating over a list of numbers can be done with `seq`: - -\fish{cli-dark} ->_ for x in (seq 5) - touch file_$x.txt -end -\endfish - - -\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 `fish_prompt`, and its output is used as the prompt. - -You can define your own prompt: - -\fish{cli-dark} ->_ function fish_prompt - echo "New Prompt % " -end -New Prompt % ___ -\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 -02/06/13 -/home/tutorial >___ -\endfish - -You can choose among some sample prompts by running `fish_config prompt`. `fish` also supports RPROMPT through `fish_right_prompt`. - -\section tut_path $PATH - -`$PATH` is an environment variable containing the directories in which `fish` searches for commands. Unlike other shells, $PATH is a [list](#tut_lists), not a colon-delimited string. - -To prepend /usr/local/bin and /usr/sbin to `$PATH`, you can write: - -\fish{cli-dark} ->_ set PATH /usr/local/bin /usr/sbin $PATH -\endfish - -To remove /usr/local/bin from `$PATH`, you can write: - -\fish{cli-dark} ->_ set PATH (string match -v /usr/local/bin $PATH) -\endfish - -You can do so directly in `config.fish`, like you might do in other shells with `.profile`. See [this example](#path_example). - -A faster way is to modify the `$fish_user_paths` [universal variable](#tut_universal), which is automatically prepended to `$PATH`. For example, to permanently add `/usr/local/bin` to your `$PATH`, you could write: - -\fish{cli-dark} ->_ set -U fish_user_paths /usr/local/bin $fish_user_paths -\endfish - -The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to `config.fish`. If you do, the variable will get longer each time you run fish!) - -\section tut_startup Startup (Where's .bashrc?) - -`fish` starts by executing commands in `~/.config/fish/config.fish`. You can create it if it does not exist. - -It is possible to directly create functions and variables in `config.fish` file, using the commands shown above. For example: - - -\fish{cli-dark} ->_ cat ~/.config/fish/config.fish - -set -x PATH $PATH /sbin/ - -function ll - ls -lh $argv -end -\endfish - -However, it is more common and efficient to use autoloading functions and universal variables. - -\section tut_autoload Autoloading Functions - -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/`. - -For example, if you wanted to have a function `ll`, you would add a text file `ll.fish` to `~/.config/fish/functions`: - -\fish{cli-dark} ->_ cat ~/.config/fish/functions/ll.fish -function ll - ls -lh $argv -end -\endfish - -This is the preferred way to define your prompt as well: - -\fish{cli-dark} ->_ cat ~/.config/fish/functions/fish_prompt.fish -function fish_prompt - echo (pwd) "> " -end -\endfish - -See the documentation for funced and funcsave for ways to create these files automatically. - -\section tut_universal Universal Variables - -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`: - -\fish{cli-dark} ->_ set -U EDITOR vim -\endfish - -Now in another shell: - -\fish{cli-dark} ->_ echo $EDITOR -vim -\endfish - - -\section tut_switching_to_fish Switching to fish? - -If you wish to use fish (or any other shell) as your default shell, -you need to enter your new shell's executable `/usr/local/bin/fish` in two places: -- add `/usr/local/bin/fish` to `/etc/shells` -- change your default shell with `chsh -s /usr/local/bin/fish` - -You can use the following commands for this: - -Add the fish shell `/usr/local/bin/fish` -to `/etc/shells` with: - -\fish{cli-dark} ->echo /usr/local/bin/fish | sudo tee -a /etc/shells -\endfish - -Change your default shell to fish with: - -\fish{cli-dark} ->chsh -s /usr/local/bin/fish -\endfish - -(To change it back to another shell, just substitute `/usr/local/bin/fish` -with `/bin/bash`, `/bin/tcsh` or `/bin/zsh` as appropriate in the steps above.) - - -\section tut_more Ready for more? - -If you want to learn more about fish, there is lots of detailed documentation, an official mailing list, the IRC channel \#fish on `irc.oftc.net`, and the github page. - -\htmlonly[block] -
-\endhtmlonly -*/ diff --git a/doc_src/type.txt b/doc_src/type.txt deleted file mode 100644 index 13a0836d3..000000000 --- a/doc_src/type.txt +++ /dev/null @@ -1,34 +0,0 @@ -\section type type - indicate how a command would be interpreted - -\subsection type-synopsis Synopsis -\fish{synopsis} -type [OPTIONS] NAME [NAME ...] -\endfish - -\subsection type-description Description - -With no options, `type` indicates how each `NAME` would be interpreted if used as a command name. - -The following options are available: - -- `-a` or `--all` prints all of possible definitions of the specified names. - -- `-f` or `--no-functions` suppresses function and builtin lookup. - -- `-t` or `--type` prints `function`, `builtin`, or `file` if `NAME` is a shell function, builtin, or disk file, respectively. - -- `-p` or `--path` prints the path to `NAME` if `NAME` resolves to an executable file in $PATH, the path to the script containing the definition of the function `NAME` if `NAME` resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt), or nothing otherwise. - -- `-P` or `--force-path` returns the path to the executable file `NAME`, presuming `NAME` is found in $PATH, or nothing otherwise. `--force-path` explicitly resolves only the path to executable files in $PATH, regardless of whether `$NAME` is shadowed by a function or builtin with the same name. - -- `-q` or `--quiet` suppresses all output; this is useful when testing the exit status. - -The `-q`, `-p`, `-t` and `-P` flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time. - - -\subsection type-example Example - -\fish{cli-dark} ->_ type fg -fg is a builtin -\endfish diff --git a/doc_src/ulimit.txt b/doc_src/ulimit.txt deleted file mode 100644 index 86ffe2b6f..000000000 --- a/doc_src/ulimit.txt +++ /dev/null @@ -1,64 +0,0 @@ -\section ulimit ulimit - set or get resource usage limits - -\subsection ulimit-synopsis Synopsis -\fish{synopsis} -ulimit [OPTIONS] [LIMIT] -\endfish - -\subsection ulimit-description Description - -`ulimit` builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value. - -Use one of the following switches to specify which resource limit to set or report: - -- `-c` or `--core-size`: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled. - -- `-d` or `--data-size`: the maximum size of a process' data segment. - -- `-f` or `--file-size`: the maximum size of files created by the shell. - -- `-l` or `--lock-size`: the maximum size that may be locked into memory. - -- `-m` or `--resident-set-size`: the maximum resident set size. - -- `-n` or `--file-descriptor-count`: the maximum number of open file descriptors (most systems do not allow this value to be set). - -- `-s` or `--stack-size`: the maximum stack size. - -- `-t` or `--cpu-time`: the maximum amount of CPU time in seconds. - -- `-u` or `--process-count`: the maximum number of processes available to a single user. - -- `-v` or `--virtual-memory-size` The maximum amount of virtual memory available to the shell. - -Note that not all these limits are available in all operating systems. - -The value of limit can be a number in the unit specified for the resource or one of the special values `hard`, `soft`, or `unlimited`, which stand for the current hard limit, the current soft limit, and no limit, respectively. - -If limit is given, it is the new value of the specified resource. If no option is given, then `-f` is assumed. Values are in kilobytes, except for `-t`, which is in seconds and `-n` and `-u`, which are unscaled values. The return status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit. - -`ulimit` also accepts the following switches that determine what type of limit to set: - -- `-H` or `--hard` sets hard resource limit - -- `-S` or `--soft` sets soft resource limit - -A hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither -H nor -S is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value. - -The following additional options are also understood by `ulimit`: - -- `-a` or `--all` prints all current limits - -The `fish` implementation of `ulimit` should behave identically to the implementation in bash, except for these differences: - -- Fish `ulimit` supports GNU-style long options for all switches - -- Fish `ulimit` does not support the `-p` option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish. - -- Fish `ulimit` does not support getting or setting multiple limits in one command, except reporting all values using the -a switch - - -\subsection ulimit-example Example - -`ulimit -Hs 64` sets the hard stack size limit to 64 kB. - diff --git a/doc_src/umask.txt b/doc_src/umask.txt deleted file mode 100644 index 7429d8a9e..000000000 --- a/doc_src/umask.txt +++ /dev/null @@ -1,41 +0,0 @@ -\section umask umask - set or get the file creation mode mask - -\subsection umask-synopsis Synopsis -\fish{synopsis} -umask [OPTIONS] [MASK] -\endfish - -\subsection umask-description Description - -`umask` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files. - -The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which represents the only rights that will be granted by default. - -Access rights are explained in the manual page for the `chmod`(1) program. - -With no parameters, the current file creation mode mask is printed as an octal number. - -- `-h` or `--help` prints this message. - -- `-S` or `--symbolic` prints the umask in symbolic form instead of octal form. - -- `-p` or `--as-command` outputs the umask in a form that may be reused as input - -If a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default. - -If a symbolic mask is specified, the desired permission bits, and not the inverse, should be specified. A symbolic mask is a comma separated list of rights. Each right consists of three parts: - -- The first part specifies to whom this set of right applies, and can be one of `u`, `g`, `o` or `a`, where `u` specifies the user who owns the file, `g` specifies the group owner of the file, `o` specific other users rights and `a` specifies all three should be changed. - -- The second part of a right specifies the mode, and can be one of `=`, `+` or `-`, where `=` specifies that the rights should be set to the new value, `+` specifies that the specified right should be added to those previously specified and `-` specifies that the specified rights should be removed from those previously specified. - -- The third part of a right specifies what rights should be changed and can be any combination of `r`, `w` and `x`, representing read, write and execute rights. - -If the first and second parts are skipped, they are assumed to be `a` and `=`, respectively. As an example, `r,u+w` means all users should have read access and the file owner should also have write access. - -Note that symbolic masks currently do not work as intended. - - -\subsection umask-example Example - -`umask 177` or `umask u=rw` sets the file creation mask to read and write for the owner and no permissions at all for any other users. diff --git a/doc_src/user_doc.css b/doc_src/user_doc.css deleted file mode 100644 index f514892c2..000000000 --- a/doc_src/user_doc.css +++ /dev/null @@ -1,269 +0,0 @@ -* { - margin: 0; - box-sizing: border-box; -} -html { font-size: 62.5%; } -html, body { - min-height: 100%; - background: #fff; - color: #111; -} -body { - overflow: hidden; -} -.logo { - width: 210px; - height: 147px; - margin-left: 2rem; - margin-bottom: -3rem; - background-image: url(ascii_fish.png); -} -/*Top site index*/ -.qindex { - font: 500 1.4rem/3.6rem DejaVuSansCondensed, "DejaVu Sans", Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; - font-stretch: condensed; - border: none; - color: white; - text-align: center; - position: relative; - background-color: #1f2d53; - width: 100%; - height: 3.6rem; -} -/* Don't show the header */ -.header { display: none; } -/*Substructure*/ -.contents { - margin: 0; - min-width: 570px; -} -.fish_left_bar, .fish_right_bar, .fish_only_bar { - position: absolute; - top: 3.6rem; - bottom: 0; - overflow-y: scroll; - -webkit-overflow-scrolling: touch; /* necessary for momentum scrolling */ - font: 400 1.3rem/2.1rem "DejaVu Sans", Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; -} -.fish_left_bar { - width: 25rem; - color: white; - font-family: DejaVuSansCondensed, "DejaVu Sans", Roboto, "Lucida Grande", Calibri, Verdana, "Helvetica Neue", Helvetica, Arial, sans-serif; - font-stretch: condensed; - background-color: #1f2d53; -} -.fish_right_bar { - margin-left: 25rem; - margin-right: 0; - padding: 0 3rem; - box-shadow: -0.3rem 0.3rem 1rem #000818; -} -.fish_only_bar { - width: 100%; - padding-bottom: 3rem; -} -hr { - height: 0; - border: none; - border-top: 1px solid #AAA; -} -/*Interaction*/ -a { color: #3d5cb3; } -.qindex a { - color: white; - text-decoration: none; -} -.qindex a:hover { text-decoration: underline; } -.fish_left_bar a { - color: white; - text-decoration: none; -} -.fish_left_bar a:visited { color: inherit; } -.fish_left_bar a:hover { color: #88aaff; } -.fish_right_bar a { text-decoration: none; } -.fish_right_bar a:hover { text-decoration: underline; } -/* Adjust lists */ -.fish_left_bar ul { - padding-left: 2rem; - padding-right: 1rem; -} -.fish_right_bar ul { - list-style-type: circle; - padding-left: 2.4rem; - margin: 1.4rem 0; -} -.fish_right_bar ul li { - margin-bottom: 0.6rem; -} -/* Typography */ -p { margin: 1rem 0; } -h1, h2, h3, h4, h5, h6 { - color: #1f2d53; - font-family: DejaVuSansCondensed-Bold, "DejaVu Sans", Roboto, "Lucida Grande", Calibri, Verdana, sans-serif; - font-stretch: condensed; -} -h1 { - margin: 1.6rem 0 1rem 0; - font-weight: 700; - font-size: 2.5rem; -} -h2 { - margin: 1.6rem 0 1rem 0; - font-weight: 700; - font-size: 1.7rem; -} -h3 { - margin: 1rem 0 0.4rem 0; - font-weight: 500; - font-size: 1.5rem; -} -.interior_title { - font-size: 2rem; - margin: 2rem 0 1.4rem 0; - color: #414141; - padding-bottom: 10px; - border-bottom: 1px solid #AAA; -} -/* Special Formmating */ -/* Keyboard */ -.key span { - display:none; -} -.key em { - font-style: normal; - margin-right: 2px; -} -.key em, .key b { - padding: 1px 4px; - background-color: #fafafa; - background: linear-gradient(to bottom, #eee 0%,#fafafa 100%); - border: 1px solid #bbb; - border-radius: 3px; - font-weight: normal; - white-space: nowrap; - box-shadow: 0 1px 2px #ddd; -} -/* Console display */ -tt, code, pre, .fish { - font-family: "DejaVu Sans Mono", "Source Code Pro", Menlo, "Ubuntu Mono", Consolas, Monaco, "Lucida Console", monospace, fixed; - font-weight: 500; - text-shadow: 0 0 0 rgba(0,0,0,0.4); /*Stronger anti-aliasing*/ - white-space: -moz-pre-wrap; - white-space: -pre-wrap; - white-space: -o-pre-wrap; - white-space: pre-wrap; - word-wrap: break-word; -} - -/*Default 'light' console*/ -.fish { - margin: 1rem 0; - padding: 0.6rem 1rem; - font-size: 1.2rem; - line-height: 1.8rem; - color: #111; - background-color: #fafafa; - border: 1px solid #bbb; - border-radius: 0.6rem; - box-shadow: 0 0.2rem 0.2rem #eee; -} -.comment, .suggest { color: #555; } -.command, .function, .binary { color: #223aa4; } -.argument, .path, .file { color: #5961cf; } -.operator, .variable, .match, .history { color: #1c8885; } -.string, .string .operator { color: #858904; } - -/* Synopsis variant */ -.synopsis { - border: none; - color: #333; - text-shadow: 0 0 0 rgba(0,0,0,0.2); - background: none; - font-size: 1.3rem; - padding: 0; - box-shadow: none; -} -.synopsis .comment, .synopsis .suggest { color: #669; } -.synopsis .command, .synopsis .function, .synopsis .binary { color: #333; } -.synopsis .argument, .synopsis .path, .synopsis .file { color: #666; } - -/* Console variants */ -.cli-dark { - background-color: #222; - color: #ccc; - text-shadow: none; - padding: 0.6rem 1.2rem; - border-radius: 0.6rem; -} -.cli-dark .key em, .cli-dark .key b { - background-color: #ccc; - box-shadow: 0 0.1rem 0 #666; - border: 1px solid #333; - color: #000; - padding: 0 3px; -} -.cli-dark .comment { color: #c33; } -.cli-dark .command, .cli-dark .function, .cli-dark .binary { color: #6159de; } -.cli-dark .argument, .cli-dark .path, .cli-dark .file { color: #00afff; } -.cli-dark .redirect { color: #fff; } -.cli-dark .operator,.cli-dark .variable, .cli-dark .match, .cli-dark .history { color: #2ff; } -.cli-dark .string { color: #b3b206; } -.cli-dark .suggest, .cli-dark em { color: #777; } -.cli-dark .match { color: #2ff; } -.cli-dark .search_match { background-color: #a100a3; } -.cli-dark .cwd, .cli-dark .prompt .path { color: #2f2; } -.cli-dark .prompt { color: #999; } -.cli-dark .cursor { border-bottom: 2px solid #3F3; } -.cli-dark .underline { color: #00afff; text-decoration: underline; } -.cli-dark .error, .cli-dark .error .path { color: #f55; font-weight: bold; } - - -/*Menus*/ -.menu { margin: 1.4rem 0; line-height: 2.2rem; } -.menu ul { list-style-type: none; } -.menu > ul li { position: relative; } -.menu > ul li:before { - content: "›"; - color: #88aaff; - font-size: 1.6rem; - position: absolute; - left: -1rem; - top: -1px; -} -/*Page overrides*/ -/*Documentation*/ -.docs_menu { line-height: 2rem; } -.docs_menu > ul > li { position: static; } -.docs_menu > ul ul { margin: 0.6rem 0; } -.docs_menu > ul ul > li { margin-bottom: 0.2rem; } -/*Tutorial*/ -.tutorial_menu { margin-left: 2rem; } -/*Design*/ -.design { - max-width: 780px; - margin: 0 auto; - padding: 0 4rem; -} -/*Commands*/ -.commands_menu { line-height: 2rem; margin-left: 2rem; } -/*FAQ*/ -.faq_menu { line-height: 2rem; margin-top: 4rem; margin-right: 2rem;} -.faq_menu > ul > li { position: static; } -.faq_menu > ul li { margin-bottom: 0.6rem; } - -/*Licenses*/ -.license { - max-width: 780px; - margin: 0 auto; - padding: 0 4rem; -} -.license li { margin: 1rem 0; } -.license ul li:first-child { - list-style-type: none; - position: relative; -} -.license ul li:first-child:before { - content: "0."; - position: absolute; - left: -2rem; -} diff --git a/doc_src/user_doc.footer.html b/doc_src/user_doc.footer.html deleted file mode 100644 index 308b1d01b..000000000 --- a/doc_src/user_doc.footer.html +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/doc_src/user_doc.header.html b/doc_src/user_doc.header.html deleted file mode 100644 index 59f0b4b3d..000000000 --- a/doc_src/user_doc.header.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -$projectname: $title -$extrastylesheet - - -
-fish shell -| -Documentation -| -Tutorial -| -Design -| -Commands -| -FAQ -| -License diff --git a/doc_src/vared.txt b/doc_src/vared.txt deleted file mode 100644 index 352357872..000000000 --- a/doc_src/vared.txt +++ /dev/null @@ -1,15 +0,0 @@ -\section vared vared - interactively edit the value of an environment variable - -\subsection vared-synopsis Synopsis -\fish{synopsis} -vared VARIABLE_NAME -\endfish - -\subsection vared-description Description - -`vared` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using `vared`, but individual array elements can. - - -\subsection vared-example Example - -`vared PATH[3]` edits the third element of the PATH array diff --git a/doc_src/wait.txt b/doc_src/wait.txt deleted file mode 100644 index 57aa27318..000000000 --- a/doc_src/wait.txt +++ /dev/null @@ -1,34 +0,0 @@ -\section wait wait - wait for jobs to complete - -\subsection wait-synopsis Synopsis -\fish{synopsis} -wait [-n | --any] [PID | PROCESS_NAME] ... -\endfish - -\subsection wait-description Description - -`wait` waits for child jobs to complete. - -- If a pid is specified, the command waits for the job that the process with the pid belongs to. -- If a process name is specified, the command waits for the jobs that the matched processes belong to. -- If neither a pid nor a process name is specified, the command waits for all background jobs. -- If the `-n` / `--any` flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete. - -\subsection wait-example Example - -\fish -sleep 10 & -wait $last_pid -\endfish -spawns `sleep` in the background, and then waits until it finishes. -\fish -for i in (seq 1 5); sleep 10 &; end -wait -\endfish -spawns five jobs in the background, and then waits until all of them finishes. -\fish -for i in (seq 1 5); sleep 10 &; end -hoge & -wait sleep -\endfish -spawns five jobs and `hoge` in the background, and then waits until all `sleep`s finishes, and doesn't wait for `hoge` finishing. diff --git a/doc_src/while.txt b/doc_src/while.txt deleted file mode 100644 index 5fb851768..000000000 --- a/doc_src/while.txt +++ /dev/null @@ -1,22 +0,0 @@ -\section while while - perform a command multiple times - -\subsection while-synopsis Synopsis -\fish{synopsis} -while CONDITION; COMMANDS...; end -\endfish - -\subsection while-description Description - -`while` repeatedly executes `CONDITION`, and if the exit status is 0, then executes `COMMANDS`. - -The exit status of the while loop is the exit status of the last iteration of the `COMMANDS` executed, -or 0 if none were executed. (This matches other shells and is POSIX-compatible.) - -You can use `and` or `or` for complex conditions. Even more complex control can be achieved with `while true` containing a break. - -\subsection while-example Example - -\fish -while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end -# outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists. -\endfish