The previous command outputs a lot of junk, does not strip after the
white-space in OSX (10.8.2).
Tried out the new command on both Ubuntu (12.04.1) and OSX (10.8.2)
- Fix branch for older git version (--short for symbolic-ref was not
available on git 1.7.9.5)
- Use index (git status) for checking if staged
- Add status indication for copied
- Remove variables for statuses (less litter in the variables)
- Remove usage of eval to echo and set_color
- Replace printf where possible with echo -n
After updating, fish would immediately die when started in an xterm from
my window manager (wmii) with a message like:
fish: builtin.cpp:3357: int builtin_end(parser_t&, wchar_t**): Assertion `false' failed.
fish: Job 1, “~/code/fish-shell/fish†terminated by signal SIGABRT (Abort)
Starting fish from an existing shell worked, and running it on other
machines that I was only SSHing into worked as well. I did discover that
on one machine starting git from one specific directory
(/home/ian/bml/kernel) would cause this failure, but starting from any
other directory worked as normal. I'm not entirely sure what
circumstances contribute to this failure - starting from a copy of the
kernel directory works fine.
The failure only started with the following commit, which introduced the
assert(false):
commit d788c84440
Made type property of block_t constant and private
Further work towards cleaning up block_t hierarchy
Looking at this fail in gdb:
(gdb) r
Starting program: /home/ian/code/fish-shell/fish
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
fish: builtin.cpp:3357: int builtin_end(parser_t&, wchar_t**): Assertion `false' failed.
Program received signal SIGABRT, Aborted.
0x00007ffff6c82475 in *__GI_raise (sig=<optimized out>) at ../nptl/sysdeps/unix/sysv/linux/raise.c:64
64 ../nptl/sysdeps/unix/sysv/linux/raise.c: No such file or directory.
(gdb) bt
function=0x548520 "int builtin_end(parser_t&, wchar_t**)") at assert.c:81
(gdb) up 3
3357 assert(false); //should never get here
(gdb) p parser.current_block->type()
$1 = FAKE
So this happens when we run an end command for a FAKE block.
The below patch adds an empty case for FAKE blocks to avoid hitting the
assert. I would need to study the code in more detail to understand if
we should even be executing this code if we are in a FAKE block, but
this patch seems to solve the issue for me.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
In both in python2 and python3 parse_qs expects str object. In
python2 it worked ok, because self.rfile was open in binary mode and
str in python2 is actually a string of bytes. However in python3 str is
actually string of unicode literals, not bytes and file was still open
in binary mode. Thus, deleting any file with non-ascii byte inside
filename failed in python3.
Also, cgi.parse_qs is deprecated and shouldn't be used.
The __fish_git_prompt_show_upstream helper function was inadvertently
looking at the misnamed variable __fish_git_prompt_show_upstream in some
cases, including when implementing the bash.showUpstream override.
Fixing the script to use __fish_git_prompt_showupstream triggered an
infinite loop because the --on-variable hook does not distinguish
between local and global variables.
Update the script to set a completely different local variable to
__fish_git_prompt_showupstream and to override this local variable for
bash.showUpstream.
Also update the code that looks at bash.showUpstream to also read
bash.showupstream, because the bash script appears to have a bug where
it looks for bash.showupstream despite documenting bash.showUpstream.
Git-svn remotes can have a prefix for their remotes. If I set a prefix
of 'svn/' then my remote trunk branch is called svn/trunk. Update the
script to use the svn-remote.*.fetch key to figure out how the 'trunk'
branch is mapped into the remotes namespace and apply this to the
current branch. This assumes branches are mapped into the same
namespace, which is likely. It also doesn't work for tags, but neither
did the old code.
- etc/config.fish and share/config.fish are now "universal" and no longer reference install paths or need to be touched by autotools. They've been removed from config.fish.in to config.fish.
- fish now attempts to determine __fish_datadir and __fish_sysconfdir relative to the path of the fish executable itself (typically by walking up one directory). This means that you can copy the directory hierarchy around and things will still work. The compiled-in paths are used as a backup.
- The fish Xcode project now can build fish natively, without needing autotools.
- Version bumped to 2.0
Fish now doesn't join the fish_prompt output. This breaks the default
fish_prompt. Make default fish_prompt single-line. Fixes#203.
Add -l flag to 'read' documentation. Remove ambiguous '-x' description.
Fixes#157.
Builtin 'set' now can set variable index ranges:
set test[1..3] a b c #works
set test[-1..-3] a b c #works if variable have enough elements
set test[2..-2] a b c #works
set test[1..3 -1..-2] a b c b b #works
Expand now can parse index ranges. But not handle for now.
TODO:
* Add variable substitution index ranges: echo $PATH[-1..1]
* Add command substitution index range: echo (seq 10)[-1..-4]
* Add process substitution indexes and ranges: echo %vim[-1]
Fish now doesn't join the fish_prompt output. This breaks the default
fish_prompt. Make default fish_prompt single-line. Fixes#203.
Add -l flag to 'read' documentation. Remove ambiguous '-x' description.
Fixes#157.
Remove the case statements, which were handled by the sed blocks anyway
Move around the '/' character in the regex, so only one regex is needed
Fix a bug where '/' is output as '//'
The following expression now works:
```sh
switch '\\'
case '\\'
echo 1
end
```
Due to ambiguity, the following expression also works:
```sh
switch '\a'
case '\\a'
echo 1
end
```
By the way, the following expression now doesn't work, which was not the
case before, because of wrong escaping:
```sh
switch 'nn'
case '\n'
echo 1
end
```
* case no properly handles -h and --help flags, i.e. treats it as
pattern
* fixed case escaping:
The following expressions now work correctly:
switch '*'
echo '*'
echo Match any string
end
switch '*'
echo '\*'
echo Match asterix
end
switch '\\'
echo '\\\\'
echo Match slash
end
The same for '?' sign
Autosuggestion will be automatically re-enabled next time a character is
inserted. An alternative implementation would require another command to
explicitly re-enable it.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
This can be demonstrated with something like:
echo howdy hi<control-w>
echo howdy I<alt-b>
Previousely this would delete/move all the way to the start of 'howdy',
rather than just the word 'hi'/'I'.
It seems that the code to ignore the character under the cursor was
redundant, as all the cases I've tried with it removed seem to do the
right thing.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
* Editor mode is no the default
* Use -i or --interactive or -e fish to edit function in interactive
mode
* tmpname is now created with random number added and check that file
do not already exist
* check $TMPDIR existence and put /tmp if it does not exist
* There is an undocumented feature to use functions, started with dash.
Introduce necessary changes to funced, functions, def_function()
in order to make it work properly.
* Delete editor guessing. Use $EDITOR variable or -e key
fish_pager_color_secondary to set background of every second completion
line. It simplifies finding the options corresponding to given
description. Default color is 151515.
With the switch bug fixed, __fish_git_prompt can be very slightly
simplified by not recording the exit status of every case in the
describe style switch individually.
The echo command to print the last path segment got a couplel of fixes,
but these fixes were only applied to the non-Darwin version. Copy these
fixes over to the Darwin version. Notably, this makes `/` stop
displaying as `//`.
When $PWD is "/private", the prompt was printing "rivate". Skip the
"/private" stripping if there's nothing after it.
Prevent "/private" from being stripped anywhere but the beginning of the
PWD.
Fixes#173
__fish_config_interactive.fish uses the presence of __fish_init_1_50_0
to decide whether it should perform a one-time initialization of
universal variables. Unfortunately, it sets the variable
__fish_init_1_23_0. Fix this to set __fish_init_1_50_0 instead.
__fish_git_prompt.fish is a complete port of the __git_ps1 function from
git-completion.bash, with the relevant configuration variables changed
and some extra configuration added (namely, control over individual
colors and the status indicator characters).
* Seems that writestr( L"\x1b];" ); doesn't work in tmux and
screen. As discussed in fish-shell/fish-shell#47 the 2 was
removed. This commit adds the zero (L"\x1b]0;").
* Tested in screen,tmux,iTerm and xterm.
If doxygen isn't installed, an empty file called user_doc will be created.
If doxygen is later installed, the documentation will not generate correctly.
- Was an opening tag, should have been a closing tag
- Confused Doxygen 1.8.1.1 on my machine (OS X 10.7), resulting in the fish man pages not being installed at all
Renamed autosuggest_handle_special to autosuggest_special_validate_from_history
Began work to factor autosuggest_special_validate_from_history together with autosuggest_suggest_special
This should fix the bug where output from commands and builtins gets incorrectly interleaved.
I think this is a very long-standing bug that predates my work on the shell
__fish_complete_subcommand
* sudo:
- now can be completed bu group and user (-u and -g keys).
- subcommand completion is fixed
* __fish_complete_proc.fish is added to complete killall command with
list of running processes
* __fish_complete_tex.fish is updated with common options
* __fish_make_completion_signals.fish is added to make a list of kill
signals for kill and killall
* completions:
- minor filetype completions are added for djview, xpdf, mupdf, gv,
xdvi
- adduser is copmleted by user and group
- dlocate and dpkg are completed by packages
- find: -executable options is added
- htop: options
- funced and funcsave are completed by function names
- ifdown and ifup are copmleted by interfaces
- kill and killall: options, signals and processes
- latexmk, ln, nm: options
- lualatex and xelatex copmletions
- sudo: -u and -g options
- wvdial: presets
I find that if I have a config.fish consisting of the following two
lines
status --job-control full
. empty.fish
where empty.fish is just an empty file in ~/.config/fish, Fish will
hang when I attempt to log in on a virtual console (e.g. tty1). If I run
Fish within X11 or with either of those lines commented out,
everything's fine. I think the second line can be any command that cause
Fish to perform a fork().
The fix is pretty simple and just involves replacing getpid() with
getpgrp() in terminal_return_from_job in proc.c. See below for the
detailed explanation. I'm certainly no expert so I would appreciate it
if anyone else can confirm that my fix looks ok.
Here's what causes the bug as far as I can tell:
1. When I login on a virtual console, /bin/login calls Fish. When Fish
begins executing its process group and the process group controlling the
terminal are both the pid of the /bin/login process.
2. The ". empty.fish" line causes Fish to fork a new process. The new
process creates a new process group and takes control of the terminal
under the name of that process group.
3. When the child process finishes, the parent prcoess attempts to take
back control of the terminal by setting its controlling process group id
to be its pid.
4. Now there is a mismatch between the process group id of the Fish
shell (= the pid of the /bin/login process) and the process group id
controlling the terminal (= the pid of the Fish shell).
reader_interactive_init detects the mismatch and it thinks that it
doesn't have control of the terminal, so it hangs as it waits for
control.
My fix just solves the problem in step 3 by having the parent process
correctly reassign control of the terminal to its process group.
Signed-off-by: Grissiom <chaos.proton@gmail.com>
On my system at least (fedora 15), git-symbolic-ref is an invalid
command. Not sure if it's a BIC change from git itself, a distribution
thing, or a mistake on my end. Either way, no harm in using the
extended version. Now I get git branch status (yay).
The first defaults.list file found should not override all the other ones,
it just needs to be searched first.
E.g. For me (cat ~/.local/share/applications/defaults.list) returns
[Default Applications]
text/html=chromium-browser.desktop
So this should be used for text/html mimetypes, but the other defaults.list
files should be searched for other mimetypes.
I had to refactor get_filename so that it can return all the filenames, so
I changed it to append_filenames that appends all the filenames to a list
and provided a wrapper function called get_filename.
On Gentoo the eix program is MUCH faster than emerge for listing package
names. I've left the emerge code in as a 2nd choice because not every
Gentoo system has eix installed (although they should). Also, the
emerge code didn't seem to produce any output on my system.
Signed-off-by: Grissiom <chaos.proton@gmail.com>
get_filename tried to work around this with hardcoded strings that end with
a '/', but would fail to work properly for environment variables
XDG_DATA_HOME or XDG_DATA_DIRS that don't do the same.
Renamed references to the previous command name of save_function to
funcsave, and returned an error after printing the help text when no
arguments are specified.
It is documented this way, but the common builtin_run function was
checking for -h or --help before even calling the builtin_count. Without
this functions like funced can't use count to check the number of
arguments before checking for -h or --help.
Signed-off-by: Grissiom <chaos.proton@gmail.com>
Treat fish_greeting as a whole when show up the greeting messages. And
the user may want to set fish_greeting to an null value or an array.
This requires that the variable be quoted when used as an argument for
switch in __fish_config_interactive.
Signed-off-by: James Vega <jamessan@debian.org>
[modified the commit message]
Signed-off-by: Grissiom <chaos.proton@gmail.com>
The builtin function returns the raw status, which is not the same as
the integer return by waitpid. Therefore, the WIF macros shouldn't be
used for checking or obtaining the status.
This bug can be seen by executing (eval false). The builtin eval
function returns 1, but proc_format_status misinterprets it as a signal
by checking WIFSIGNALED, so adds 128 to the status to return 129.
Signed-off-by: Grissiom <chaos.proton@gmail.com>
Previously the expression only searched for anchors with a name
attribute, but doxygen 1.7.1 is producing anchors with the id attribute
instead. The sed expression allows both cases for compatibility.
I also used single quotes for the sed expression to avoid escaping
double quotes.
Signed-off-by: Grissiom <chaos.proton@gmail.com>
This also caused (isatty < /dev/null) to return 0 since it uses eval,
and (ls | cat) to output using the classify indicator style since it
uses isatty. This is how I found the bug.
Reviewed-by: Grissiom <chaos.proton@gmail.com>
docdir was previously being set to "${prefix}/share/doc/${PACKAGE_NAME}"
when it wasn't explicitely set on configuration using --docdir. Without
this appearing in the Makefile, some files silently get silently
installed directly into ${prefix}/share/doc instead within a fish
subdirectory.
I also added datarootdir to fix an autoconf warning, since autoconf
normally would use it for the directory paths (e.g. docdir =
${datarootdir}/doc/${PACKAGE_TARNAME}). The autoconf generated configure
script has a hack to fix this, but states: "FIXME: This hack should be
removed a few years after 2.60."
a command to accept the "copy". So, you add your clipboard buffer command
to an environment variable, and custom commands will be used for the copy
program. Very useful when your OS is not naitively supported by fish.
Way to reproduce:
> set -e TERM
fish: function contains_internal called with null value for argument a.
fish: This is a bug. If you can reproduce it, please send a bug report
to fish-users@lists.sf.net.
fish: Backtrace:
/home/grissiom/sysroot/bin/fish(show_stackframe+0x1a) [0x43519a]
/home/grissiom/sysroot/bin/fish(contains_internal+0xce) [0x4373ee]
/home/grissiom/sysroot/bin/fish(reader_write_title+0x59) [0x424179]
/home/grissiom/sysroot/bin/fish() [0x4242d5]
/home/grissiom/sysroot/bin/fish(reader_readline+0x54) [0x425974]
/home/grissiom/sysroot/bin/fish(reader_read+0xba) [0x42742a]
/home/grissiom/sysroot/bin/fish(main+0x4be) [0x43b19e]
/lib64/libc.so.6(__libc_start_main+0xfd) [0x7fcbe0dcbb6d]
/home/grissiom/sysroot/bin/fish() [0x408c29]
This commit makes fish_parse_opt stop at first non-option argument,
which expected as fish script name and pass the remaining argument to
that script. I also updated the test cases.
Now matches function create behaviour, running the new function name through
wcsfuncname() and parser_keywords_is_reserved(), before allowing the copy.
Copying the function implementation was the main point. Actually removing the original isn't necessary, as that
functionality already exists (functions -e).
Aim is to allow an existing function to be renamed, allowing some basic function chaining.
Example:
> function foo
echo Hello
end
> foo
Hello
> functions --rename foo bar
> foo
fish: Unknown command 'foo'
> bar
Hello
> functions --rename fish_prompt old_prompt
> function fish_prompt
printf "{Boo!}%s" (old_prompt)
end
{Boo!}>
Note in the last case, the new fish_prompt is calling its old definition.
recently, as the incorrect arguments were being passed to execve. The
function went through the trouble of creating the proper arguments, and
then failed to use them.
darcs-hash:20080104015631-2d839-1d79a7810fcc3e2a3788dabdbc22d13a4bd4f404.gz
Add a function which checks that an option has not been used (useful to avoid
incompatible combinations of options and necessary for the completions for
the pacman package manager.
darcs-hash:20071217230315-782a0-be39b1258832f0d2427765200d051e5d688b041b.gz
There are various terminfo entries for screen that should be recognized aside from simply 'screen' such as 'screen-256color' and 'screen-bce'.
darcs-hash:20071013184358-35ec8-5e85add3cc1667781590e12118a98ec6641bc714.gz
Shells such as bash, sh, tcsh, and ksh each support a "colon command" that causes the script to be
evaluated as a bourne script. In the case of bash and sh, this command is a no-op. For others,
it means the script has sh syntax.
To suppor this in fish, I've added code to launch_process that checks for a ':' as the first
character of p->actual_cmd. If it is a colon, the process descriptor is modified to call
/bin/sh, which should exist on any POSIX system.
darcs-hash:20061208220428-5830d-6bde4f1a3e8100296a60c21f9e47988e20688a77.gz
Completions for all tools which come with eix.
(http://dev.croup.de/proj/eix)
darcs-hash:20061110155925-a923b-fd06120f7ea5f65cb752fe437bfccb6f16c87b45.gz
- You don't need to supply the package right after -C or -u etc.
- Better descriptions
darcs-hash:20061109145341-a923b-a1a54d3a5a040396ccba350c125f3b1ba645c601.gz
The current method of gettext detection is broken on (at least) OS X and Solaris, where which always returns successfully. This method seems to work on Linux, OS X, and Solaris.
darcs-hash:20060313014458-c90d9-8b169581a8632b6a47c61310ef3c976abd67d8e0.gz
Tweak to fallback.h to make it compile under OS X. As shipped with fish 1.21.2, this causes a lot of warnings and then dies.
darcs-hash:20060313014333-c90d9-de59932f81dd6debbfb48225893983df485df12b.gz
Command-line completions for svn. This includes some tweaks to the cvs completions file, to move a common function out into fish_complete.fish.
darcs-hash:20060210004314-494f2-c12a77084499cbc4216e8c5603ae4fadfb6b384c.gz
Better completions for cvs. Covers most flags in the manual, except for some for history that I couldn't write good descriptions for. Descriptions could probably use some tweaking, but the basic structure should be much better than what we had before.
darcs-hash:20060208023146-494f2-bea009421c161257f09c0f53c52ab1ee116fc3dc.gz
Tweak the open function to use /usr/bin/open on Darwin, and mimedb on everything else.
darcs-hash:20060206012623-494f2-e4626c03895065837f0c8981482d5b16313dfc08.gz
Changed __fish_describe_command to use awk instead of sed, and handle 'alternative' names, as used by OS X. (And possibly some BSDs?)
darcs-hash:20060205221805-494f2-85a48edd8e6fbcfc1dcd28079e4adfa52a0466d0.gz
Tweaked prompt_pwd and pwd to omit the leading /private from some system directories on OS X.
darcs-hash:20060205194908-494f2-936d1346a4cd118f763bea24495edf9829b59748.gz
Without this check, it would be possible to attempt to source a directory and get stuck in an infinite loop.
darcs-hash:20051215172122-35ec8-b3ce05d8d7ee9534edf92b74ca842d034b894e8a.gz
[fish](http://ridiculousfish.com/shell/) - the friendly interactive shell
================================================
fish is a smart and user-friendly command line shell for OS X, Linux, and the rest of the family. fish includes features like syntax highlighting, autosuggest-as-you-type, and fancy tab completions that just work, with no configuration required.
For more on fish's design philosophy, see the [design document](http://ridiculousfish.com/shell/user_doc/html/design.html).
## Quick Start
fish generally works like other shells, like bash or zsh. A few important differences are documented at <http://ridiculousfish.com/shell/faq.html>
Detailed user documentation is available by running `help` within fish, and also at <http://ridiculousfish.com/shell/user_doc/html/>
## Building
fish can be built using autotools or Xcode.
### Autotools Build
autoconf
./configure [--without-xsel]
make [gmake on BSD]
sudo make install
### Xcode Development Build
* Build the `base` target in Xcode
* Run the fish executable, for example, in `DerivedData/FishsFish/Build/Products/Debug/base/bin/fish`
// Note that we record the last checked time after the call, on the assumption that in a slow filesystem, the lag comes before the kernel check, not after.
/* Note that we are NOT locked in this function! */
size_ti;
boolreloaded=0;
/* Try using a cached function. If we really want the function to be loaded, require that it be really loaded. If we're not reloading, allow stale functions. */
{
boolallow_stale_functions=!reload;
/* Take a lock */
scoped_locklocker(lock);
/* Get the function */
autoload_function_t*func=this->get_node(cmd);
/* Determine if we can use this cached function */
/* Remove any loaded command because we are going to reload it. Note that this will deadlock if command_removed calls back into us. */
if(func&&func->is_loaded){
command_removed(cmd);
func->is_placeholder=false;
}
/* Mark that we're reloading it */
reloaded=true;
}
/* Create the function if we haven't yet. This does not load it. Do not trigger eviction unless we are actually loading, because we don't want to evict off of the main thread. */
Autoload the specified file, if it exists in the specified path. Do
not load it multiple times unless it's timestamp changes or
parse_util_unload is called.
Autoloading one file may unload another.
\param cmd the filename to search for. The suffix '.fish' is always added to this name
\param on_unload a callback function to run if a suitable file is found, which has not already been run. unload will also be called for old files which are unloaded.
\param reload wheter to recheck file timestamps on already loaded files
*/
intload(constwcstring&cmd,boolreload);
/** Check whether we have tried loading the given command. Does not do any I/O. */
boolhas_tried_loading(constwcstring&cmd);
/**
Tell the autoloader that the specified file, in the specified path,
is no longer loaded.
\param cmd the filename to search for. The suffix '.fish' is always added to this name
\param on_unload a callback function which will be called before (re)loading a file, may be used to unload the previous file.
\return non-zero if the file was removed, zero if the file had not yet been loaded
*/
intunload(constwcstring&cmd);
/**
Unloads all files.
*/
voidunload_all();
/** Check whether the given command could be loaded, but do not load it. */
This is the_ridiculous'fish s delightful fork of, fish friendly interactive shell. For more information, visit http://ridiculousfish.com/shell/ .
This installer will install fish, but will not modify your /etc/shells file or your default shell. I trust you know how to do that yourself if you care to!
\f0\fs30 \cf0 This installs ridiculous_fish's fork of fish, a command line shell for Mac OS X, Linux, and the rest of the family. For more information on fish, visit {\field{\*\fldinst{HYPERLINK "http://ridiculousfish.com/shell/"}}{\fldrslt http://ridiculousfish.com/shell/}}\
\
The path to fish will be added to /etc/shells, but your default shell will not be modified. \
#define BUILTIN_ERR_COMBO L": Invalid combination of options"
#define BUILTIN_ERR_COMBO _( L"%ls: Invalid combination of options\n" )
/**
Error message on invalid combination of options
*/
#define BUILTIN_ERR_COMBO2 _( L"%ls: Invalid combination of options,\n%ls\n" )
/**
Error message on multiple scope levels for variables
*/
#define BUILTIN_ERR_GLOCAL L": Variable can only be one of universal, global and local"
#define BUILTIN_ERR_GLOCAL _( L"%ls: Variable scope can only be one of universal, global and local\n" )
/**
Error message for specifying both export and unexport to set/read
*/
#define BUILTIN_ERR_EXPUNEXP L": Variable can't be both exported and unexported"
#define BUILTIN_ERR_EXPUNEXP _( L"%ls: Variable can't be both exported and unexported\n" )
/**
Error message for unknown switch
*/
#define BUILTIN_ERR_UNKNOWN L": Unknown option"
#define BUILTIN_ERR_VARCHAR L"%ls: Invalid character in variable name: '%lc'. Only alphanumerical characters and underscores are valid in a variable name.\n"
#define BUILTIN_ERR_VARNAME_ZERO L"%ls: Variable name can not be the empty string\n"
Error message for invalid character in variable name
*/
externstring_buffer_t*sb_out;
#define BUILTIN_ERR_VARCHAR _( L"%ls: Invalid character '%lc' in variable name. Only alphanumerical characters and underscores are valid in a variable name.\n" )
/**
Stringbuffer used to represent standard error
Error message for invalid (empty) variable name
*/
externstring_buffer_t*sb_err;
#define BUILTIN_ERR_VARNAME_ZERO _( L"%ls: Variable name can not be the empty string\n" )
/**
Error message when second argument to for isn't 'in'
*/
#define BUILTIN_FOR_ERR_IN _( L"%ls: Second argument must be 'in'\n" )
/**
Error message for insufficient number of arguments
*/
#define BUILTIN_FOR_ERR_COUNT _( L"%ls: Expected at least two arguments, got %d\n")
#define BUILTIN_FOR_ERR_NAME _( L"%ls: '%ls' is not a valid variable name\n" )
/** Error messages for 'else if' */
#define BUILTIN_ELSEIF_ERR_COUNT _( L"%ls: can only take 'if' and then another command as an argument\n")
#define BUILTIN_ELSEIF_ERR_ARGUMENT _( L"%ls: any second argument must be 'if'\n")
/**
Error message when too many arguments are supplied to a builtin
*/
#define BUILTIN_ERR_TOO_MANY_ARGUMENTS _( L"%ls: Too many arguments\n" )
/**
Error message when block types mismatch in the end builtin, e.g. 'begin; end for'
*/
#define BUILTIN_END_BLOCK_MISMATCH _( L"%ls: Block mismatch: '%ls' vs. '%ls'\n" )
/**
Error message for unknown block type in the end builtin, e.g. 'begin; end beggin'
*/
#define BUILTIN_END_BLOCK_UNKNOWN _( L"%ls: Unknown block type '%ls'\n" )
#define BUILTIN_ERR_NOT_NUMBER _( L"%ls: Argument '%ls' is not a number\n" )
/** Get the string used to represent stdout and stderr */
constwcstring&get_stdout_buffer();
constwcstring&get_stderr_buffer();
/** Output an error */
voidbuiltin_show_error(constwcstring&err);
/**
Kludge. Tells builtins if output is to screen
@@ -80,72 +125,58 @@ void builtin_destroy();
/**
Is there a builtin command with the given name?
*/
intbuiltin_exists(wchar_t*cmd);
intbuiltin_exists(constwcstring&cmd);
/**
Execute a builtin command
\param parser The parser being used
\param argv Array containing the command and parameters
of the builtin. The list is terminated by a
null pointer. This syntax resembles the syntax
for exec.
\param io the io redirections to perform on this builtin.
/* Combining expression. Contains a list of AND or OR expressions. It takes more than two so that we don't have to worry about precedence in the parser. */
/* Evaluate our lists, remembering that AND has higher precedence than OR. We can visualize this as a sequence of OR expressions of AND expressions. */
assert(combiners.size()+1==subjects.size());
assert(!subjects.empty());
size_tidx=0,max=subjects.size();
boolor_result=false;
while(idx<max){
if(or_result){
/* Short circuit */
break;
}
/* Evaluate a stream of AND starting at given subject index. It may only have one element. */
/* IEEE 1003.1 says nothing about what it means for two strings to be "algebraically equal". For example, should we interpret 0x10 as 0, 10, or 16? Here we use only base 10 and use wcstoll, which allows for leading + and -, and leading whitespace. This matches bash. */
Under curses, tputs expects an int (*func)(char) as its last
parameter, but in ncurses, tputs expects a int (*func)(int) as its
last parameter. tputs_arg_t is defined to always be what tputs
expects. Hopefully.
*/
classcompletion_t;
#ifdef NCURSES_VERSION
typedefinttputs_arg_t;
#else
typedefchartputs_arg_t;
#endif
/* Common string type */
typedefstd::wstringwcstring;
typedefstd::vector<wcstring>wcstring_list_t;
/**
Maximum number of bytes used by a single utf-8 character
@@ -32,15 +34,55 @@ typedef char tputs_arg_t;
#define MAX_UTF8_BYTES 6
/**
Color code for set_color. Does not update the color.
This is in the unicode private use area.
*/
#define FISH_COLOR_IGNORE -1
#define ENCODE_DIRECT_BASE 0xf100
/**
Color code for set_color. Sets the default color.
Highest legal ascii value
*/
#define FISH_COLOR_RESET -2
#define ASCII_MAX 127u
/**
Highest legal 16-bit unicode value
*/
#define UCS2_MAX 0xffffu
/**
Highest legal byte value
*/
#define BYTE_MAX 0xffu
/**
Escape special fish syntax characters like the semicolon
*/
#define UNESCAPE_SPECIAL 1
/**
Allow incomplete escape sequences
*/
#define UNESCAPE_INCOMPLETE 2
/* Flags for the escape() and escape_string() functions */
enum{
/** Escape all characters, including magic characters like the semicolon */
ESCAPE_ALL=1<<0,
/** Do not try to use 'simplified' quoted escapes, and do not use empty quotes as the empty string */
ESCAPE_NO_QUOTED=1<<1,
/** Do not escape tildes */
ESCAPE_NO_TILDE=1<<2
};
typedefunsignedintescape_flags_t;
/**
Helper macro for errors
*/
#define VOMIT_ON_FAILURE(a) do { if (0 != (a)) { int err = errno; fprintf(stderr, "%s failed on line %d in file %s: %d (%s)\n", #a, __LINE__, __FILE__, err, strerror(err)); abort(); }} while (0)
/** Exits without invoking destructors (via _exit), useful for code after fork. */
/* Useful macro for asserting that a lock is locked. This doesn't check whether this thread locked it, which it would be nice if it did, but here it is anyways. */
/** Our crappier versions of debug which is guaranteed to not allocate any memory, or do anything other than call write(). This is useful after a call to fork() with threads. */
Exit program at once, leaving an error message about running out of memory
*/
voiddie_mem();
Loop a read request while failiure is non-critical. Return -1 and set errno
in case of critical error.
*/
ssize_tread_loop(intfd,void*buff,size_tcount);
/**
Clean up
*/
voidcommon_destroy();
/**
Issue a debug message with printf-style string formating and
automatic line breaking. The string will begin with the string \c
program_name, followed by a colon and a whitespace.
Because debug is often called to tell the user about an error,
before using wperror to give a specific error message, debug will
never ever modify the value of errno.
\param level the priority of the message. Lower number means higher priority. Messages with a priority_number higher than \c debug_level will be ignored..
\param msg the message format string.
@@ -302,7 +624,8 @@ void common_destroy();
will print the string 'fish: Pi = 3.141', given that debug_level is 1 or higher, and that program_name is 'fish'.
*/
voiddebug(intlevel,wchar_t*msg,...);
voiddebug(intlevel,constchar*msg,...);
voiddebug(intlevel,constwchar_t*msg,...);
/**
Replace special characters with backslash escape sequences. Newline is
Values are copied and should be freed by the caller.
All supplied values are copied, they should be freed by or otherwise
disposed by the caller.
Examples:
@@ -86,71 +197,60 @@ void complete_destroy();
file completion is not performed.
\param comp A space separated list of completions which may contain subshells.
\param desc A description of the completion.
\param authorative Whether there list of completions for this command is complete. If true, any options not matching one of the provided options will be flagged as an error by syntax highlighting.
\param condition a command to be run to check it this completion should be used. If \c condition is empty, the completion is always used.
\param flags A set of completion flags
*/
voidcomplete_add(constwchar_t*cmd,
intcmd_type,
wchar_tshort_opt,
constwchar_t*long_opt,
intlong_mode,
intresult_mode,
intauthorative,
constwchar_t*condition,
constwchar_t*comp,
constwchar_t*desc);
boolcmd_is_path,
wchar_tshort_opt,
constwchar_t*long_opt,
intlong_mode,
intresult_mode,
constwchar_t*condition,
constwchar_t*comp,
constwchar_t*desc,
intflags);
/**
Sets whether the completion list for this command is complete. If
true, any options not matching one of the provided options will be
/** Find all completions of the command cmd, insert them into out. If to_load is not NULL, append all commands that we would autoload, but did not (presumably because this is not the main thread) */
Tests if the specified option is defined for the specified command
*/
intcomplete_is_valid_option(constwchar_t*str,
constwchar_t*opt,
array_list_t*errors );
intcomplete_is_valid_option(constwcstring&str,
constwcstring&opt,
wcstring_list_t*inErrorsOrNull,
boolallow_autoload);
/**
Tests if the specified argument is valid for the specified option
and command
*/
intcomplete_is_valid_argument(constwchar_t*str,
constwchar_t*opt,
constwchar_t*arg);
boolcomplete_is_valid_argument(constwcstring&str,
constwcstring&opt,
constwcstring&arg);
/**
@@ -162,6 +262,18 @@ int complete_is_valid_argument( const wchar_t *str,
\param cmd the command for which to load command-specific completions
\param reload should the commands completions be reloaded, even if they where previously loaded. (This is set to true on actual completions, so that changed completion are updated in running shells)
*/
voidcomplete_load(wchar_t*cmd,intreload);
voidcomplete_load(constwcstring&cmd,boolreload);
/**
Create a new completion entry
\param completions The array of completions to append to
\section and and - Conditionally execute a command
\section and and - conditionally execute a command
\subsection and-synopsis Synopsis
<tt>and COMMAND1; COMMAND2</tt>
<tt>COMMAND1; and COMMAND2</tt>
\subsection and-description Description
The \c and builtin is used to execute one command, and if it returns
zero status, also execute a second command.
The \c and builtin is used to execute a command if the current exit
status (as set by the last previous command) is 0.
The and command does not change the current exit status.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
variable.
\subsection and-example Example
The following code runs the \c make command to build a program, and if it suceeds, it runs <tt>make install</tt>, which installs the program.
<pre>
and make; make install
</pre>
\c or and \c and can be nested, as in this example, that attempts to build and install a program, and removed the files created by the build process on failiure
The following code runs the \c make command to build a program, if the
build succeeds, the program is installed. If either step fails,
<tt>make clean</tt> is run, which removes the files created by the
@@ -8,7 +8,7 @@ Sends the specified jobs to the background. 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 group ids are put in the background.
The PID of the desired process is usually found by using process globbing.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
The <tt>bind</tt> builtin causes fish to add the readline style bindings specified by <tt>BINDINGS</tt> to the list of key bindings. For more information on specifying keyboard bindings, use <tt>man readline</tt> to access the readline documentation.
<tt>bind [OPTIONS] SEQUENCE COMMAND</tt>
\subsection bind-description Description
- <tt>-M MODE</tt> or <tt>--set-mode=MODE</tt> sets the current input mode to MODE.
The <tt>bind</tt> builtin causes fish to add a key binding from the specified sequence.
SEQUENCE is the character sequence to bind to. Usually, one would use
fish escape sequences to express them. 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
\c \\e escape. For example, Alt-w can be written as
<tt>\\ew</tt>. Control character can be written in much the same way
using the \c \\c escape, for example Control-x can be written as
<tt>\\cx</tt>. Note that Alt-based key bindings are case sensitive and
Control base key bindings are not. This is not a design choice in
fish, it is simply how terminals work.
If SEQUENCE is the empty string, i.e. an empty set of quotes, this is
interpreted as the default keybinding. It will be used whenever no
other binding matches. For most key bindings, it makes sense to use
the \c self-insert function (i.e. <tt>bind '' self-insert</tt> as the
default keybining. 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 e.g. 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 man 5 terminfo for more information, or use <tt>bind
--key-names</tt> for a list of all available named keys)
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 <a href="#function">function</a> 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 you want to autoload bindings each time you start shell, you should
define them inside fish_user_key_bindings function.
- <tt>-a</tt> or <tt>--all</tt> If --key-names is specified, show all key names, not only the ones that actually are defined for the current terminal. If erase mode is specified, this switch will cause all current bindings to be erased.
- <tt>-e</tt> or <tt>--erase</tt> Erase mode. All non-switch arguments are interpreted as character sequences and any commands associated with those sequences are erased.
- <tt>-h</tt> or <tt>--help</tt> Display help and exit
- <tt>-k</tt> or <tt>--key</tt> Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- <tt>-K</tt> or <tt>--key-names</tt> Display a list of available key names
- <tt>-f</tt> or <tt>--function-names</tt> Display a list of available input functions
\subsection bind-example Example
<tt>bind -M vi</tt> changes to the vi input mode
<tt>bind \\cd 'exit'</tt> causes fish to exit on Control-d
<tt>bind -k ppage history-search-backward</tt> Causes fish to perform a history search when the page up key is pressed
<tt>bind '"\\M-j": jobs'</tt> Binds the jobs command to the Alt-j keyboard shortcut
\section break break - stop the innermost currently evaluated loop
\subsection break-synopsis Synopsis
@@ -8,14 +7,13 @@
The \c break builtin is used to halt a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\subsection break-example Example
The following code searches all .c files for smurfs, and halts at the first occurance.
<p>
<tt>for i in *.c;
<br> if grep smurf $i;
<br> echo Smurfs are present in $i;
For an introduction to how to specify completions, see the section <a
href='index.html#completions-own'>Writing your own completions</a> of
href='index.html#completion-own'>Writing your own completions</a> of
the fish manual.
- <tt>COMMAND</tt> is the name of the command for which to add a completion
@@ -14,13 +14,15 @@ the fish manual.
- <tt>LONG_OPTION</tt> is a multi character option for the command
- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells
- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do
- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string
- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted
- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename
- <tt>-n</tt> or <tt>--condition</tt> specides 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.
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
- <tt>-n</tt> or <tt>--condition</tt> 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.
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command
- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option
- <tt>-u</tt> or <tt>--unauthorative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors
- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt>
Command specific tab-completions in \c fish are based on the notion
@@ -30,13 +32,14 @@ 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 preceeded by a single hyphen and may ge 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 are more than one character long, are preceeded 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 are more than one character long, are preceeded 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 abbrevated so long as the abbrevation is unique ('--h' is equivalent to '--help' if help is the only long option beginning with an 'h').
- 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').
\c complete only allows one of old style long options and GNU style
long options to be used on a specific command, but short options can
always be specified.
The options for specifying command name, command path, or command
switches may all be used multiple times to specify multiple commands
which have the same completion or multiple switches accepted by a
command.
When erasing completions, it is possible to either erase all
completions for a specific command by specifying <tt>complete -e -c
@@ -70,5 +73,5 @@ This can be written as:
"Don't check dependencies"</tt>
where \c __fish_contains_opt is a function that checks the commandline
buffer for the presense of a specified set of options.
buffer for the presence of a specified set of options.
The \c continue builtin is used to skip the current lap of the innermost currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\subsection continue-example Example
The following code removes all tmp files without smurfs.
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 achive 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 sourcecode, 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. \c fish only supports command substitution, the others can be achived 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. \c fish functions have none of the drawbacks of either syntax.
- The many Posix quoting styles are silly, especially \$''.
\section sep The law of minimalism
The shell should only contain features that cannot be implemented in
a reasonable way outside of the shell. A large performance decrease,
as well as some program complexity increase is acceptable in order to
improve separation.
Rationale:
A modular project is easier to maintain since smaller programs are far
easier to understand than larger ones. A modular project is also more
future proof since the modules can be individually
replaced. Modularity also decreases the severity of bugs, since there
is good hope that a bug, even a serious one, in one module, does not
take the whole system down.
Examples:
- Builtin commands should only be created when it cannot be
avoided. \c echo, \c kill, \c printf and \c time are among the commands
that fish does not implement internally since they can be provided as
external commands. Several other commands that are commonly implemented
as builtins and can not be implemented as external commands,
including \c type, \c vared, \c pushd and \c popd are implemented as shellscript
functions in fish.
- Mathematical calculations, regex matching, generating lists of numbers
and many other funtions can easily be done in external programs. They
should not be supported internally by the shell.
The law of minimalism does not imply that a large feature set is
bad. So long as a feature is not part of the shell itself, but a
separate command or at least a shellscript function, bloat is fine.
\section conf 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 failiure 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 history filename, 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 of by default in zsh. Other features that zsh support 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 a
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 to 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 builtin commands, shellscript functions and builtin commands should be made as small as possible. Builtins 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 io 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 \c end builtin.
\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 commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and the she/he then remembers the new information
until the next time she/he uses the same program.
Examples:
- Everything should be tab-completable, and every tab completion should have a description.
- Every syntax error and error in a builtin 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, he will know the whole language, and be able to use tab-completion to discover new featues.
\section eval eval - evaluate the specified commands
\subsection eval-synopsis Synopsis
<tt>eval [COMMANDS...]</tt>
\subsection eval-description Description
The <tt>eval</tt> builtin causes fish to evaluate 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.
The <tt>eval</tt> function causes fish to evaluate 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.
Fish is trying to set the titlebar message of your terminal. While
screen itself supports this feature, your terminal does
not. Unfortuntaly, 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 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.
<hr>
\section faq-greeting How do I change the greeting message?
Change the value of the variable fish_greeting. For example, to remove
the greeting use:
<pre>
set fish_greeting
</pre>
<hr>
\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 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.
- 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 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 (Alt+D and Alt+Backspace are your friends).
See <a href='index.html#editor'>documentation</a> for more details about line editing in fish.
Sends the specified job to the foreground. 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.
The PID of the desired process is usually found by using process globbing.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
\section fish fish - the friendly interactive shell
\subsection fish-synopsis Synopsis
fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]
\subsection fish-description Description
A commandline shell written mainly with interactive use in mind. The
full manual is available <a href='index.html'>in html</a> by using the
<a href='#help'>help</a> command from inside fish.
- <code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline
- <code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- <code>-h</code> or <code>--help</code> display help and exit
- <code>-i</code> or <code>--interactive</code> specify that fish is to run in interactive mode
- <code>-l</code> or <code>--login</code> specify that fish is to run as a login shell
- <code>-n</code> or <code>--no-execute</code> do not execute any commands, only perform syntax checking
- <code>-p</code> or <code>--profile=PROFILE_FILE</code> when fish exits, output timing information on all executed commands to the specified file
- <code>-v</code> or <code>--version</code> display version and exit
The fish exit status is generally the exit status of the last
foreground command. If fish is exiting because of a parse error, the
\section fish_prompt fish_prompt - define the apperance of the command line prompt
\subsection fish_prompt-synopsis Synopsis
<pre>function fish_prompt
...
end</pre>
\subsection fish_prompt-description Description
By defining the \c fish_prompt function, the user can choose a custom
prompt. The \c fish_prompt function is executed when the prompt is to
be shown, and the output is used as a prompt.
Please keep in mind that the function is executed by <a
href='index.html#expand-command-substitution'>command substitution</a>, and so the exit status of commands within fish_prompt will not modify the <a href="index.html#variables-status">$status</a> seen outside of fish_prompt.
\section funced funced - edit a function interactively
\subsection funced-synopsis Synopsis
<code>funced [OPTIONS] NAME</code>
\subsection funced-description Description
Use the funced command to edit the definition of a
function. If there is no function with the name specified, a skeleton function is inserted, if a function exist, the definition will be shown in your editor or on the command line.
By default, funced edits functions using the text editor in your $EDITOR variable, if set; otherwise it uses the built-in editor.
- <code>-e command</code> or <code>--editor command</code> Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor.
- <code>-i</code> or <code>--interactive</code> Open function body in built-in editor.
- \c -b or \c --key-binding specifies that the function is a key biding. Key binding functions work exactly like regular functions except that they can not be tab-completed, and may contain the '-' character.
- <tt>-d DESCRIPTION</tt> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
- <tt>-j PID</tt> or <tt> --on-job-exit PID</tt> tells fish to run this function when the job with group id PID exits
- <tt>-p PID</tt> or <tt> --on-process-exit PID</tt> tells fish to run this function when the fish child process with process id PID exits
- <tt>-s</tt> or <tt>--on-signal SIGSPEC</tt> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a singal number, or the signal name, such as SIGHUP (or just HUP)
- <tt>-v</tt> or <tt>--on-variable VARIABLE_NAME</tt> tells fish to run this function when the variable VARIABLE_NAME changes value
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group id PID exits. Instead of PID, 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.
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process id PID exits
- <code>-s</code> or <code>--on-signal SIGSPEC</code> 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)
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value
This builtin command is used to create a new function. A Function is a
This builtin command is used to create a new function. A function is a
list of commands that will be executed when the name of the function
is entered. The function
is entered. The function
<pre>
function hi
echo hello
end
</pre>
</pre>
will write <tt>hello</tt> whenever the user enters \c hi.
will write <code>hello</code> whenever the user enters \c hi.
If the user enters any additional arguments after the function, they
are inserted into the environment variable <a href="index.html#variables-arrays">array</a> argv.
are inserted into the environment <a href="index.html#variables-arrays">variable array</a> argv.
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 <a href='#emit">emit</a> builtin. Fish generates the following named events:
- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed
- \c fish_command_not_found, which is emitted whenever a command lookup failed
\subsection function-example Example
<pre>function ll
<pre>
function ll
ls -l $argv
end
</pre>
@@ -39,18 +45,18 @@ will run the \c ls command, using the \c -l option, while passing on any additio
<pre>
function mkdir -d "Create a directory and set CWD"
mkdir $argv
if test $status = 0
if test $status = 0
switch $argv[(count $argv)]
case '-*'
case '*'
cd $argv[(count $argv)]
return
end
end
end
</pre>
</pre>
will run the mkdir command, and if it is succesfull, change the
will run the mkdir command, and if it is successful, change the
current working directory to the one just created.
\section functions functions - print or erase functions
\subsection function-synopsis Synopsis
<tt>functions [-e] FUNCTIONS...</tt>
<code>functions [-e] FUNCTIONS...</code>
\subsection functions-description Description
This builtin command is used to print or erase functions.
- <tt>-e</tt> or <tt>--erase</tt> causes the specified functions to be erased.
- <tt>-n</tt> or <tt>--names</tt> List only the names of all defined functions
- <code>-a</code> or <code>--all</code> list all functions, even those whose name start with an underscore.
- <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.
- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> change the description of this function
- <code>-e</code> or <code>--erase</code> causes the specified functions to be erased.
- <code>-h</code> or <code>--help</code> display a help message and exit
- <code>-n</code> or <code>--names</code> list only the names of all defined functions, not their definition
- <code>-q</code> or <code>--query</code> test if the specified functions exist. Does not output anything, but the builtins exit status is the number of functions specified that were not defined.
If \c functions is called with no arguments, the names and definition
of all functions are printed, otherwise, the specified function
definitions will be printed.
The default behavior of \c functions when called with no arguments,
is to print the names and definitions of all defined functions. If any
non-switch parameters are given, only the definition of the specified
functions are printed.
Automatically loaded functions can not be removed using functions
-e. Either remove the definition file or change the
$fish_function_path variable to remove autoloaded functions.
Function copies, created with -c, will not have any event/signal/on-exit
notifications that the original may have had.
The exit status of the functions builtin is the number functions
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
The precise terms and conditions for copying, distribution and
modification follow.
</P>
<H2><A NAME="SEC3" HREF="gpl.html#TOC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2>
<P>
<STRONG>0.</STRONG>
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".
<P>
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.
<P>
<STRONG>1.</STRONG>
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.
<P>
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.
<P>
<STRONG>2.</STRONG>
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:
<P>
<DL>
<DT>
<DD>
<STRONG>a)</STRONG>
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>b)</STRONG>
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.
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>c)</STRONG>
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.)
</DD>
</DT>
</DL>
<P>
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.
<P>
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.
<P>
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.
<P>
<STRONG>3.</STRONG>
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:
<!-- we use this doubled UL to get the sub-sections indented, -->
<!-- while making the bullets as unobvious as possible. -->
<DL>
<DT>
<DD>
<STRONG>a)</STRONG>
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,
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>b)</STRONG>
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,
</DD>
</DT>
</DL>
<P>
<DL>
<DT>
<DD>
<STRONG>c)</STRONG>
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.)
</DD>
</DT>
</DL>
<P>
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.
<P>
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.
<P>
<STRONG>4.</STRONG>
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.
<P>
<STRONG>5.</STRONG>
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.
<P>
<STRONG>6.</STRONG>
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.
<P>
<STRONG>7.</STRONG>
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.
<P>
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.
<P>
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.
<P>
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
<P>
<STRONG>8.</STRONG>
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.
<P>
<STRONG>9.</STRONG>
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.
<P>
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.
<P>
<STRONG>10.</STRONG>
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.
<P><STRONG>NO WARRANTY</STRONG></P>
<P>
<STRONG>11.</STRONG>
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.
<P>
<STRONG>12.</STRONG>
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.
<P>
<HR>
<h2>License for wcslcat and wcslcpy</h2>
\c fish also contains small amounts of code under the BSD
license, namely versions of the two functions strlcat and strlcpy,
modified for use with wide character strings. This code is copyrighted
by Todd C. Miller.
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.
<HR>
<h2>License for XSel</h2>
The XSel command, written and copyrighted by Conrad Parker, is
distributed together with \c fish.
It is Copyright (C) 2001 Conrad Parker <conrad@vergenet.net>
Permission to use, copy, modify, distribute, and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation. No representations are made about the
suitability of this software for any purpose. It is provided "as is"
without express or implied warranty.
<HR>
<h2>License for xdgmime and glibc</h2>
The xdgmime library, written and copyrighted by Red Hat, Inc, is used
by the mimedb command, which is a part of fish. It is released under
the LGPL, version 2 or later, or under the Academic Free License,
version 2. Version 2 of the LGPL license agreement is included below.
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.
<H2><A NAME="SEC1" HREF="#TOC1">GNU LESSER GENERAL PUBLIC LICENSE</A></H2>
<P>
Version 2.1, February 1999
<P>
<PRE>
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.]
</PRE>
<H2><A NAME="SEC2" HREF="#TOC2">Preamble</A></H2>
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
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.
<P>
<H2><A NAME="SEC3" HREF="#TOC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2>
<P>
<STRONG>0.</STRONG>
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".
<P>
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.
<P>
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".)
<P>
"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.
<P>
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.
<P>
<STRONG>1.</STRONG>
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.
<P>
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.
<P>
<STRONG>2.</STRONG>
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:
<P>
<UL>
<LI><STRONG>a)</STRONG>
The modified work must itself be a software library.
<LI><STRONG>b)</STRONG>
You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
<LI><STRONG>c)</STRONG>
You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
<LI><STRONG>d)</STRONG>
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.
<P>
(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.)
<P>
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.
<P>
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.
<P>
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.
</UL>
<P>
<STRONG>3.</STRONG>
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.
<P>
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.
<P>
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
<P>
<STRONG>4.</STRONG>
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.
<P>
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.
<P>
<STRONG>5.</STRONG>
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.
<P>
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.
<P>
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.
<P>
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.)
<P>
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.
<P>
<STRONG>6.</STRONG>
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.
<P>
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:
<P>
<UL>
<LI><STRONG>a)</STRONG> 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.)
<LI><STRONG>b)</STRONG> 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.
<LI><STRONG>c)</STRONG> 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.
<LI><STRONG>d)</STRONG> 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.
<LI><STRONG>e)</STRONG> Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
</UL>
<P>
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.
<P>
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.
<P>
<STRONG>7.</STRONG> 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:
<P>
<UL>
<LI><STRONG>a)</STRONG> 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.
<LI><STRONG>b)</STRONG> 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.
</UL>
<P>
<STRONG>8.</STRONG> 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.
<P>
<STRONG>9.</STRONG>
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.
<P>
<STRONG>10.</STRONG>
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.
<P>
<STRONG>11.</STRONG>
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.
<P>
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.
<P>
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.
<P>
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
<P>
<STRONG>12.</STRONG>
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.
<P>
<STRONG>13.</STRONG>
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.
<P>
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.
<P>
<STRONG>14.</STRONG>
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.
<P>
<STRONG>NO WARRANTY</STRONG>
<P>
<STRONG>15.</STRONG>
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.
<P>
<STRONG>16.</STRONG>
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.
<P>
*/
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
