how_to_add

Calc Software Package for Number Calc

	result.v_num = qalloc();		/* see ../qmath.c */
	result.v_num->num = variable;
	return result;

    To convert a small NUMBER* into a long:

	NUMBER *num;
	long variable;

	variable = qtoi(num);

    To obtain a ZVALUE from a NUMBER*, extract the numerator:

	NUMBER *num;
	ZVALUE z_variable;

	if (qisint(num)) {
		z_variable = num->num;
	}

    To be sure that the value will fit, use the ZVALUE test macros:

	ZVALUE z_num;
	long variable;
	unsigned long u_variable;
	FULL f_variable;
	short very_tiny_variable;

	if (zgtmaxlong(z_num)) {			/* see ../zmath.h */
		variable = ztolong(z_num);
	}
	if (zgtmaxulong(z_num)) {
		u_variable = ztoulong(z_num);
	}
	if (zgtmaxufull(z_num)) {
		f_variable = ztofull(z_num);
	}
	if (zistiny(z_num)) {
		very_tiny_variable = z1tol(z_num);
	}


Step 6: Register the function in the custom interface table

    To allow the custom() builtin to transfer control to your function,
    you need to add an entry into the CONST struct custom cust table
    found in custom/custtbl.c:

	/*
	 * custom interface table
	 *
	 * The order of the elements in struct custom are:
	 *
	 *	{ "xyz", "brief description of the xyz custom function",
	 *	   minimum_args, maximum_args, c_xyz },
	 *
	 * where:
	 *
	 *	minimum_args	an int >= 0
	 *	maximum_args	an int >= minimum_args and <= MAX_CUSTOM_ARGS
	 *
	 * Use MAX_CUSTOM_ARGS for maximum_args is the maximum number of args
	 * is potentially 'unlimited'.
	 *
	 * If the brief description cannot fit on the same line as the name
	 * without wrapping on a 80 col window, the description is probably
	 * too long and will not look nice in the show custom output.
	 */
	CONST struct custom cust[] = {

	#if defined(CUSTOM)


		/*
		 * add your own custom functions here
		 *
		 * We suggest that you sort the entries below by name
		 * so that show custom will produce a nice sorted list.
		 */

		{ "argv", "information about its args, returns arg count",
		 0, MAX_CUSTOM_ARGS, c_argv },

		{ "devnull", "does nothing",
		 0, MAX_CUSTOM_ARGS, c_devnull },

		{ "help", "help for custom functions",
		 1, 1, c_help },

		{ "sysinfo", "return a calc #define value",
		 0, 1, c_sysinfo },


	#endif /* CUSTOM */

		/*
		 * This must be at the end of this table!!!
		 */
		{NULL, NULL,
		 0, 0, NULL}
	};

    The definition of struct custom may be found in custom.h.

    It is important that your entry be placed inside the:

	#if defined(CUSTOM) ... #endif /* CUSTOM */

    lines so that when the custom interface is disabled by the upper
    level Makefile, one does not have unsatisfied symbols.

    The brief description should be brief so that 'show custom' looks well
    formatted.	If the brief description cannot fit on the same line as
    the name without wrapping on a 80 col window, the description is
    probably too long and will not look nice in the show custom output.

    The minargs places a lower bound on the number of args that
    must be supplied to the interface.	This does NOT count
    the name argument given to custom().  So if minargs is 2:

	custom("curds")		/* call blocked at high level interface */
	custom("curds", a)	/* call blocked at high level interface */
	custom("curds", a, b)	/* call passed down to "curds" interface */

    The maxargs sets a limit on the number of args that may be passed.
    If minargs == maxargs, then the call requires a fixed number of
    argument.  There is a upper limit on the number of args.  If
    one wants an effectively unlimited upper bound, use MAX_CUSTOM_ARGS.

    Note that one must have:

		0 <= minargs <= maxargs <= MAX_CUSTOM_ARGS

    To allow the curds function to take at least 2 args and up
    to 5 args, one would add the following entry to cust[]:

		{ "curds", "brief description about curds interface",
		 2, 5, u_curds },

    It is recommended that the cust[] remain in alphabetical order,
    so one would place it before the "devnull" and after "argv".

    Last, you must forward declare the u_curds near the top of the file:

	#if defined(CUSTOM)


	/*
	 * add your forward custom function declarations here
	 *
	 * Declare custom functions as follows:
	 *
	 *	extern VALUE c_xyz(char*, int, VALUE**);
	 *
	 * We suggest that you sort the entries below by name.
	 */
	extern VALUE c_argv(char*, int, VALUE**);
	extern VALUE c_devnull(char*, int, VALUE**);
	extern VALUE c_help(char*, int, VALUE**);
	extern VALUE c_sysinfo(char*, int, VALUE**);

    For u_curds we would add the line:

	extern VALUE u_curds(char*, int, VALUE**);


Step 7: Add the required information to the custom/Makefile

    The calc test script, curds.cal, should be added to the
    CUSTOM_CALC_FILES Makefile variable found in custom/Makefile:

	CUSTOM_CALC_FILES= argv.cal halflen.cal curds.cal

    The help file, curds, should be added to the CUSTOM_HELP
    Makefile variable:

	CUSTOM_HELP= argv devnull help sysinfo curds

    If you needed to create any .h files to support u_curds.c, these
    files should be added to the CUSTOM_H_SRC Makefile variable:

	CUSTOM_H_SRC= u_curds.h otherfile.h

    Your u_curds.c file MUST be added to the CUSTOM_SRC Makefile variable:

	CUSTOM_SRC= c_argv.c c_devnull.c c_help.c c_sysinfo.c u_curds.c

    and so must the associated .o file:

	CUSTOM_OBJ= c_argv.o c_devnull.o c_help.o c_sysinfo.o u_curds.o


Step 8: Compile and link in your code

    If your calc was not previously setup to compile custom code,
    you should set it up now.  The upper level Makefile (and
    the custom Makefile) should have the following Makefile
    variable defined:

	ALLOW_CUSTOM= -DCUSTOM

    It is recommended that you build your code from the top level
    Makefile.  It saves having to sync the other Makefile values.
    To try and build the new libcustcalc.a that contains u_curds.c:

	(cd ..; make custom/libcustcalc.a)

    Fix any compile and syntax errors as needed.  :-)

    Once libcustcalc.a successfully builds, compile calc:

	cd ..
	make calc

    And check to be sure that the regression test suite still
    works without errors:

	make check


Step 9: Add the Make dependency tools

    You should probably add the dependency lines to the bottom of
    the Makefile.  Given the required include files, you will at least
    have the following entries placed at the bottom of the Makefile:

	u_curds.o: ../alloc.h
	u_curds.o: ../block.h
	u_curds.o: ../byteswap.h
	u_curds.o: ../calcerr.h
	u_curds.o: ../cmath.h
	u_curds.o: ../config.h
	u_curds.o: ../endian_calc.h
	u_curds.o: ../hash.h
	u_curds.o: ../have_const.h
	u_curds.o: ../have_malloc.h
	u_curds.o: ../have_newstr.h
	u_curds.o: ../have_stdlib.h
	u_curds.o: ../have_string.h
	u_curds.o: ../longbits.h
	u_curds.o: ../nametype.h
	u_curds.o: ../qmath.h
	u_curds.o: ../shs.h
	u_curds.o: ../value.h
	u_curds.o: ../zmath.h
	u_curds.o: u_curds.c
	u_curds.o: ../custom.h

    If you have the makedepend tool from the X11 development environment
    (by Todd Brunhoff, Tektronix, Inc. and MIT Project Athena), you can
    use the following to update your dependencies:

	# cd to the top level calc directory if you are not there already

	rm -f Makefile.bak custom/Makefile.bak
	make depend

	diff -c Makefile.bak Makefile			# look at the changes
	diff -c custom/Makefile.bak custom/Makefile	# look at the changes

	rm -f Makefile.bak custom/Makefile.bak		# cleanup

Step 10: Test

    Now that you have built calc with your new custom function, test it:

	./calc -C		# run the new calc with the -C arg

    And then try out our test suite:

	C-style arbitrary precision calculator (version 2.10.3t5.1)
	[Type "exit" to exit, or "help" for help.]

	> read custom/curds.cal
	curds(a, b, [c, d, e]) defined

	> custom("curds", 2, 3, 4)


Step 11: Install

    Once you are satisfied that everything works, install the new code:

	# cd to the top level calc directory if you are not there already

	make install

    Although calc does not run setuid, you may need to be root to install
    the directories into which calc installs may be write protected.


Step 12: Contribute

    Your custom function may be of interest to some people and/or
    serve as an example of what one can do with custom functions.

    Read the file:

	help/contrib		(or run:  calc help contrib)

    and consider submitting your custom function for possible
    inclusion in later versions of calc.

## Copyright (C) 1999-2004  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
##
## @(#) $Revision: 29.5 $
## @(#) $Id: HOW_TO_ADD,v 29.5 2005/10/18 11:18:34 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/custom/RCS/HOW_TO_ADD,v $
##
## Under source code control:	1997/03/10 03:03:21
## File existed as early as:	1997
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/