22416, tweaked: math functions via shell functions

unposted: add styles to pick-web-browser

2 files changed, 194 insertions, 83 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 99b3238bd..bd81a7746 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -501,8 +501,52 @@ Equivalent to tt(typeset -E), except that options irrelevant to floating
 point numbers are not permitted.
 )
 findex(functions)
-item(tt(functions) [ {tt(PLUS())|tt(-)}tt(UXkmtuz) ] [ var(name) ... ])(
-Equivalent to tt(typeset -f).
+xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UXkmtuz) ] [ var(name) ... ])
+xitem(tt(functions -M) var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ])
+xitem(tt(functions -M) [ tt(-m) var(pattern) ... ])
+item(tt(functions +M) [ tt(-m) ] var(mathfn))(
+Equivalent to tt(typeset -f), with the exception of the tt(-M) option.
+Use of the tt(-M) option may not be combined with any of the options
+handled by tt(typeset -f).
+
+tt(functions -M) var(mathfn) defines var(mathfn) as the name of
+a mathematical function recognised in all forms of arithmetical expressions;
+see
+ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
+ifnzman(noderef(Arithmetic Evaluation))\
+.  By default var(mathfn) may take
+any number of comma-separated arguments.  If var(min) is given,
+it must have exactly var(min) args; if var(min) and var(max) are
+both given, it must have at least var(min) and and at most var(max)
+args.  var(max) may be -1 to indicate that there is no upper limit.
+
+By default the function is implemented by a shell function of the same
+name; if var(shellfn) is specified it gives the name of the corresponding
+shell function while var(mathfn) remains the name used in arithmetical
+expressions.  The name of the function in tt($0) is var(mathfn) (not
+var(shellfn) as would usually be the case), provided the option
+tt(FUNCTION_ARGZERO) is in effect.  The positional parameters in the shell
+function correspond to the arguments of the mathematical function call.
+The result of the last arithmetical expression evaluated
+inside the shell function (even if it is a form that normally only returns
+a status) gives the result of the mathematical function.
+
+tt(functions -M) with no arguments lists all such user-defined functions in
+the same form as a definition.  With the additional option tt(-m) and
+a list of arguments, all functions whose var(mathfn) matches one of
+the pattern arguments are listed.
+
+tt(function +M) removes the list of mathematical functions; with the
+additional option tt(-m) the arguments are treated as patterns and
+all functions whose tt(mathfn) matches the pattern are removed.  Note
+that the shell function implementing the behaviour is not removed
+(regardless of whether its name coincides with tt(mathfn)).
+
+For example, the following prints the cube of 3:
+
+example(zmath_cube+LPAR()RPAR() { (( $1 * $1 * $1 )) }
+functions -M cube 1 1 zmath_cube
+print $(( cube+LPAR()3+RPAR() )))
 )
 module(getcap)(zsh/cap)
 findex(getln)
@@ -652,8 +696,10 @@ tt(kill -IO) and tt(kill -POLL) have the same effect.
 findex(let)
 item(tt(let) var(arg) ...)(
 Evaluate each var(arg) as an arithmetic expression.
-See noderef(Arithmetic Evaluation) for a description
-of arithmetic expressions.  The exit status is 0 if the
+See
+ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
+ifnzman(noderef(Arithmetic Evaluation))
+for a description of arithmetic expressions.  The exit status is 0 if the
 value of the last expression is nonzero, and 1 otherwise.
 )
 findex(limit)
@@ -856,7 +902,9 @@ that allows it to be reused as shell input. With the numeric format
 specifiers, if the corresponding argument starts with a quote character,
 the numeric value of the following character is used as the number to
 print otherwise the argument is evaluated as an arithmetic expression. See
-noderef(Arithmetic Evaluation) for a description of arithmetic
+ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
+ifnzman(noderef(Arithmetic Evaluation))
+for a description of arithmetic
 expressions. With `tt(%n)', the corresponding argument is taken as an
 identifier which is created as an integer parameter.
 
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index a0fc1ff56..e8555d89d 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -15,6 +15,7 @@ menu(Prompt Themes)
 menu(ZLE Functions)
 menu(Exception Handling)
 menu(MIME Functions)
+menu(Mathematical Functions)
 menu(Other Functions)
 endmenu()
 
@@ -1339,7 +1340,7 @@ if a shell error subsequently occurs.  Adding tt(unset EXCEPTION) at the
 start of the outermost layer of any code that uses exception handling will
 eliminate this problem.
 
-texinode(MIME Functions)(Other Functions)(Exception Handling)(User Contributions)
+texinode(MIME Functions)(Mathematical Functions)(Exception Handling)(User Contributions)
 sect(MIME Functions)
 
 Three functions are available to provide handling of files recognised by
@@ -1347,6 +1348,8 @@ extension, for example to dispatch a file tt(text.ps) when executed as a
 command to an appropriate viewer.
 
 startitem()
+findex(zsh-mime-setup)
+findex(zsh-mime-handler)
 xitem(tt(zsh-mime-setup [-flv]))
 item(tt(zsh-mime-handler))(
 These two functions use the files tt(~/.mime.types) and tt(/etc/mime.types),
@@ -1520,6 +1523,7 @@ example(text/html; /usr/bin/lynx '%s'; needsterminal)
 )
 enditem()
 )
+findex(pick-web-browser)
 item(tt(pick-web-browser))(
 This function is separate from the two MIME functions described above
 and can be assigned directly to a suffix:
@@ -1528,19 +1532,19 @@ example(autoload -U pick-web-browser
 alias -s html=pick-web-browser)
 
 It is provided as an intelligent front end to dispatch a web browser.
-It will check if an X Windows display is available, and if so
-if there is already a browser running which can accept a remote
+It will check if an X Windows display is available, and if so if there
+is already a browser running on the display which can accept a remote
 connection.  In that case, the file will be displayed in that browser;
 you should check explicitly if it has appeared in the running browser's
-window.  Otherwise, it will start a new browser according to a builtin
+window.  Otherwise, it will start a new browser according to a built-in
 set of preferences.
 
 Alternatively, tt(pick-web-browser) can be run as a zsh script.
 
 Two styles are available to customize the choice of browsers:
-tt(x-browsers) when running under the X Windows System, and
+tt(x-browsers) when running under the X Window System, and
 tt(tty-browsers) otherwise.  These are arrays in decreasing order
-of preference consiting of the command name under which to start the
+of preference consisting of the command name under which to start the
 browser.  They are looked up in the context tt(:mime:) (which may
 be extended in future, so appending `tt(*)' is recommended).  For
 example,
@@ -1550,10 +1554,140 @@ example(zstyle ':mime:*' x-browsers opera konqueror netscape)
 specifies that tt(pick-web-browser) should first look for a runing
 instance of Opera, Konqueror or Netscape, in that order, and if it
 fails to find any should attempt to start Opera.
+
+In addition, the style tt(command), if set, is used to pick the command
+used to open a page for a browser.  The context is
+tt(:mime:browser:new:$browser:) to start a new browser or
+tt(:mime:browser:running:$browser:) to open a URL in a browser already
+runing on the current X display.  The escape sequence tt(%b) in the
+style's value will be replaced by the browser, while tt(%u) will be
+replaced by the URL.  If the style is not set, the default for all new
+instances is equivalent to tt(%b %u) and the defaults for using running
+browsers are equivalent to the values tt(kfmclient openURL %u) for
+Konqueror, tt(firefox -new-tab %u) for Firefox and tt(%b -remote
+"openUrl+LPAR()%u+RPAR()") for all others.
 )
 enditem()
 
-texinode(Other Functions)()(MIME Functions)(User Contributions)
+texinode(Mathematical Functions)(Other Functions)(MIME Functions)(User Contributions)
+sect(Mathematical Functions)
+
+startitem()
+findex(zcalc)
+item(tt(zcalc) [ var(expression) ... ])(
+A reasonably powerful calculator based on zsh's arithmetic evaluation
+facility.  The syntax is similar to that of formulae in most programming
+languages; see
+ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
+ifnzman(noderef(Arithmetic Evaluation)) for details.  The mathematical
+library tt(zsh/mathfunc) will be loaded if it is available; see
+ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/mathfunc Module)).  The mathematical functions
+correspond to the raw system libraries, so trigonometric functions are
+evaluated using radians, and so on.
+
+Each line typed is evaluated as an expression.  The prompt shows a number,
+which corresponds to a positional parameter where the result of that
+calculation is stored.  For example, the result of the calculation on the
+line preceded by `tt(4> )' is available as tt($4).  The last value
+calculated is available as tt(ans).  Full command line editing, including
+the history of previous calculations, is available; the history is saved in
+the file tt(~/.zcalc_history).  To exit, enter a blank line or type `tt(q)'
+on its own.
+
+If arguments are given to tt(zcalc) on start up, they are used to prime the
+first few positional parameters.  A visual indication of this is given when
+the calculator starts.
+
+The constants tt(PI) (3.14159...) and tt(E) (2.71828...) are provided.
+Parameter assignment is possible, but note that all parameters will be put
+into the global namespace.
+
+The output base can be initialised by passing the option `tt(-#)var(base)',
+for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending
+on the globbing options set).
+
+The prompt is configurable via the parameter tt(ZCALCPROMPT), which
+undergoes standard prompt expansion.  The index of the current entry is
+stored locally in the first element of the array tt(psvar), which can be
+referred to in tt(ZCALCPROMPT) as `tt(%1v)'.  The default prompt is
+`tt(%1v> )'.
+
+The output precision may be specified within zcalc by special commands
+familiar from many calculators:
+startitem()
+item(tt(norm))(
+The default output format.  It corresponds to the printf tt(%g)
+specification.  Typically this shows six decimal digits.
+)
+item(tt(sci) var(digits))(
+Scientific notation, corresponding to the printf tt(%g) output format with
+the precision given by var(digits).  This produces either fixed point or
+exponential notation depending on the value output.
+)
+item(tt(fix) var(digits))(
+Fixed point notation, corresponding to the printf tt(%f) output format with
+the precision given by var(digits).
+)
+item(tt(eng) var(digits))(
+Exponential notation, corresponding to the printf tt(%E) output format with
+the precision given by var(digits).
+)
+enditem()
+
+Other special commands:
+startitem()
+item(tt(local) var(arg) ...)(
+Declare variables local to the function.  Note that certain variables
+are used by the function for its own purposes.  Other variables
+may be used, too, but they will be taken from or put into the global
+scope.
+)
+item(tt(function) var(name) [ var(body) ])(
+Define a mathematical function or (with no var(body)) delete it.
+The function is defined using tt(zmathfuncdef), see below.
+
+Note that tt(zcalc) takes care of all quoting.  Hence for example:
+
+example(function cube $1 * $1 * $1)
+
+defines a function to cube the sole argument.
+)
+item(tt([#)var(base)tt(]))(
+When this syntax appears on a line by itself, the default output radix
+is set to var(base).  Use, for example, `tt([#16])' to display hexadecimal
+output preceded by an indication of the base, or `tt([##16])' just to
+display the raw number in the given base.  Bases themselves are always
+specified in decimal. `tt([#])' restores the normal output format.  Note
+that setting an output base suppresses floating point output; use `tt([#])'
+to return to normal operation.
+
+)
+enditem()
+
+See the comments in the function for a few extra tips.
+)
+findex(zmathfuncdef)
+item(tt(zmathfuncdef) var(mathfunc) [ var(body) ])(
+A convenient front end to tt(functions -M).
+
+With two arguments, define a mathematical function named var(mathfunc)
+which can be used in any form of arithmetic evaluation.  var(body)
+is a mathematical expression to implement the function.  It may
+contain references to position parameters tt($1), tt($2), ...
+to refer to mandatory parameters and tt(${1:-)var(defvalue)tt(}) ...
+to refer to optional parameters.  Note that the forms must be
+strictly adhered to for the function to calculate the correct number
+of arguments.  The implementation is held in a shell function named
+tt(zsh_math_func_)var(mathfunc); usually the user will not need
+to refer to the shell function directly.
+
+With one argument, remove the mathematical function var(mathfunc)
+as well as the shell function implementation.
+)
+enditem()
+
+texinode(Other Functions)()(Mathematical Functions)(User Contributions)
 sect(Other Functions)
 
 There are a large number of helpful functions in the tt(Functions/Misc)
@@ -1720,77 +1854,6 @@ This is a good choice in that example because no plain file can be named
 For details of the other tt(zargs) options, see zmanref(xargs) or run
 tt(zargs) with the tt(-)tt(-help) option.
 )
-findex(zcalc)
-item(tt(zcalc) [ var(expression) ... ])(
-A reasonably powerful calculator based on zsh's arithmetic evaluation
-facility.  The syntax is similar to that of formulae in most programming
-languages; see
-ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
-ifnzman(noderef(Arithmetic Evaluation)) for details.  The mathematical
-library tt(zsh/mathfunc) will be loaded if it is available; see
-ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\
-ifnzman(noderef(The zsh/mathfunc Module)).  The mathematical functions
-correspond to the raw system libraries, so trigonometric functions are
-evaluated using radians, and so on.
-
-Each line typed is evaluated as an expression.  The prompt shows a number,
-which corresponds to a positional parameter where the result of that
-calculation is stored.  For example, the result of the calculation on the
-line preceded by `tt(4> )' is available as tt($4).  Full command line
-editing, including the history of previous calculations, is available; the
-history is saved in the file tt(~/.zcalc_history).  To exit, enter a blank
-line or type `tt(q)' on its own.
-
-If arguments are given to tt(zcalc) on start up, they are used to prime the
-first few positional parameters.  A visual indication of this is given when
-the calculator starts.
-
-The constants tt(PI) (3.14159...) and tt(E) (2.71828...) are provided.
-Parameter assignment is possible, but note that all parameters will be put
-into the global namespace.
-
-An extra facility is provided for changing the default output base.  Use,
-for example, `tt([#16])' to display hexadecimal output preceded by an
-indication of the base, or `tt([##16])' just to display the raw number in
-the given base.  Bases themselves are always specified in decimal.
-`tt([#])' restores the normal output format.  Note that setting an output
-base suppresses floating point output; use `tt([#])' to return to normal
-operation.
-
-The output base can be initialised by passing the option `tt(-#)var(base)',
-for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending
-on the globbing options set).
-
-The prompt is configurable via the parameter tt(ZCALCPROMPT), which
-undergoes standard prompt expansion.  The index of the current entry is
-stored locally in the first element of the array tt(psvar), which can be
-referred to in tt(ZCALCPROMPT) as `tt(%1v)'.  The default prompt is
-`tt(%1v> )'.
-
-The output precision may be specified within zcalc by special commands
-familiar from many calculators:
-startitem()
-item(tt(norm))(
-The default output format.  It corresponds to the printf tt(%g)
-specification.  Typically this shows six decimal digits.
-)
-item(tt(sci) var(digits))(
-Scientific notation, corresponding to the printf tt(%g) output format with
-the precision given by var(digits).  This produces either fixed point or
-exponential notation depending on the value output.
-)
-item(tt(fix) var(digits))(
-Fixed point notation, corresponding to the printf tt(%f) output format with
-the precision given by var(digits).
-)
-item(tt(eng) var(digits))(
-Exponential notation, corresponding to the printf tt(%E) output format with
-the precision given by var(digits).
-)
-enditem()
-
-See the comments in the function for a few extra tips.
-)
 findex(zed)
 xitem(tt(zed) [ tt(-f) ] var(name))
 item(tt(zed -b))(