Creating New System Functions
|
Sunday
24
November
2024
03:17 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 in NARS source code. 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. Sys Fcn Ct=30. Snapshot as of Thu 7/2/15 10:03:25 AM:
| QuadFcn c FileName | APL System Function | Mnemonic Exec Name | c FileSize | Function Type(sysvars.c) | Description(sysvars.c) | |
|---|---|---|---|---|---|---|
| C:\NARS2000\trunk\qf_a.c | ||||||
| ⎕A | SysFnA_EM_YY | 3,151 | Niladic | Alphabet | ||
| C:\NARS2000\trunk\qf_at.c | ||||||
| ⎕AT | SysFnAT_EM_YY | 44,356 | Monadic or Dyadic | Attributes | ||
| C:\NARS2000\trunk\qf_av.c | ||||||
| ⎕AV | SysFnAV_EM_YY | 5,188 | Niladic | Atomic Vector | ||
| C:\NARS2000\trunk\qf_cr.c | ||||||
| ⎕CR | SysFnCR_EM_YY | 33,687 | Monadic or Dyadic | Canonical Representation | ||
| C:\NARS2000\trunk\qf_d.c | ||||||
| ⎕D | SysFnD_EM_YY | 3,149 | Niladic | Digits | ||
| C:\NARS2000\trunk\qf_dl.c | ||||||
| ⎕DL | SysFnDL_EM_YY | 8,265 | Monadic or Dyadic | Delay Execution | ||
| C:\NARS2000\trunk\qf_dr.c | ||||||
| ⎕DR | SysFnDR_EM_YY | 49,334 | Monadic or Dyadic | Data Representation | ||
| C:\NARS2000\trunk\qf_ea.c | ||||||
| ⎕EA | SysFnEA_EM_YY | 9,565 | Monadic or Dyadic | Execute Alternate | ||
| C:\NARS2000\trunk\qf_ec.c | ||||||
| ⎕EC | SysFnEC_EM_YY | 17,469 | Monadic or Dyadic | Execute Controlled | ||
| C:\NARS2000\trunk\qf_em.c | ||||||
| ⎕EM | SysFnEM_EM_YY | 3,106 | Niladic | Event Message | ||
| C:\NARS2000\trunk\qf_error.c | ||||||
| ⎕ERROR | SysFnERROR_EM_YY | 7,129 | Monadic or Dyadic | Signal Error | ||
| C:\NARS2000\trunk\qf_es.c | ||||||
| ⎕ES | SysFnES_EM_YY | 18,322 | Monadic or Dyadic | Event Simulate | ||
| C:\NARS2000\trunk\qf_et.c | ||||||
| ⎕ET | SysFnET_EM_YY | 6,645 | Niladic | Event Type | ||
| C:\NARS2000\trunk\qf_ex.c | ||||||
| ⎕EX | SysFnEX_EM_YY | 23,537 | Monadic or Dyadic | Expunge Names | ||
| C:\NARS2000\trunk\qf_fmt.c | ||||||
| ⎕FMT | SysFnFMT_EM_YY | 108,506 | Monadic or Dyadic | Format | ||
| C:\NARS2000\trunk\qf_fx.c | ||||||
| ⎕FX | SysFnFX_EM_YY | 18,028 | Monadic or Dyadic | Function Fix | ||
| C:\NARS2000\trunk\qf_lc.c | ||||||
| ⎕LC | SysFnLC_EM_YY | 5,679 | Niladic | Line Counter | ||
| C:\NARS2000\trunk\qf_mf.c | ||||||
| ⎕MF | SysFnMF_EM_YY | 38,096 | Monadic or Dyadic | Monitor Function | ||
| C:\NARS2000\trunk\qf_nc.c | ||||||
| ⎕NC | SysFnNC_EM_YY | 20,952 | Monadic or Dyadic | Name Classification | ||
| C:\NARS2000\trunk\qf_nfns.c | ||||||
| ⎕NFNS | SysFnNAPPEND_EM_YY | 260,952 | Monadic or Dyadic | Append Data To An Open Native File | ||
| C:\NARS2000\trunk\qf_nl.c | ||||||
| ⎕NL | SysFnNL_EM_YY | 17,698 | Monadic or Dyadic | Name List | ||
| C:\NARS2000\trunk\qf_sysid.c | ||||||
| ⎕SYSID | SysFnSYSID_EM_YY | 4,826 | Niladic | System Identifier | ||
| C:\NARS2000\trunk\qf_sysver.c | ||||||
| ⎕SYSVER | SysFnSYSVER_EM_YY | 8,556 | Niladic | System Version | ||
| C:\NARS2000\trunk\qf_t.c | ||||||
| ⎕T | SysFnT_EM_YY | 3,542 | Niladic | High Resolution Time | ||
| C:\NARS2000\trunk\qf_tc.c | ||||||
| ⎕TC | SysFnTC_EM_YY | 12,390 | Niladic | Terminal Control Characters | ||
| C:\NARS2000\trunk\qf_tf.c | ||||||
| ⎕TF | SysFnTF_EM_YY | 53,263 | Monadic or Dyadic | Transfer Form | ||
| C:\NARS2000\trunk\qf_ts.c | ||||||
| ⎕TS | SysFnTS_EM_YY | 5,165 | Niladic | Time Stamp | ||
| C:\NARS2000\trunk\qf_ucs.c | ||||||
| ⎕UCS | SysFnUCS_EM_YY | 23,003 | Monadic or Dyadic | Universal Character Set | ||
| C:\NARS2000\trunk\qf_vr.c | ||||||
| ⎕VR | SysFnVR_EM_YY | 5,624 | Monadic or Dyadic | Vector Representation of a Function | ||
| C:\NARS2000\trunk\qf_wa.c | ||||||
| ⎕WA | SysFnWA_EM_YY | 3,367 | Niladic | Workspace Available |
Magic Function C Header File vs APL - a Comparison
Extract from NARS file C:\NARS2000\trunk\mf_quadvr.h for System Function ⎕VR (C source code header file, just below):
//***************************************************************************
// Magic function/operator for Monadic []VR
//
// Monadic []VR -- Visual Representation
//
// Return a visual representation of a user-defined function/operator
//***************************************************************************
static APLCHAR MonHeaderVR[] =
L"Z←" MFON_MonVR L" R;L;⎕IO";
static APLCHAR MonLineVR1[] =
L"⎕IO←0 ⋄ Z←1 ##.⎕CR R";
static APLCHAR MonLineVR2[] =
L"→(0≠⍴Z)/L1 ⋄ Z←'' ⋄ →0";
static APLCHAR MonLineVR3[] =
L"L1:→(1=≡Z)/0";
static APLCHAR MonLineVR4[] =
L"L←'∇'∊0⊃Z";
static APLCHAR MonLineVR5[] =
L"Z←(∊((⊂[1]'LO< ∇>P<[>Q<]>I6' ⎕FMT⍳⍴Z),¨Z),¨⎕TCNL),' ∇'";
static APLCHAR MonLineVR6[] =
L"→L/0 ⋄ Z←Z,(' ',⍕2 ##.⎕AT R),' (UTC)'";
static LPAPLCHAR MonBodyVR[] =
{MonLineVR1,
MonLineVR2,
MonLineVR3,
MonLineVR4,
MonLineVR5,
MonLineVR6,
};
MAGIC_FCNOPR MFO_MonVR =
{MonHeaderVR,
MonBodyVR,
countof (MonBodyVR),
};
⎕VR - APL monadic function named MFON_MonVR(just below):
⎕CR 'MFON_MonVR'
Z←MFON_MonVR R;L;⎕IO
⎕IO←0 ⋄ Z←1 ##.⎕CR R
→(0≠⍴Z)/L1 ⋄ Z←'' ⋄ →0
L1:→(1=≡Z)/0
L←'∇'∊0⊃Z
Z←(∊((⊂[1]'LO< ∇>P<[>Q<]>I6' ⎕FMT⍳⍴Z),¨Z),¨⎕TCNL),' ∇'
→L/0 ⋄ Z←Z,(' ',⍕2 ##.⎕AT R),' (UTC)'
Note the displaced lines yes, but great/identical similarity between the UTF-8 C source code header file and the actual APL function MFON_MonVR. In a very real sense, APL source code was imported directly into C source code via a header file, using a magic function. Hence the term magic since APL magically gets executed inside a compiled C program. This is somewhat code-wise equivalent to using the ⍎(execute) function in APL. Technically the APL simulation in C was made possible and accomplished via re-formatting the ⎕CR representation of an APL function, placing it into a C source code header file, and using PHP in the NARS2000 project model. Also technically, note the use of L" in the header file at the front of several lines - the presence of the prefix L in C source code indicates Unicode string to the C compiler.
Ref. also System Function ⎕VR and System Function ⎕CR
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.
