Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
function(1)			     fish			   function(1)

NAME
       function	-- create a function

   Synopsis
       function	NAME [OPTIONS];	BODY; end

   Description
       function	creates	a new function NAME with the body BODY.

       A function is a list of commands	that will be executed when the name of
       the function is given as	a command.

       The following options are available:

       o -a NAMES or --argument-names NAMES assigns the	value of successive
	 command-line arguments	to the names given in NAMES.

       o -d DESCRIPTION	or --description=DESCRIPTION is	a description of what
	 the function does, suitable as	a completion description.

       o -w WRAPPED_COMMAND or --wraps=WRAPPED_COMMAND causes the function to
	 inherit completions from the given wrapped command. See the
	 documentation for complete for	more information.

       o -e or --on-event EVENT_NAME tells fish	to run this function when the
	 specified named event is emitted. Fish	internally generates named
	 events	e.g. when showing the prompt.

       o -v or --on-variable VARIABLE_NAME tells fish to run this function
	 when the variable VARIABLE_NAME changes value.

       o -j PGID or --on-job-exit PGID tells fish to run this function when
	 the job with group ID PGID exits. Instead of PGID, the	string
	 'caller' can be specified. This is only legal when in a command
	 substitution, and will	result in the handler being triggered by the
	 exit of the job which created this command substitution.

       o -p PID	or --on-process-exit PID tells fish to run this	function when
	 the fish child	process	with process ID	PID exits.

       o -s or --on-signal SIGSPEC tells fish to run this function when	the
	 signal	SIGSPEC	is delivered. SIGSPEC can be a signal number, or the
	 signal	name, such as SIGHUP (or just HUP).

       o -S or --no-scope-shadowing allows the function	to access the
	 variables of calling functions. Normally, any variables inside	the
	 function that have the	same name as variables from the	calling
	 function are 'shadowed', and their contents is	independent of the
	 calling function.

       o -V or --inherit-variable NAME snapshots the value of the variable
	 NAME and defines a local variable with	that same name and value when
	 the function is defined. This is similar to a closure in other
	 languages like	Python but a bit different. Note the word 'snapshot'
	 in the	first sentence.	If you change the value	of the variable	after
	 defining the function,	even if	you do so in the same scope (typically
	 another function) the new value will not be used by the function you
	 just created using this option. See the function notify example below
	 for how this might be used.

       If the user enters any additional arguments after the function, they
       are inserted into the environment variable array	$argv. If the
       --argument-names	option is provided, the	arguments are also assigned to
       names specified in that option.

       By using	one of the event handler switches, a function can be made to
       run automatically at specific events. The user may generate new events
       using the emit builtin. Fish generates the following named events:

       o fish_prompt, which is emitted whenever	a new fish prompt is about to
	 be displayed.

       o fish_command_not_found, which is emitted whenever a command lookup
	 failed.

       o fish_preexec, which is	emitted	right before executing an interactive
	 command. The commandline is passed as the first parameter.

       Note: This event	will be	emitted	even if	the command is invalid.	The
       commandline parameter includes the entire commandline verbatim, and may
       potentially include newlines.

       o fish_postexec,	which is emitted right after executing an interactive
	 command. The commandline is passed as the first parameter.

       Note: This event	will be	emitted	even if	the command is invalid.	The
       commandline parameter includes the entire commandline verbatim, and may
       potentially include newlines.

   Example
       function	ll
	   ls -l $argv
       end

       will run	the ls command,	using the -l option, while passing on any
       additional files	and switches to	ls.

       function	mkdir -d 'Create a directory and set CWD'
	   command mkdir $argv
	   if test $status = 0
	       switch $argv[(count $argv)]
		   case	'-*'

		   case	'*'
		       cd $argv[(count $argv)]
		       return
	       end
	   end
       end

       This will run the mkdir command,	and if it is successful, change	the
       current working directory to the	one just created.

       function	notify
	   set -l job (jobs -l -g)
	   or begin; echo 'There are no	jobs' >&2; return 1; end

	   function _notify_job_$job --on-job-exit $job	--inherit-variable job
	       echo -n \a  # beep
	       functions -e _notify_job_$job
	   end
       end

       This will beep when the most recent job completes.

Version	2.5.0			Fri Feb	3 2017			   function(1)

NAME

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=function&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help