Creating New System Functions

From NARS2000
Revision as of 20:43, 1 July 2015 by Robert Wallick (talk | contribs) (Added section for Source Code Derived List of APL System Functions)
Jump to navigationJump to search

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.

Source Code Derived List of APL System Functions

Source Code List of NARS Quad System Functions, per qf_*.c Files Derivative. Snapshot as of Wed 7/1/15 4:38:57 PM:

QuadFcn c FileName APL System Function Mnemonic Exec Name c FileSize
C:\NARS2000\trunk\qf_a.c
⎕A SysFnA_EM_YY 3,151
C:\NARS2000\trunk\qf_at.c
⎕AT SysFnAT_EM_YY 44,356
C:\NARS2000\trunk\qf_av.c
⎕AV SysFnAV_EM_YY 5,188
C:\NARS2000\trunk\qf_cr.c
⎕CR SysFnCR_EM_YY 33,687
C:\NARS2000\trunk\qf_d.c
⎕D SysFnD_EM_YY 3,149
C:\NARS2000\trunk\qf_dl.c
⎕DL SysFnDL_EM_YY 8,265
C:\NARS2000\trunk\qf_dr.c
⎕DR SysFnDR_EM_YY 49,334
C:\NARS2000\trunk\qf_ea.c
⎕EA SysFnEA_EM_YY 9,565
C:\NARS2000\trunk\qf_ec.c
⎕EC SysFnEC_EM_YY 17,469
C:\NARS2000\trunk\qf_em.c
⎕EM SysFnEM_EM_YY 3,106
C:\NARS2000\trunk\qf_error.c
⎕ERROR SysFnERROR_EM_YY 7,129
C:\NARS2000\trunk\qf_es.c
⎕ES SysFnES_EM_YY 18,322
C:\NARS2000\trunk\qf_et.c
⎕ET SysFnET_EM_YY 6,645
C:\NARS2000\trunk\qf_ex.c
⎕EX SysFnEX_EM_YY 23,537
C:\NARS2000\trunk\qf_fmt.c
⎕FMT SysFnFMT_EM_YY 108,506
C:\NARS2000\trunk\qf_fx.c
⎕FX SysFnFX_EM_YY 18,028
C:\NARS2000\trunk\qf_lc.c
⎕LC SysFnLC_EM_YY 5,679
C:\NARS2000\trunk\qf_mf.c
⎕MF SysFnMF_EM_YY 38,096
C:\NARS2000\trunk\qf_nc.c
⎕NC SysFnNC_EM_YY 20,952
C:\NARS2000\trunk\qf_nfns.c
⎕NFNS SysFnNAPPEND_EM_YY 260,952
C:\NARS2000\trunk\qf_nl.c
⎕NL SysFnNL_EM_YY 17,698
C:\NARS2000\trunk\qf_sysid.c
⎕SYSID SysFnSYSID_EM_YY 4,826
C:\NARS2000\trunk\qf_sysver.c
⎕SYSVER SysFnSYSVER_EM_YY 8,556
C:\NARS2000\trunk\qf_t.c
⎕T SysFnT_EM_YY 3,542
C:\NARS2000\trunk\qf_tc.c
⎕TC SysFnTC_EM_YY 12,390
C:\NARS2000\trunk\qf_tf.c
⎕TF SysFnTF_EM_YY 53,263
C:\NARS2000\trunk\qf_ts.c
⎕TS SysFnTS_EM_YY 5,165
C:\NARS2000\trunk\qf_ucs.c
⎕UCS SysFnUCS_EM_YY 23,003
C:\NARS2000\trunk\qf_vr.c
⎕VR SysFnVR_EM_YY 5,624
C:\NARS2000\trunk\qf_wa.c
⎕WA SysFnWA_EM_YY 3,367

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.