Creating New System Functions

Tuesday 3 December 2024 18:10 UTC NARS2000 Creating New Quad System Functions

Who Should Be Reading This Page

If you are an APL'er, an APL programmer or APL developer - this page may not be right for you. This page is for Developers who want to implement a new Quad or ⎕ command using the C/C++ language. Given that NARS source code is over a quarter million lines of highly evolved source code, it is helpful to have several starting points to work from, whether you are a gifted C++/C programmer, PHP programmer, Bison programmer or a relative newcomer to NARS source code. The basic premise is that you have an idea for a new Quad system function command for APL/NARS and wish to implement it, add it to NARS functionality. This page is a starting conceptual and reference point.

Helpful Starting Point Perspectives

Scan Build notes found in the ReleaseNotes subfolder, e.g. C:\NARS2000\trunk\ReleaseNotes, using a text or string scanner program such as Windows File Explorer. Many examples of adding system functions over time should appear in those previous Build notes. Search for the specific text string, "system function" and there should be a number of references found/listed. These references give an idea of which files frequently need to be modified, including much about what you will need to do. For example, file <sysvars.c> contains code locations where all system variables and functions hook into the system - a primary symbol tables reference, an interpreter-table-of-contents file. You will further need to define a new file for your system function, e.g. <qf_cmd.c> or <qf_menus.c> or <qf_grafx.c> or a similar name. Defining any new file also requires some specific changes such as new entries in <compro.h>, <makefile.src>, and <makefile.inc>. You'll also need to change <NARS2000.vcxproj> which you can do through Visual Studios 20xx GUI or IDE(integrated developer's environment). Try to maintain a list of the various files you edit/change because if NARS subsequently moves to a new release and you need to synch with it, it is helpful to know which files you modified - to synch plus reinstate, to bring forward your local changes.

General Reference Notes

Notation Convention on this wiki page: Unless otherwise specified all file names used on this page will exclude their path which is C:\NARS2000\trunk\.

Every programming language uses at least two primary concepts 1) mnemonics and 2) a syntax to implement that language. NARS is no different. Every NARS quad system command has an associated mnemonic or reference name. For example, Quad CR or ⎕ CR - Canononical Representation - uses mnemonic SysFnCR_EM_YY, as found in its definition file qf_cr.c. Quad FX or ⎕ FX - Fix or Function eXecute - uses mnemonic SysFnFX_EM_YY, per file qf_fx.c. Note the similarity in file naming conventions for both c files.

Several Quad functions have been implemented using PHP magic functions, for example Quad VR or ⎕ VR - Visual Representation - uses mnemonic SysFnVR_EM_YY, per definition file qf_vr.c. However, Quad VR also has an additional PHP magic header file called in this case mf_quadvr.h. Quad FMT is similarly coded using a PHP magic function header file.