Release calc version 2.10.3t5.45

help/custom

@@ -0,0 +1,95 @@
+NAME
+    custom - custom builtin interface
+
+SYNOPSIS
+    custom([custname [, arg ...]])
+
+TYPES
+    custname	string
+    arg		any
+
+    return	any
+
+DESCRIPTION
+    This function will invoke the custom function interface.  Custom
+    functions are accessed by the custname argument.  The remainder
+    of the args, if any, are passed to the custom function.  The
+    custom function may return any value, including null.  Calling
+    custom with no args is equivalent to the command 'show custom'.
+
+    In order to use the custom interface, two things must happen:
+
+	1) Calc must be built to allow custom functions.  By default,
+	   the master Makefile is shipped with ALLOW_CUSTOM= -DCUSTOM
+	   which causes custom functions to be compiled in.
+
+	2) Calc must be invoked with an argument of -C as in:
+
+		calc -C
+
+    In other words, explicit action must be taken in order to
+    enable the use of custom functions.  By default (no -C arg)
+    custom functions are compiled in but disabled so that only
+    portable calc scripts may be used.
+
+    The main focus for calc is to provide a portable platform for
+    multi-precision calculations in a C-like environment.  You should
+    consider implementing algorithms in the calc language as a first
+    choice.  Sometimes an algorithm requires use of special hardware, a
+    non-portable OS or pre-compiled C library.  In these cases a custom
+    interface may be needed.
+
+    The custom function interface is intended to make is easy for
+    programmers to add functionality that would be otherwise
+    un-suitable for general distribution.  Functions that are
+    non-portable (machine, hardware or OS dependent) or highly
+    specialized are possible candidates for custom functions.
+
+    To add a new custom function requires access to calc source.
+    For information on how to add a new custom function, try:
+
+	    help new_custom
+
+    To serve as examples, calc is shipped with a few custom functions.
+    If calc if invoked with -C, then either of the following will
+    display information about the custom functions that are available:
+
+	    show custom
+    or:
+
+	    custom()
+
+    A few library script that uses these function are also provided
+    to serve as usage examples.
+
+    We welcome submissions for new custom functions.  For information
+    on how to submit new custom functions for general distribution, see:
+
+	    help contrib
+
+EXAMPLE
+    If calc compiled with ALLOW_CUSTOM= (custom disabled):
+
+    > print custom("sysinfo", "baseb")
+	    Calc was built with custom functions disabled
+    Error 10195
+
+    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked without -C:
+
+    > print custom("sysinfo", "baseb")
+	    Calc must be run with a -C argument to use custom function
+    Error 10194
+
+    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked with -C:
+
+    > print custom("sysinfo", "baseb")
+    32
+
+LIMITS
+    By default, custom is limited to 100 args.
+
+LIBRARY
+    none
+
+SEE ALSO
+    custom_cal, new_custom, contrib