Creating New System Functions

Tuesday 3 December 2024 17:48 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

Visually scan or browse the Build notes found in the ReleaseNotes subfolder, normally located in C:\NARS2000\trunk\ReleaseNotes using a text or string scanner program such as Windows File Explorer with its Search text box. Multiple time-lapsed prior examples of adding system functions 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 c file for your system function, e.g. <qf_cmd.c> or <qf_menus.c> or <qf_grfx.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.

For example, in C:\NARS2000\trunk\ReleaseNotes\Notes-1295.txt system function Quad T or ⎕T was created and implemented, to return a Tick Count for time-sensitive APL subroutine stop-watch timing purposes. The following seven files were edited/affected by the addition of system function ⎕T into NARS2000.exe. Listed below are edited notations extracted from <Notes-1295.txt>:

COMPRO.H:   #1
  Include <qf_t.pro> in the list of prototype files.

MAKEFILE.INC:   #2
MAKEFILE.SRC:   #3
NARS2000.32.VCPROJ:   #4
NARS2000.64.VCPROJ:   #5
  Include <qf_t.c> in the list of source files.   #6

QF_T.C   #6(again)
  Implement []T.

SYSVARS.C:   #7
  Include []T in the list of niladic system functions.

Note above how filenames edited/changed were kept track of, including general notes on what was performed including the purpose of the revision/edit-change by the System Developer. This filename + purpose tracking along with associated note keeping is considered good programming, a best developer practice. Such detailed record-keeping makes program flow and source-code maintenance much easier to follow and subsequently revise as needed.

Continuing with the formation or genesis process re system function ⎕T example just above, viewing(using a standard text editor such as notepad.exe) file <qf_t.c> which is the central ⎕T function-defining c file, you will note that the mnemonic(see #General Reference Notes) for ⎕T is SysFnT_EM_YY. A File Explorer search for string SysFnT_EM_YY will bring up primarily two found-in files, <qf_t.c> and <sysvars.c>.

Therefore we may conclude or determine - that operational functionality for this particular system function ⎕T was contained in just two files. The other five affected files, and not to be ignored, were impacted for overall programming structural integrity, potential debugging/compilation, and NARS2000 overall modeling purposes. Not every System Function impacts or requires so few files, but ⎕T is a solid 'minimal impact elsewhere' System Function example.

<sysvars.c> Reference Table

All ⎕ System Variables and System Functions, per system reference table (7 column table) are listed/defined within file <sysvars.c>. Quad T's entry is extracted just below. The sysvars table helps APL's interpreter understand "how" to handle each quad system variable and function, how each is "supposed to operate"; thus helping the Interpreter identify syntax errors, valence errors, domain errors, etc.
⎕T's entry(within niladic system functions grouping) in table:

SysName	Valence	Var?	Std?	Exec Routine(name)	Sys_Vars	Descr
QUAD L"t"	0	FALSE	FALSE	SysFnT_EM_YY	0	High Resolution Time

Every APL/APL2 Quad System Variable and Quad System Function(niladic, monadic and dyadic) has an entry in the <sysvars.c> table. System function ⎕T, because it is niladic, has a zero valence; it is not a System Variable(False); it has a function mnemonic or calling name = SysFnT_EM_YY; it uses zero system variables.

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.