NARS2000 - User contributions [en]

Building An Executable

2016-12-19T19:27:07Z

Robert Wallick: Clarified download, install and use of Tortoise SVN at SourceForge

<div style="float:right; padding-left:5px;">
{| style="text-align:left; border:1px solid #aaaaaa; background-color:#f9f9f9;width: 200px;font-family: Verdana, sans-serif;"
|- padding:5px;padding-top:0.5em;font-size: 95%;
|
----
<div style="border:1px solid #ccc; background: #fff; border-right:3px solid #ccc; border-bottom:3px solid #ccc; text-align: center; padding:3px; float:right; font-size: smaller; line-height: 1.3; margin-right: 4px;">
<div style="width:100%">{{CURRENTDAYNAME}}</div>
<div style="font-size: x-large; width: 100%;">{{CURRENTDAY}}</div>
<div style="width: 100%;"> {{CURRENTMONTHNAME}}</div>
<div style="width: 100%;">{{CURRENTYEAR}}</div>
<div style="background: #aaa; color: #000;">'''{{CURRENTTIME}}''' UTC</div>
</div>
<big>'''NARS2000 Building The Executable'''</big>
----
<div style="text-align:center;">
</div>
|-
|
__TOC__
|}
</div>
==Update Notice==

Although it is not the "ONLY compiler - IDE (integrated developer's environment) choice", the below uses '''Visual Studio 2013''' as its designated C/C++ Compiler and IDE(Integrated Developer's Environment, GUI/Graphical User Interface for programming). All source code compiles correctly and multiple APL workspaces have been tested for correct APL/NARS functionality. This page is current, up-to-date re NARS working with VS2013's compiler and standards. The conversion to VS2013 resulted in a more up-to-date (5 years[2008 to 2013] more current software technology) program for the GUI Builder and Compiler interface, including newer C/C++ programming standards. This has represented a major cyclical software upgrade and results in greater APL user functionality via improved C coding. Recent releases of NARS2000.exe (32 and 64-bit versions) are fully functional.
<div align="right">v---- '''Useful Developer links:''' ----v [http://svnbook.red-bean.com Version Control with Subversioning - Conceptual Gen Bkgnd.] [http://sourceforge.net/p/forge/documentation/svn/ Source Forge Versioning Documentation] [http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ Source Forge NARS2000 Source Code]</div>

==Why Build Your Own==

First of all, you do not have to build your own. NARS has already created a great existing Nested Arrays Research System APL interpreter. NARS2000.exe is freely available at [http://www.nars2000.org/download/Download.html NARS Downloads]. Downloads includes Beta releases for APLers so inclined.

On the other hand, why not expand your programming/software and computer skill horizons? Many people think and believe '''Kenneth Iverson's''' work remains that of a true genius, a bright light among some very bright intellectual lights, both from a theoretical as well as a software implementation perspective. Here's your opportunity to attempt to improve upon some very substantive, preexisting software development work - to further it, to make it even better, and perhaps best of all - '''it's free'''.

Personalize some already pretty amazing software for yourself, or share it with others and get '''their feedback''' for even greater insight and subsequent improvement. NARS version of APL already has over a quarter million lines of source code, subroutines, macros, functions, etc. - 50 years of sometimes intense and continuing evolution, so you are not creating something from undeveloped scratch, but inheriting and working from already highly evolved, rigidly disciplined concepts and rigorously debugged software over time.

'''APL/2''' has been used in physics, science, genetic engineering-DNA studies, advanced mathematics, robotics, engineering, artificial intelligence, image processing, bio-medicine, VLSI, financial, statistical and social science applications. NASA and Astronomers have used APL.

Now APL/2 is 100% customizable. Perhaps you will be the first to customize APL to safely drive a vehicle, help save a life, make new discoveries or make some process(es) more efficient.

It's '''free'''. It's '''evolved'''. Once you start examining NARS/APL/APL2 source code you'll find it is comprehensive, elegant, process-symbol-efficient, focused toward the end-user, evolved over some fifty years of use, structurally enigmatic, tirelessly debugged and rich with coding techniques - a great learning tool, even if absolutely nothing else - and NARS believes it is far, far better than just a learning tool. You'll learn about Bison Parsing, how it helps define compilers and interpreters. Further, NARS is a tremendous opportunity to learn more about the human-machine interface; how machine hardware operates and - better understand how software and hardware interact together.

One of the stellar, intellectually expansive aspects of APL/2 is - how fully the language embraces the breadth of hardware functionality. This includes instructions running core processor chip(s) and peripheral devices. This is not your grandparents' punch-card software program run on a room-sized computer, although that was marvelous at its time, but it may have taken him/her several days to get results back for in an introductory chemistry or math lab course. Today '''[http://phys.org/news/2015-03-quantum-unexpected-ways.html data structures influence speed of quantum search in unexpected ways]'''.

==Platforms==

The current version of NARS2000 may be run and built on a variety of Windows platforms, including most or all post-Windows-98 OS versions. Furthermore, a long-term goal is to enable NARS to be built on Linux, Mac OS, etc. as per user requests and Developer interests. If you do not have a Windows machine, the following may be helpful to you:

'''[http://www.howtogeek.com/187359/5-ways-to-run-windows-software-on-a-mac/ Five ways to run Windows software on a Mac.]''' From HowToGeek.com, methods include 1)Virtual Machines, 2)Boot Camp, 3)Wine, 4)CrossOver Mac (not free) and 5)Remote Desktop.

'''[http://www.howtogeek.com/133515/4-ways-to-run-windows-software-on-linux/ Four ways to run Windows software on Linux.]''' Again from HowToGeek.com, methods include 1)Use Wine, 2)Run Windows in a Virtual Machine, 3)Try Crossover (not free) and 4)Remote Desktop. A fifth way per [http://www.pcworld.com/article/2900497/how-to-run-windows-software-in-linux-everything-you-need-to-know.html PC World] is dual booting both Linux and Windows on your machine. This essentially involves partitioning hard drives with a portion reserved for Linux and a portion reserved for Windows. With costs of external hard drives continuing to decline, buying an external or network hard drive may free up hard drive storage space requirements.

'''[http://www.howtogeek.com/173353/how-to-run-windows-software-on-a-chromebook/ How to Run Windows Software on a Chromebook {notebook or tablet PC}.]''' Again from HowToGeek.com, methods include 1)Access a Windows Desktop Remotely, 2)Use Developer Mode and Install Wine (not available for all Chromebooks), 3)Use Developer Mode and Install a Virtual Machine (may require an Intel Chromebook).

Furthermore, if you work using a tablet or other computing device which supports remote desktop software such as '''[http://teamviewer.com Team Viewer]''' and you have a home or work computer running Windows - then you can remotely use NARS over your network and internet using that computer as a host and your local device as a client. Network and internet speeds are sufficiently fast and TeamViewer, for instance, is very good at making your remote desktop seem and respond as if virtually right in front of you.

For the present, the following sections detail descriptions for building the executable with bias towards Windows.

==Downloads==

To build the executable in summary you'll need the following:

# C Compiler and Linker
## Make program
## Resource Compiler
## Windows SDK
# Parser Generator
# Zip Utility
# PHP (Hypertext Preprocessor)
# NARS2000 Source Code
# NARS2000 External Libraries
# Optionally, Multi-precision Library Source
# STDINT.H header file
# Version Control program
# Doctor Dump SDK
# Optionally, a File Differencing/Merge program
 All of the tools you'll need are '''freely available'''. Some of them happen to be Microsoft-specific. Bill Gates while at Harvard actually worked a bit on/with APL, obviously he discovered the importance of working with arrays and symbolic notation. At the same time there is no reason more generic tools (such as [http://www.delorie.com/djgpp/ DJGPP], [http://www.cygwin.com/ Cygwin] or [http://www.mingw.org/ MinGW]) can't be used, a task NARS is hoping someone will volunteer to investigate. In particular, the '''tools currently used''' to create the APL Executable, in detail, are as follows:
 
# '''C''' (needed for this NARS2000 project is '''Visual C++ 2013''' = C++ GUI development environment and compiler for the C language, which much of APL's interpreter is written in). Compiler and Linker: '''[https://app.vssps.visualstudio.com/profile/review?download=true&family=VisualStudioExpressDesktop&release=VisualStudio2013Upd4&type=web&slcid=0x409 Microsoft Visual Studio 2013 Express for Desktop Windows]''' (download requires a FREE Microsoft/Visual Studio account) OS requires Windows XP or later — includes Link, Make, a Resource Compiler, and an SDK (among others). Download/Installation Notes: The '''downloaded file''' may be double-clicked in Windows Explorer. VS 2013 does NOT Install to a mapped or network drive(but to something like C:\Program Files\...). It must be Installed on a local PC drive (e.g. C:\...) and '''unmapped directory''' (but you can map to it later) - Microsoft apparently requires installation to a local machine drive letter such as "C:\...".   VS2013 Desktop is free '''and''' it includes a GUI or graphical user interface (icon-based IDE or integrated developer's environment), which is geometrically easier to use than a command-line interface. Windows 8.1 SDK (does NOT require Windows 8.1, but does update for some 8.1 capabilities, especially useful for using Visual Studio 2013; '''[https://msdn.microsoft.com/en-us/windows/desktop/bg162891.aspx?f=255&MSPPError=-2147217396 download is available at Microsoft]'''. '''Windows SDK''' (the following MAY NOT BE NECESSARY, SDK=Software Developers Kit, sometimes needed for '''64-bit installations''', usually choose download file GRMSDKX_EN_DVD.iso even for Intel machines) '''[http://www.microsoft.com/en-us/download/details.aspx?id=18950 download here]''', with '''installation instructions [https://github.com/enGits/engrid/wiki/Configure-Microsoft-Visual-Studio-2008-Express-to-also-build-for-Windows-x64 here]'''.
# '''Parser Generator''': '''[https://cygwin.com/install.html Bison]''', a Cygwin package, Save and run either '''setup-x86.exe''' (32-bit systems) or '''setup-x86_64.exe''' (64-bit systems) as appropriate to your system, '''Choose A Download Source''': Install from Internet, '''Select Root Install Directory''', '''Select Local Package Directory''', '''Select Your Internet Connection''', '''Choose A Download Site''', '''Select Packages''': Leave alone '''All (Default)''' - first time through, just click [Next], '''Devel''', and '''bison''', other dependent packages may be installed along with '''bison''', if not then '''after first''' Cygwin installation finishes, double-click the downloaded Cygwin file in Windows Explorer, downloaded filename should be something like '''setup-x86_64.exe''' and the '''second time through''' do specifically download and install '''Dev''', '''Bison''' - informally note the '''tree structure''' during the Bison download/install since '''creating parse trees''' is '''very much''' a ''Bison program specialty'', a strength. Compilers and even APL itself relies heavily on correct statement type recognition and parsing. To make sure you successfully downloaded and installed '''bison.exe''', the file should be '''found''' or reside in the C:\Cygwin\bin or C:\cygwin64\bin folder. Make note of the folder location since you will need it when setting the PARGEN environment variable shortly, below.
# '''Zip Utility''': '''[http://www.7-zip.org/ 7-Zip]''' (Latest version, 32- or 64-bit, as appropriate to your system; needed to Extract/Unzip the files and folders you are downloading for this project.) If you already have a Zip utility program on your PC, Tablet or Server such as WinZip, you can normally skip the 7-Zip download/install.
# '''PHP''' (Hypertext Preprocessor): '''[http://www.php.net/downloads.php Downloads]''' (Windows downloads for Windows systems.) (Windows binaries/VC9 x86 Thread Safe/Latest version/Zip or Installer, your choice) (Items to Install: Entire '''Script Executable''', and entire '''Extras'''). Place the unzipped file's contents into something like "C:\PHP". The executable file "php.exe" needs to be "on your directory or environmental path" when later compiling or building the APL executable.
# '''NARS2000 Source Code''': Click on '''[http://sourceforge.net/projects/nars2000/ Browse Code] button''' at '''NARS''' SourceForge.net '''code repository'''.
## You also likely need a Version Control program for SourceForge code 'checkouts', e.g. see '''Tortoise SVN''' below and '''[http://tortoisesvn.net/ here, visit Tortoise SVN's download page]''', then download and install Tortoise SVN's 64-bit or 32-bit version depending on your operating system to subsequently be able to auto-check-out NARS source code. '''Prior''' non-current NARS Source Code versions available at [http://code.google.com/p/nars2000/source/checkout Code Google].
# '''NARS2000 External Libraries''': [http://www.nars2000.org/download/binaries/misc.zip Miscellaneous Library] (misc.zip, which contains 4 .php files and 1 .ttf file - all directly unzipped into C:\NARS2000) and the following NARS libraries:
## [http://www.nars2000.org/download/binaries/mplibs.zip '''MPIR/MPFR/ECM Libraries'''] - These libraries(mplibs.zip) should be directly extracted or unzipped into the C:\NARS2000 folder such that three(3) distinct sub-directories are '''directly''' created: \ecm, \mpfr and \mpir, e.g. C:\NARS2000\ecm.
## [http://www.nars2000.org/download/binaries/gsldir.zip '''gsl Library'''] - This library(gsldir.zip) should be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\gsl'''. Folder structure "C:\NARS2000\gsldir\gsl" would be invalid.
## [http://www.nars2000.org/download/binaries/qdebug.zip '''qdebug Library'''] - This library(qdebug.zip) should also be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\qdebug'''. Make sure it is NOT double-enclosed when unzipped, for example the following would be an invalid folder setup structure: C:\NARS2000\qdebug\qdebug.
# '''Multi-precision Library Source Code: [http://www.nars2000.org/download/binaries/mpfns-src.zip MPIR/MPFR/ECM Source]'''. This zipped download is large (roughly 0.5GB) and is needed primarily to reproduce files in the MPIR/MPFR/ECM Library download so as to satisfy requirements of the GNU General Public License (GPL) v3. For more details on using the files in the download, look in the zipped file for <code>readme.txt</code>. If you are content to use the already-compiled existing binary libraries in [http://www.nars2000.org/download/binaries/mplibs.zip MPIR/MPFR/ECM Libraries], you may not immediately need the MPIR/MPFR/ECM Source Code; on the other hand - 128-bit CPU chips are in manufacturing production pipelines, quadruple-precision 128-bit floating-point format has been standardized by the IEEE and ultra-precise calculations are already needed in such fields as quantum physics, ref. [http://phys.org/news/2014-06-physicists-quantum-ultra-precise.html Physicists take quantum leap toward ultra-precise measurement], 6/2/2014. One of APL's strengths is its handling of mathematically precise calculations and the '''large size''' of the multi-precision source code library reinforces that.
# [http://msinttypes.googlecode.com/svn/trunk/stdint.h STDINT.H] header file installed in the MS Visual Studio 2013 include directory (V:\VC\include -- see below)
# '''SubVersion Control program''': [http://tortoisesvn.net/downloads Tortoise SVN] (Current version, 32- or 64-bit depending upon your OS)
# '''Doctor Dump SDK''': [https://drdump.com/public/DoctorDumpSDK/DoctorDumpSDK.zip Doctor Dump SDK] - e.g. DoctorDumpSDK.zip.
# '''File Differencing/Merge program''': [http://winmerge.org/ WinMerge] ('''Latest stable version''', usually downloads to something like WinMerge-k.m.n-Setup.exe where k, m and n are version/sub-version numbers.)

==Install Tools==

'''Preface''', Convention: '''x86''' generally refers to '''32-bit''' software installations while 64 (or blank) represents 64-bit software installations on a Windows OS machine. NARS works on '''both''' 32-bit and 64-bit systems, but you should decide '''in advance''' which type of install you want 64 vs. 32-bit - ditto for all tool installs. Installation examples:
# C:\Program Files (x86)\        Represents 32-bit software program installation, normal folder location.
# C:\Program Files\                 Represents 64-bit software program installation, normal folder location.
Also, '''both''' folder locations just above frequently and even always exist on most machines, but for consistency and integration purposes the software should be 32 '''or''' 64-bit. Most people choose 64-bit installs if their Windows OS supports the 64-bit architecture, with 32-bit available for backward software compatibility in conjunction with less current systems. If you don't know which architecture your system uses, go to the Control Panel, System Information. Downloads usually get placed into a Downloads folder. Several of the unzipped NARS tools get placed directly into the C:\NARS2000 folder, see individual tools for exact locations. 

To install the Microsoft '''Visual Studio 2013 Express C compiler''', see Downloads(detail, #1 above). Visual C++ 2013 usually installs into something like, "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" (64-bit loc) and you may want to place a '''Shortcut''' to '''VCExpress.exe''' on your Desktop by right-clicking on that VCExpress.exe file in Windows Explorer and Send To - Desktop (create shortcut). (Windows 8 Users: You can also '''Pin VCExpress.exe To your Taskbar''' for quick, easy access.) (Prior/obs. Microsoft setup routine name: run the vcsetup.exe program.) Afterwards including after drive plus folder remapping - the files '''msobj80.dll''', '''mspdb80.dll''', '''mspdbcore.dll''', and '''mspdbsrv.exe''' all need to be copied from '''V:\Common7\IDE''' to '''V:\VC\bin''', where the '''V''' drive is a substitute/mapping for '''C:\Program Files\Microsoft Visual Studio 9.0'''. See the discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

To install the Parser Generator (Bison), see the instructions above. When the Cygwin setup program asks you to choose a '''Default Text File Type''', choose '''DOS/text''' so any committed files are the same as in the version control repository.

To install Doctor Dump SDK, unzip it in a directory at or above %NARSROOT%, this usually means unzipping into folder C:\DoctorDumpSDK. See also discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

Install the rest of the tools as per their instructions above, in the Downloads section.

==Install The Source Code==

<ol>
<li>First create a NARS2000 '''root folder''' somewhere on one of your hard drives, perhaps calling it '''NARS2000''', as in '''C:\NARS2000''' (most common) or perhaps at some lower level. The source code and external libraries are typically installed at or into this level, e.g. qdebug.zip into C:\NARS2000 as C:\NARS2000\qdebug.</li>
<li>Under the root folder make three folders: '''trunk''', '''msieve''', and '''branches'''. The first folder ('''trunk''') will hold the main body of NARS/APL built exe interpreter '''source''' code. The second ('''msieve''') will be utilized for code used to '''factor numbers''', and the third ('''branches''') will contain individual developer branches of the main code not as yet ready for release, but made public for other developers to see.</li>
<li>Using a Version Control program such as '''TortoiseSVN''', download-checkout the source code (see [[#Check_Out_The_Source_Code|Check Out The Source Code]]),</li>
<li>Download the '''misc.zip''', '''qdebug.zip''', '''gsldir.zip''', and '''mplibs.zip''' files into the root folder and unzip them (directly into that root folder, e.g. C:\NARS2000) using e.g. '''7z.exe''' (unzip/extract program used) as in '''7z x misc.zip''', '''7z x qdebug.zip''', '''7z x gsldir.zip''', and '''7z x mplibs.zip''' - or double-click on those downloaded zip file names using Windows File Explorer and Extract All (again typically directly into NARS root folder previously set up).</li>
</ol>

==Check Out The Source Code==

An easy way to initialize your copy of the source code for the first time, although it may initially appear cumbersome to an SVN newcomer, is to use a version control program such as TortoiseSVN, mentioned above. One very helpful feature of TortoiseSVN is that it integrates well with Windows File Explorer. After downloading and installing TortoiseSVN and then rebooting your PC, there are two directories you will need to Install/initialize-checkout/TortoiseSVN-on.
# '''First''' bring up Windows Explorer, right-click on the '''trunk''' folder you manually created, and choose '''SVN Checkout'''.
## If you do not see "SVN Checkout" when you right-click on the '''trunk''' folder, download '''Tortoise SVN''' per the '''Tortoise SVN link above'''([[#Downloads|Downloads-NARS2000 Source Code-Tortoise SVN]]. The online NARS SourceForge URL of source code repository: is '''svn://svn.code.sf.net/p/nars2000/code/trunk''' and your local Checkout directory: is '''C:\NARS2000\trunk''' (or wherever your trunk folder is) - quite likely you will have to edit the TortoiseSVN repository field or program local folder field because default text inserted by TortoiseSVN usually does not match folder location(s) identically. Depth should show Fully recursive, the default.
## To begin source code downloading/checkout into your locally created '''trunk''' folder click the '''OK''' button. Code downloading/checkout should then begin. With a high-speed Internet connection, time required to TortoiseSVN download/checkout NARS code is on the order of roughly two minutes. When successfully complete, you should get a return message at the end of the downloads list, like '''Completed at revision nnnn'''.
# '''Second''' (and this is a similar repeat step but using folder '''msieve''' instead of trunk), bring up Windows Explorer, right-click on the '''msieve''' folder you likewise manually created - and choose '''SVN Checkout...'''. This time online NARS '''URL of repository:''' is '''svn://svn.code.sf.net/p/nars2000/code/msieve''' (this address is slightly different than step 1) and your local '''Checkout directory:''' is '''C:\NARS2000\msieve''' (or wherever your '''msieve''' folder is). Again, depth should be fully recursive and click the '''OK''' button to begin. This step two normally completes in under five seconds, downloading far fewer files than the trunk download. Normally, the same msieve revision number should appear after finishing this download as per trunk download in step 1.

The above '''two''' steps/distinct-folders need be initialized this first checkout time through - in order to establish the special hidden SVN directories for subversion "synching" between your local source code and NARS online code repository. As a brief check that your '''local''' NARS source code files match NARS, there should be green check marks on folders trunk and msieve on your PC, placed there by TortoiseSVN. [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-wcstatus.html TortoiseSVN Status Information.]

You will still or now need to download and unzip '''qdebug.zip''', '''misc.zip''', '''gsldir.zip''', and '''mplibs.zip''' as described above.

Subsequently, you may quickly and easily update your local copy of NARS source code by right-clicking on the '''trunk''' and/or '''msieve''' folders and choose '''SVN Update'''. One useful feature of sub-versioning programs such as TortoiseSVN is that only '''changed files''' from the online latest official version will need to be subsequently downloaded as changes are made in futuro, re subsequent NARS revisions.

Since you may be unfamiliar with the download process your first time through, it make take slightly longer; however, the second or third time you Check Out The Source Code, over time, the entire "update to most current NARS source code revision" process will probably take under 3 to 5 minutes total, depending however on your (high-speed) Internet service provider's(ISP) download speed.

==Folders==

After unzipping the above files, the structure under the '''NARS2000 root folder''' should look very much like the following('''leftmost column'''), where lower level sub-directories and individual sub-folder file names have been omitted:
{|class="wikitable"| style="width: 40%; border:1px dotted blue;"
!'''NARS2000''' SubFolder:
! Downloaded Zip '''Source''' File or Checkout Process:
|-
| branches\
| class="Unicode" style="text-align:center;" | Created manually(1)
|-
| ecm\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| gsl\
| class="Unicode" style="text-align:center;" | '''gsldir'''.zip
|-
| mpfr\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| mpir\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| msieve\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''msieve'''
|-
| qdebug\
| class="Unicode" style="text-align:center;" | '''qdebug'''.zip
|-
| trunk\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\binaries\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\Extensions\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\htdocs\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\images\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\MediaWiki\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\ReleaseNotes\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\WineHQ\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
|}
(1) Subfolder '''\branches''' should be '''created manually''' (e.g. Windows Explorer, right-click, New, Folder). It is used to hold subprojects you may develop. For example if your name is Bill Gates, you might have the following subfolders, each representing a NARS subproject: 
C:\NARS2000\branches\bgates\NARS_Spreadsheets 
C:\NARS2000\branches\bgates\NARS_WordProcPlusAPLEdits 
C:\NARS2000\branches\bgates\EZMenus 
C:\NARS2000\branches\bgates\Graphics 

==Choose How To Build==

The following sections describe two alternate ways to build the executable. One is the GUI interface of VC++ Express, the other is a command line interface using a '''makefile'''.

==Set Up VC++ Express==

If you are using Visual Studio 2013/VC++ Express, the project file is in the '''trunk''' folder and is called '''NARS2000.vcproj'''. You may load it manually every time you invoke VC++ Express, or you may load it automatically by placing the path to the project file on the command line in the VC++ Express shortcut as in '''"C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" C:\NARS2000\trunk\NARS2000.vcproj''' or wherever you defined your NARS2000 root folder.

The vast majority of the project settings are found in the above file with some exceptions.

==Set Up Makefile and Environment Variables==

<hr width=25%>
'''Windows 8''': Setting up Environment and Path Variable(s):
Under Settings, Control Panel, System and Security, System, Advanced System Settings, Advanced (Tab) '''or''' in Control Panel Search for '''Environment Variables''',
* Click '''Environment Variables''' button - There is both a '''Temp Variable''' and '''Path Variable'''.
:: There are 2 sections, User Account Variables and System Variables. You normally want to add new '''System Variables'''.
::: Click '''[New]''' button for a New System Variable:
:::: Variable name       '''PARGEN'''
:::: Variable value       '''C:\cygwin64\bin\bison'''       << typical for a 64 bit install(for bison.exe in subfolder bin), for 32 bits installs see below for variable '''set''' values.
* Normally add a '''New''' variable (var Name plus Value) for each of the '''eight Set''' vars commands listed below, 8 environment variable names - such as NARSROOT, CS_DIR, ZIPPRG, PARGEN, etc.
* If you need to add another Path to an existing variable, each new or added path is separated with a semi-colon.
* After updating any Environment/Path variable(s) you apparently need to reboot since the above variable changes only affect changes in the Registry until PC is rebooted.
* The instructions below should also or alternatively work.
<hr width=25%>
If you are building from the '''makefile''' or working with the GUI C++ Compiler, you'll need to set '''eight environment variables''' in your '''autoexec.bat''' file ('''or''' see just above for setting Environment Variables via '''Windows Control Panel'''). Note that ''Environment variable #n's'' just below are shown only for helpful reference purposes.
<pre>
REM Path of the root of the NARS2000 project *ending with a backslash*
Set NARSROOT=C:\NARS2000^\                         Environment variable #1

REM Path to Doctor Dump SDK root
Set CS_DIR=C:\DoctorDumpSDK^\                      Environment variable #2

REM Path and name of zip program (7-Zip)
Set ZIPPRG="C:\Program Files\7-Zip\7z"             Environment variable #3

REM Path and name of parser generator (bison)      Environment variable #4 (next line)
Set PARGEN=C:\Cygwin\bin\bison         OR for a 64-bit install >>   Set PARGEN=C:\cygwin64\bin\bison

REM Path and name of makedep program
Set MAKEDEP=%NARSROOT%makedep.php                  Environment variable #5

REM Path and name of the <makepro.php> program
Set MAKEPRO=%NARSROOT%makepro.php                  Environment variable #6

REM Folder of SDK ("C:\Program Files\Microsoft SDKs\Windows\v7.0A")
Set SDK=U:^\                                       Environment variable #7

REM MSVC compiler ("C:\Program Files\Microsoft Visual Studio 9.0")
Set MSVC=V:\VC^\                                   Environment variable #8
</pre>
<hr width="75%">
'''Mapping Virtual Drive Letters:''' 
You will be using Windows '''subst''' command to map drive letters as references to drives '''U:''' and '''V:''' that several of the above '''environment variables''' refer to. Microsoft explanation of '''[https://technet.microsoft.com/en-us/library/bb491006.aspx subst command here]'''. 
Modify your C:\AutoExec.bat file to include something approximating the following highlighted text(version#/32/64 bit installs each vary), '''include''' the enclosing quote chars just below: 
'''subst U: "C:\Program Files\Microsoft SDKs\Windows\v7.0A"'''      (or whatever your current version is) 
'''subst V: "C:\Program Files\Microsoft Visual Studio 9.0"'''             (ditto re version 9.0=Visual Studio 2008)
 
If you do not have an '''AutoExec.bat''' file (many '''Windows 7 and 8''' users may not):
: Create a new text document using Windows File Explorer, rename it as AutoExec.bat and move(or copy) it to the '''C:\''' drive folder '''with the above two subst''' commands in it.
: Windows 7 and 8 users: File AutoExec.bat no longer automatically gets run at system-user boot-up so '''place a Shortcut to AutoExec.bat''' in the Program files '''Startup''' folder location(navigate Windows File Explorer to '''one''' of the below locations, right-click, '''New''', '''Shortcut''', '''AutoExec.bat'''). The Windows 7/8 Startup Folder usually is located as follows:
:: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup                                         (general/all users Startup folder) '''OR'''
:: C:\Users\'''UserName'''\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup       (single user Startup folder, '''UserName varies''')
'''IMPORTANT''': A successfully mapped '''V''' drive should contain a sub-sub-subfolder which then contains the '''amd64\nmake.exe''' (64-bit systems) file or '''bin\nmake.exe''' (32-bit systems), e.g. '''typical''' 64-bit configuration/location: '''C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\nmake.exe'''.
:The V drive map would '''only''' include linking through subfolder '''\Visual Studio 9.0'''. After creating the linked drives, just '''check''' to make sure your mapped '''V''' drive has the '''nmake.exe''' contained one or several subfolder levels below it. The NARS2000.exe automated Compile/Build uses '''nmake.exe''' during exe construction. 64-bit installs require the '''amd64\nmake.exe''' file - paradoxically even if your machine's chipset is Intel, a minor Microsoft variation. 
Typical mapped configurations just below, but again each install/version# may vary: 
'''U''' =     '''C:\Program Files\Microsoft SDKs\Windows\v7.0A'''     (or v6.0A or whatever your downloaded/current version is) 
'''V''' =     '''C:\Program Files\Microsoft Visual Studio 9.0'''           (or '''C:\Program Files (x86)\Microsoft Studio 9.0''' for 64-bit installs, again look for nmake.exe in a subfolder) 
As a '''check''' to make sure the '''subst''' commands worked, there should now be '''2 new drive letters visible in Windows Explorer, in the leftmost window for virtual drives/mapped folders - U and V'''. ''To avoid having to reboot'' at present, just '''open'''(not edit but run) '''AutoExec.bat AFTER''' making sure it is 100% correctly configured. Having a correctly configured AutoExec.bat file will ensure not having to manually link drives U and V each time the NARS2000.exe is built-rebuilt.
<hr width="40%">
If you install NARS project tools in other folders, make appropriate changes to the above mappings.

'''Lastly don't forget:''' To append three folders: '''C:\cygwin64\bin''' , '''V:\Common7\IDE''' and '''C:\PHP''' to your '''Path''' variable '''PATH=%PATH%;C:\cygwin64\bin;V:\Common7\IDE;C:\PHP''' or see '''Control Panel''' search for '''Path''', then '''Edit''' System Environment Variables for your account, system variable named '''Path'''; append to that '''Path''' variable   ''';C:\cygwin64\bin;V:\Common7\IDE;C:\PHP'''   - (three additional paths, semicolon separated) so Visual C's '''Make''' plus '''Compiler''' can find DLLs, exe's and Tools you have so diligently downloaded, then installed.

==Pre First Compile and Localization Notes==

Make/Compile local Environment Variable '''%NARSROOT%''' is presently set using file '''C:\NARS2000\trunk\wcustomize.bat'''. This bat file is called by other major trigger-compile bat files such as mk32.bat, mk64.bat, w32.bat and w64.bat - which oversee-initiate compilation. The %NARSROOT% environment variable is important in indicating where Make/Compilation will occur. Before first locally compiling NARS2000, you likely need to manually edit (using Notepad or a local text file editor) file '''trunk\wcustomize.bat''' and make sure the following are initially correct per your 'local PC NARS installation' i.e. within wcustomize.bat: 
'''Set NARSROOT=C:\NARS2000^\'''       (Note: '''No %''' symbols are needed in set/specification rows in wcustomize.bat, e.g. replace 'R:\NARS2000' to 'C:\NARS2000' as shown at left) 
'''Set CS_DIR=C:\DoctorDumpSDK^\'''     (again R:\ was changed to C:\) 
The additional hat(^) symbol in the above bat commands is needed for directory/folder recombination purposes, essentially sub-directory parse-point identification and or recombination point, where NARS may use subdirectories/parsing.

'''Prior''' to using '''Visual Studio''' and its '''IDE'''(integrated developer's environment) for NARS Building/Compilation purposes a first time, and to help ensure the proper installation of NARS source code - it is very helpful/necessary to open a CMD.EXE window using <big>'''Windows Start''', '''CMD.EXE'''</big>. This will open up a small CMD window. While <big>inside the opened CMD.EXE window</big>, navigate to your local C:\NARS2000\trunk folder, using <big>'''cd C:\NARS2000\trunk'''</big> where cd represents change directory. Now run <big>'''mk32.bat'''</big> by typing it in, to compile NARS2000's 32-bit executable. If mk32.bat is successful and if your installation is 100% correct, two identical files in separate folders will be created(built and compiled) using bat commands from inside that CMD window/session: 
'''C:\NARS2000\trunk\RET\ND32\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND32\NARS2000.exe''' 
If that 32-bit NARS make/build was successful, then from the same CMD.EXE window, type <big>'''mk64.bat'''</big>. This should likewise compile locally the '''64-bit''' NARS Executable, with again two resulting '''exe output files:''' 
'''C:\NARS2000\trunk\RET\ND64\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND64\NARS2000.exe'''

Successfully completing mk32.bat and mk64.bat along with presence of their respective '''NARS2000.exe''' output files generally confirm successful installation of NARS source code, as well as correct installation for several associated tandem utility tools re compiling NARS2000.exe on your server, PC, notebook or tablet computer.

==Building The Executable==

Congratulations, if you've successfully arrived at this section, your resume now includes such useful terms as software installation wizard and relentless software engineering candidate. You are part of an elite group - the few, the proud, NARS geek marines; also known as tomorrow's APL-symbol-set event-horizon squad. You've managed to easily or otherwise cross several potentially deep programming ravines in the process.

At this point you should be ready to build the executable, again - this time however from inside Visual Studio's IDE(integrated developer's environment). There are two general ways to build NARS executable. Method one: Involves the time-honored command-line batch file compile mode using files mk32.bat or mk64.bat - as you should have previously discovered in the section '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' while using Windows CMD.EXE.

Method two: Involves again first opening a (Windows Start button) '''CMD.EXE''' window and running '''w32.bat start''' (all one command) or '''w64.bat start'''. Immediately or shortly, you should see Visual Studio 2013's program visualize, load and run - with either the 32-bit or 64-bit NARS2000 project/program loaded. After Visual Studio 2013 finishes loading - simply click Build. Full use of Visual Studio 2013's IDE (integrated developer's environment) should now be available for you to experiment with, develop code on, debug and customize APL as you may choose. Your first time through with running '''w32.bat start''' and '''w64.bat start''':
* There is usually a Visual Studio '''One Way Migration''' message which displays. This is normal, TBE(to be expected), and yes you DO at that point want to migrate the NARS2000 project to Visual Studio 2013. There are usually roughly 20 migration warnings which also show up in an Internet Browser page re the Migration Report - again, all normally to be expected. However, there should be '''zero errors''' in the migration report.
* If all went satisfactorily well with the Migration, you should be able to select/choose/Click '''Build Solution''' under Build in VS2013's IDE to fully compile NARS2000 executable. After Build, there should likewise be zero errors.

Special note regarding '''w32.bat start''' and '''w64.bat start''' while in Visual Studio's IDE for the NARS2000 project:
When switching between 32 and 64-bit versions, i.e. w32.bat start '''versus''' w64.bat start: There is a '''Property''' adjustment required when using Visual Studio's IDE. After Visual Studio opens up and in the Solution Explorer window (usually on the upper right hand side of your screen) click on "Solution 'nars2000' (1 project)." This should then show a Properties Window just below it. Look for a line which reads: '''Active config'''. If you ran w32.bat start then Active config should have a value of '''Debug32|Win32'''. If you ran w64.bat start then Active config should have a value of '''Debug64|Win32'''.

== NARS Systems Developer Suggested Knowledge Prequisites ==

For a strongly recommended set of knowledge prerequisites - in order to effectively understand, maintain or improve NARS functionality - please see '''[[NARS System Developer Suggested Knowledge Prerequisites|NARS System Developer Suggested Knowledge Prerequisites]]'''.

==Developer Experiments with NARS Source Code==

This section is for Developers who have successfully downloaded NARS source code and want to Experiment with it, or further develop NARS APL Interpreter's source code.

For development and debugging purposes: You as APL Interpreter developer normally want to want to first write new source code/model using the 32-bit version of NARS2000 (w32.bat start). This is because the 32-bit version is easier to debug than the 64-bit version; error messages can be less complex. Migrating '''correct source code''' forward from the 32-bit version to the 64-bit version is also easier than a reverse migration.

You will also at some point still need to be synched-with or later synch-back-to NARS online source code - i.e. after experimenting/changing local PC source code. This is equivalent to a ChemLab 101 at home/home-office and cleaning up all experiments at the end of the chemistry class, except as it applies to software developers, NARS software developers, and or those inclined to experiment safely.

Here is where Tortoise SVN provides excellent and time-tested source-code clean-up tools for your local PC, including '''Resolve, Revert, Clean up, and Undo changes'''. Pull up these TortoiseSVN utilities by navigating Windows File Explorer to directory C:\NARS2000. If you successfully previously downloaded and Installed TortoiseSVN and NARS2000 source code, as outlined earlier/above, you may right click on say the \trunk subfolder in C:\NARS2000. A mouse right-click on \trunk should show an option labeled TortoiseSVN. Further choosing/selecting TortoiseSVN should then reveal multiple clean up options - Resolve, Revert, Clean up and Undo changes. '''TortoiseSVN Documentation on:''' [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-cleanup.html Clean up.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-revert.html Undo Changes.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-conflicts.html Resolving Conflicts.] 

At least one method to safely synch-back-to NARS is to:
# Select '''TortoiseSVN''' after right-clicking on the trunk folder
# Select '''Revert''', click '''OK''', let it run.
# Select '''Clean up''', check '''Refresh shell overlays''', click '''OK''', let it run.
Per TortoiseSVN there should again be green check marks appearing on your trunk folder as well as your msieve folder.

For revision tracking and long-term software program maintenance purposes: '''Keep track of which files (file names) you personally modify, including a brief purpose''' for that edit. You will need to this information later for Release Notes purposes (see folder C:\NARS2000\trunk\ReleaseNotes for best-practice-examples of developer note-taking) and if you later synch to a new online NARS version, you may have to carry-forward your edit changes into a newly downloaded set of NARS source code files which may or may not reflect your prior local computer edit changes.

==Periodic NARS Updates==

Incremental Update - Method 1: 
Periodically, NARS APL interpreter developers should ensure changes done by other developers get incorporated into their local machine's source code working copy. This is the process of integrating/downloading changes from NARS SourceForge server '''to''' your local copy. Updating may be performed on single files, a set of selected files, or recursively on entire directory hierarchies. To update, select the files and/or '''directories''' you want (usually \trunk and or \msieve), right click and select '''TortoiseSVN → Update''' in the explorer context menu for that trunk or msieve folder. A window will pop up displaying the progress of the update as it runs. Changes done by other developers will be merged into your local files, '''keeping''' any changes you may have done to the same files - if you did not want to keep your local changes but do want to keep the downloaded changes, select TortoiseSVN and Revert '''prior''' to running TortoiseSVN Update. NARS repository at SourceForge is '''not''' affected by an update to your local copy. [http://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-dug-update.html Update Your Working Copy With Changes From Others]

Total Source Code Replacement - Method 2: 
For example from version r1325 to say version r1364 (note a significant revision/datetime gap between 1325 and 1364, hypothetically), whatever NARS latest revision number is. Total code replacement may be preferred over incremental updating when major structural changes or significant source code changes are newly in situ. 
Total Replacement Process: Visually scan NARS source code page at http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ and review the top 25 to 40 file entries or so, while mentally keeping track of the '''highest revision number found'''(e.g. r1379). If after your last/earlier TortoiseSVN Update, your local version number is lower than the latest revision number visually found online, then perform the following to update to the most recent NARS revision:
# Rename your existing NARS folder to something approximating C:\NARS2000_old_rev
# Create an entirely new C:\NARS2000 folder
# '''Copy all folders and files at the top level''' from C:\NARS2000_old_rev folder into C:\NARS2000 '''EXCEPT \trunk and \msieve subfolders (and their contents)'''. The \trunk and \msieve folders will shortly be downloaded from SourceForge.
# Create '''new empty folders called \trunk and \msieve''' in the new C:\NARS2000 folder.
# Revisit the section above called '''[[#Check_Out_The_Source_Code|Check Out The Source Code]]''' to again checkout/download to the absolute latest NARS version number, for both \trunk and \msieve folders.
# Also revisit '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' and text edit file \trunk\wcustomize.bat to localize the new version.
# Folder C:\NARS2000_old_rev may be '''Recycled''' after you are done copying non-trunk and non-msieve files/folders from it into your new C:\NARS2000 folder. If disk space is not restrictive and for 100% safety purposes, keep your prior folder available until after successfully '''Building/Compiling''' the newly downloaded 32-bit and 64-bit versions, and making sure you did not have any local personal changes now potentially being recycled.

Symbol Zilde

2016-03-12T01:13:26Z

Robert Wallick: expanded meaning, frame of ref. example

__NOTOC__
<h2> {zilde} — Represents an '''empty numeric vector''' or ''zero plus tilde'' (hence zilde) — Keystroke Alt + Shift + } — Character ⎕UCS '⍬' = 9068</h2>
==Usage==
<apll>      ⌊/⍬ 
∞</apll> 
<apll>      ⌈/⍬ 
¯∞</apll> 

Symbolically zero or '''<apll>0</apll>''' represents '''number''' while tilde or '''<apll>{tilde}</apll>''' represents '''not.''' Together the overstrike zilde symbol or '''<apll>⍬</apll>''' means ''not a number'', i.e. empty numeric vector. APL frequently uses overstrike characters in '''dual-combined meaning,''' thus '''<apll>{quotequad}</apll>''' which is '''<apll>{quad}</apll>''' or prompt and the single quote symbol yielding ''prompt for string'' or character input '''versus''' '''<apll>{quad}</apll>''' or prompt for numeric input. 
==Example==
The above examples for infinity and negative infinity correctly run in NARS2000. In '''theory ONLY - {zilde}''' would be hypothetically equivalent to <apll>⍳0</apll> or <apll>0⍴N</apll> (where N is any number) since zilde or {zilde} represents an empty numeric vector.
==See Also==
[[Infinity|Infinity <apll>∞</apll>]]

{{Language Toolbar}}
[[Category:Mouse Group 12]]

Symbol Zilde

2016-03-11T21:10:36Z

Robert Wallick: Initial definition

__NOTOC__
<h2> {zilde} — Represents an '''empty numeric vector''' or ''zero plus tilde'' (hence zilde) — Keystroke Alt + Shift + } — Character ⎕UCS '⍬' = 9068</h2>
==Usage==
<apll>      ⌊/⍬ 
∞</apll> 
<apll>      ⌈/⍬ 
¯∞</apll> 
==Example==
The above examples for infinity and negative infinity correctly run in NARS2000. In '''theory ONLY - {zilde}''' would be hypothetically equivalent to <apll>⍳0</apll> or <apll>0⍴N</apll> (where N is any number) since zilde or {zilde} represents an empty numeric vector.
==See Also==
[[Infinity|Infinity <apll>∞</apll>]]

{{Language Toolbar}}
[[Category:Mouse Group 12]]

APL Font

2016-02-20T16:16:38Z

Robert Wallick: /* Default Keyboard Layout */ added tilde Alt-t

==Default Font==

The default APL font for NARS2000 (its APL Interpreter session, function editing, screen display and printing purposes) and this wiki is '''SImPL medium'''(Unicode based), '''SImPL''', or '''APL385 Unicode'''.

If the APL characters in the articles don't display correctly, you may obtain a copy of the '''SImPL medium''' font by downloading the current [http://www.nars2000.org/download/Download.html NARS2000 binary], or the '''SImPL''' font from [http://archive.vector.org.uk/resource/simpl02.zip here], or the '''APL385 Unicode''' font from [http://archive.vector.org.uk/resource/apl385.ttf here]. Normally font and file '''SimPL-Medium.ttf''' may be found in your downloaded NARS2000 program folder, e.g. '''C:\Program Files (x86)\NARS2000 (32-bit program)''' and or '''C:\Program Files\NARS2000 (64-bit version)'''.

If they still don't display correctly, [http://www.getfirefox.com/ download] FireFox.

==Default Keyboard Layout==

NARS2000 default APL keyboard layout, based on the SImPL medium font, is found '''[http://www.sudleyplace.com/APL/Keyboard.ahtml here]''', on SudleyPlace.com. Printing the keyboard layout and keeping it in front of you while using NARS2000 - provides a handy reference. Just as typists eventually memorize the QWERTY (oe AZERTY, etc.) keyboard layout, most APL'ers quickly memorize APL keyboard layouts. A printed keyboard reference is good to keep however, if only for some of the lesser used APL symbols. Several frequently used APL symbols are very easily keyboard-memorized: '''∊ (epsilon = Alt-e), ⍴ (rho = Alt-r), ∼ (tilde = Alt-t) and ⍳ (iota = Alt-i)''' since the beginning letter of the symbol is same-placed as its qwerty letter equivalent in the alphabet. Also, all of the APL symbols may be found (and copied to the current session or function being edited) from the Language Bar at the top of the APL session window. Cross ref. wiki page [[Keyboard|Keyboard and Language bar]].

==Font Issues==
Even if you have an APL font installed, that may not be the end of the story. Each font designer decides what glyphs to display and for which characters. Also, some implementations of supposedly Unicode fonts don't always display the same glyphs in the same places or in the same way. The '''SimPL Medium''' font, which comes with NARS2000, will display some characters with different glyphs than are displayed by the font '''APL385 Unicode'''. For example, these are the underlined letters A to Z, which are valid identifiers in APL: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z. Now, to display these characters in ''APL385 Unicode'', the characters use code positions 9398 through 9423, or 0x24B6 through 0x24CF, which show up as Ⓐ Ⓑ Ⓒ Ⓓ Ⓔ Ⓕ Ⓖ Ⓗ Ⓘ Ⓙ Ⓚ Ⓛ Ⓜ Ⓝ Ⓞ Ⓟ Ⓠ Ⓡ Ⓢ Ⓣ Ⓤ Ⓥ Ⓦ Ⓧ Ⓨ Ⓩ, which, while not the same, is very close. When copying underlined APL characters to the clipboard, you may convert them to lowercase by first setting the user preference "Underbar alphabet converted to lowercase".

The standard '''Arial''' font doesn't even have a built-in set of underlined characters, nor does SimPL. (Yet note some glyphs, as shown below, that are used by NARS2000, are not present in APL385.)

Also, the settings for Unicode for APL symbols, which are listed as being 0x2300 - 0x23F3, do not necessarily appear - or appear the same - in all APL fonts.

==Extra APL Glyphs==

While any Unicode APL font will display all of the standard APL glyphs, NARS2000 uses (or has plans to use) some extra glyphs not found in all Unicode APL fonts such as

{| border="0" summary="" cellspacing="0"
! style="border-bottom: solid black 1px;" |Name
! style="border-bottom: solid black 1px;" |Symbol
! style="border-bottom: solid black 1px;" |Unicode Code Point
! style="border-bottom: solid black 1px;" |Keystroke
! style="border-bottom: solid black 1px;" |Description
|-
||Section
| align="center" |<apll>§</apll>
| align="center" |&ensp;167 or U+00A7
| align="center" |'''Alt-S'''
| [[Multisets#Missing_Function|Multiset Symmetric Difference]]
|-
||Pi
| align="center"|<apll>π</apll>
| align="center"|&ensp;960 or U+03C0
| align="center"|'''Alt-p'''
|| [[Primes|Prime Decomposition and Number-theoretic]]
|-
||Root
| align="center"|<apll>√</apll>
| align="center"|8730 or U+221A
| align="center"|'''Alt-R'''
|| [[Root|Square Root and Nth Root]]
|-
||Infinity
| align="center"|<apll>∞</apll>
| align="center"|8734 or U+221E
| align="center"|'''Alt-f'''
|| [[Infinity]]
|-
|| Mismatch
| align="center"|<apll>≢</apll>
| align="center"|8802 or U+2262
| align="center"|'''Alt-@'''
|| [[Mismatch]]
|-
||Left-shoe-underbar
| align="center"|<apll>⊆</apll>
| align="center"|8838 or U+2286
| align="center"|'''Alt-Z'''
|| [[Sets|Subset of]]
|-
|| Right-shoe-underbar
| align="center"|<apll>⊇</apll>
| align="center"|8839 or U+2287
| align="center"|'''Alt-X'''
|| [[Sets|Superset of]]
|-
||Circle-middle-dot
| align="center"|<apll>⊙</apll>
| align="center"|8857 or U+2299
| align="center"|'''Alt-?'''
|| [[Null|Null operator]]
|-
||Quad-colon
| align="center"|<apll>⍠</apll>
| align="center"|9056 or U+2360
| align="center"|'''Alt-_'''
|| [[Variant|Variant operator]]
|-
||Dieresis-downtack
| align="center"|<apll>⍡</apll>
| align="center"|9057 or U+2361
| align="center"|'''Alt-N'''
|| [[Convolution|Convolution operator]]
|-
||Dieresis-del
| align="center"|<apll>⍢</apll>
| align="center"|9058 or U+2362
| align="center"|'''Alt-G'''
|| [[Dual|Dual operator]]&dagger;
|-
||Dieresis-star
| align="center"|<apll>⍣</apll>
| align="center"|9059 or U+2363
| align="center"|'''Alt-P'''
|| [[Power|Power operator]]&dagger;
|-
||Dieresis-jot
| align="center"|<apll>⍤</apll>
| align="center"|9060 or U+2364
| align="center"|'''Alt-J'''
|| [[Rank|Rank operator]]
|-
||Dieresis-circle
| align="center"|<apll>⍥</apll>
| align="center"|9061 or U+2365
| align="center"|'''Alt-O'''
|| [[Composition|Composition operator]]
|-
||Down-shoe-stile
| align="center"|<apll>⍦</apll>
| align="center"|9062 or U+2366
| align="center"|'''Alt-m'''
|| [[Multisets|Multiset operator]]
|-
||Dieresis-tilde
| align="center"|<apll>⍨</apll>
| align="center"|9064 or U+2368
| align="center"|'''Alt-T'''
|| [[Commute|Commute operator]]
|-
|| Del-tilde
| align="center"|<apll>⍫</apll>
| align="center"|9067 or U+236B
| align="center"|'''Alt-k'''
|| [[Commutator|Commutator operator]]&dagger;
|-
|| Zilde
| align="center"|<apll>⍬</apll>
| align="center"|9068 or U+236C
| align="center"|'''Alt-}'''
|| Empty simple numeric vector
|-
|| Stile-tilde
| align="center"|<apll>⍭</apll>
| align="center"|9069 or U+236D
| align="center"|'''Alt-M'''
|| [[Partition|Partition operator]]&dagger;
|}

&dagger; = Not currently implemented.

All of the above glyphs may be found in '''SImPL medium''', all but the Infinity symbol in '''SImPL''', and all but the Null operator in '''APL385 Unicode'''.

APL Font

2016-02-17T23:53:01Z

Robert Wallick: added cross ref to keyboard wiki page

==Default Font==

The default APL font for NARS (its APL Interpreter session, function editing, screen display and printing purposes) and this wiki is '''SImPL medium'''(Unicode based), '''SImPL''', or '''APL385 Unicode'''.

If the APL characters in the articles don't display correctly, you may obtain a copy of the '''SImPL medium''' font by downloading the current [http://www.nars2000.org/download/Download.html NARS2000 binary], or the '''SImPL''' font from [http://archive.vector.org.uk/resource/simpl02.zip here], or the '''APL385 Unicode''' font from [http://archive.vector.org.uk/resource/apl385.ttf here]. Normally font and file '''SimPL-Medium.ttf''' may be found in your downloaded NARS2000 program folder, e.g. '''C:\Program Files (x86)\NARS2000 (32-bit program)''' and or '''C:\Program Files\NARS2000 (64-bit version)'''.

If they still don't display correctly, [http://www.getfirefox.com/ download] FireFox.

==Default Keyboard Layout==

NARS default APL keyboard layout, based on the SImPL medium font, is found here '''[http://www.sudleyplace.com/APL/Keyboard.ahtml here]''', on SudleyPlace.com. Printing the keyboard layout and keeping it in front of you while using NARS - provides a handy reference. Just as typists eventually memorize the QWERTY keyboard layout, most APL'ers quickly memorize APL keyboard layouts. A printed keyboard reference is good to keep however, if only for some of the lesser used APL symbols. Several frequently used APL symbols are very easily keyboard-memorized: '''∊ (epsilon = Alt-e), ⍴ (rho = Alt-r) and ⍳ (iota = Alt-i)''' since the beginning letter of the symbol is same-placed as its qwerty letter equivalent in the alphabet. Cross ref. wiki page [[Keyboard|keyboard]].

==Font Issues==
Even if you have an APL font installed, that may not be the end of the story. Each font designer decides what glyphs to display and for which characters. Also, some implementations of supposedly Unicode fonts don't always display the same glyphs in the same places or in the same way. The '''SimPL Medium''' font, which comes with NARS2000, will display some characters with different glyphs than are displayed by the font '''APL385 Unicode'''. For example, these are the underlined letters A to Z, which are valid identifiers in APL: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z. Now, to display these characters in ''APL385 Unicode'', the characters use code positions 9398 through 9423, or 0x24B6 through 0x24CF, which show up as Ⓐ Ⓑ Ⓒ Ⓓ Ⓔ Ⓕ Ⓖ Ⓗ Ⓘ Ⓙ Ⓚ Ⓛ Ⓜ Ⓝ Ⓞ Ⓟ Ⓠ Ⓡ Ⓢ Ⓣ Ⓤ Ⓥ Ⓦ Ⓧ Ⓨ Ⓩ, which, while not the same, is very close. When copying underlined APL characters to the clipboard, you may convert them to lowercase by first setting the user preference "Underbar alphabet converted to lowercase".

The standard '''Arial''' font doesn't even have a built-in set of underlined characters, nor does SimPL. (Yet note some glyphs, as shown below, that are used by NARS2000, are not present in APL385.)

Also, the settings for Unicode for APL symbols, which are listed as being 0x2300 - 0x23F3, do not necessarily appear - or appear the same - in all APL fonts.

==Extra APL Glyphs==

While any Unicode APL font will display all of the standard APL glyphs, NARS2000 uses (or has plans to use) some extra glyphs not found in all Unicode APL fonts such as

{| border="0" summary="" cellspacing="0"
! style="border-bottom: solid black 1px;" |Name
! style="border-bottom: solid black 1px;" |Symbol
! style="border-bottom: solid black 1px;" |Unicode Code Point
! style="border-bottom: solid black 1px;" |Keystroke
! style="border-bottom: solid black 1px;" |Description
|-
||Section
| align="center" |<apll>§</apll>
| align="center" |&ensp;167 or U+00A7
| align="center" |'''Alt-S'''
| [[Multisets#Missing_Function|Multiset Symmetric Difference]]
|-
||Pi
| align="center"|<apll>π</apll>
| align="center"|&ensp;960 or U+03C0
| align="center"|'''Alt-p'''
|| [[Primes|Prime Decomposition and Number-theoretic]]
|-
||Root
| align="center"|<apll>√</apll>
| align="center"|8730 or U+221A
| align="center"|'''Alt-R'''
|| [[Root|Square Root and Nth Root]]
|-
||Infinity
| align="center"|<apll>∞</apll>
| align="center"|8734 or U+221E
| align="center"|'''Alt-f'''
|| [[Infinity]]
|-
|| Mismatch
| align="center"|<apll>≢</apll>
| align="center"|8802 or U+2262
| align="center"|'''Alt-@'''
|| [[Mismatch]]
|-
||Left-shoe-underbar
| align="center"|<apll>⊆</apll>
| align="center"|8838 or U+2286
| align="center"|'''Alt-Z'''
|| [[Sets|Subset of]]
|-
|| Right-shoe-underbar
| align="center"|<apll>⊇</apll>
| align="center"|8839 or U+2287
| align="center"|'''Alt-X'''
|| [[Sets|Superset of]]
|-
||Circle-middle-dot
| align="center"|<apll>⊙</apll>
| align="center"|8857 or U+2299
| align="center"|'''Alt-?'''
|| [[Null|Null operator]]
|-
||Quad-colon
| align="center"|<apll>⍠</apll>
| align="center"|9056 or U+2360
| align="center"|'''Alt-_'''
|| [[Variant|Variant operator]]
|-
||Dieresis-downtack
| align="center"|<apll>⍡</apll>
| align="center"|9057 or U+2361
| align="center"|'''Alt-N'''
|| [[Convolution|Convolution operator]]
|-
||Dieresis-del
| align="center"|<apll>⍢</apll>
| align="center"|9058 or U+2362
| align="center"|'''Alt-G'''
|| [[Dual|Dual operator]]&dagger;
|-
||Dieresis-star
| align="center"|<apll>⍣</apll>
| align="center"|9059 or U+2363
| align="center"|'''Alt-P'''
|| [[Power|Power operator]]&dagger;
|-
||Dieresis-jot
| align="center"|<apll>⍤</apll>
| align="center"|9060 or U+2364
| align="center"|'''Alt-J'''
|| [[Rank|Rank operator]]
|-
||Dieresis-circle
| align="center"|<apll>⍥</apll>
| align="center"|9061 or U+2365
| align="center"|'''Alt-O'''
|| [[Composition|Composition operator]]
|-
||Down-shoe-stile
| align="center"|<apll>⍦</apll>
| align="center"|9062 or U+2366
| align="center"|'''Alt-m'''
|| [[Multisets|Multiset operator]]
|-
||Dieresis-tilde
| align="center"|<apll>⍨</apll>
| align="center"|9064 or U+2368
| align="center"|'''Alt-T'''
|| [[Commute|Commute operator]]
|-
|| Del-tilde
| align="center"|<apll>⍫</apll>
| align="center"|9067 or U+236B
| align="center"|'''Alt-k'''
|| [[Commutator|Commutator operator]]&dagger;
|-
|| Zilde
| align="center"|<apll>⍬</apll>
| align="center"|9068 or U+236C
| align="center"|'''Alt-}'''
|| Empty simple numeric vector
|-
|| Stile-tilde
| align="center"|<apll>⍭</apll>
| align="center"|9069 or U+236D
| align="center"|'''Alt-M'''
|| [[Partition|Partition operator]]&dagger;
|}

&dagger; = Not currently implemented.

All of the above glyphs may be found in '''SImPL medium''', all but the Infinity symbol in '''SImPL''', and all but the Null operator in '''APL385 Unicode'''.

Keyboard

2016-02-17T23:49:35Z

Robert Wallick: added link to APL Font wiki page

These are the keyboard positions used by NARS2000. Hover over a link to see the name of the symbol, click on the link to go to the page defining the symbol. Also see [http://www.sudleyplace.com/APL/Keyboard.ahtml keyboard] and '''[[APL_Font|APL Font default keyboard]]'''.

{| class="wikitable" style="font-size: 200%;" width="80%" align="center"
|-
||ALT+Shift
||[[Symbol Comma Bar|⍪]]
||[[Symbol Match|≡]]
||[[Symbol Not Match|≢]]
||[[Symbol Grade Down|⍒]]
||[[Symbol Grade Up|⍋]]
||[[Symbol Rotate|⌽]]
||[[Symbol Circle Slope|⍉]]
||[[Symbol Circle Bar|⊖]]
||[[Symbol Log|⍟]]
||[[Symbol Nor|⍱]]
||[[Symbol Nand|⍲]]
||[[Symbol Factorial|!]]
||[[Symbol Domino|⌹]]
|-
||ALT
||[[Diamond|⋄]]
||[[Symbol Dieresis|¨]]
||[[Symbol Overbar|¯]]
||[[Symbol Less Than|<]]
||[[Symbol Less Than or Equal|≤]]
||[[Symbol Equal|=]]
||[[Symbol Greater Than or Equal|≥]]
||[[Symbol Greater Than|>]]
||[[Symbol Not Equal|≠]]
||[[Symbol Down Caret|∨]]
||[[Symbol And|∧]]
||[[Symbol Times|×]]
||[[Symbol Divide|÷]]
|-
||Shift
||[[Symbol Not|~]]
||[[Symbol Factorial|!]]
||@
||#
||$
||%
||^
||&
||*
||[[Symbol Parenthesis|(]]
||[[Symbol Parenthesis|)]]
||[[Symbol Underbar|_]]
||[[Symbol Plus|+]]
|-
||Key
||`
||1
||2
||3
||4
||5
||6
||7
||8
||9
||0
||[[Symbol Minus|-]]
||[[Symbol Equal|=]]
|| (backspace)
|-
|colspan=15|
|-
||ALT+Shift
|colspan=3|
||[[Symbol Find|⍷]]
||[[Symbol Root|√]]
||[[Symbol Commute|⍨]]
|colspan=2|
||[[Symbol Iota Underbar|⍸]]
||[[⍥]]
||[[⍣]]
||[[Symbol Quote Quad|⍞]]
||[[Symbol Zilde|⍬]]
||[[Symbol Lev|⊣]]
|-
||ALT
||
||[[Symbol Query|?]]
||[[Special Symbols|⍵]]
||[[Symbol Epsilon|∊]]
||[[Symbol Rho|⍴]]
||[[Symbol Not|∼]]
||[[Symbol Take|↑]]
||[[Symbol Drop|↓]]
||[[Symbol Iota|⍳]]
||[[Symbol Jot|○]]
||[[Symbol Pi|π]]
||[[Symbol Assign|←]]
||[[Symbol Goto|→]]
||[[Symbol Dex|⊢]]
|-
||SHIFT
||
||Q
||W
||E
||R
||T
||Y
||U
||I
||O
||P
||{
||}
||[[Symbol Mod||]]
|-
||Key
||(Tab)
||q
||w
||e
||r
||t
||y
||u
||i
||o
||p
||[[Symbol Brace|[]]
||[[Symbol Brace|]]]
||[[Symbol Slope|\]]
|-
|colspan=15|
|-
||ALT+Shift
|Colspan=2|
||[[Symbol Section|§]]
|colspan=2|
||[[Symbol Dieresis Del|⍢]]
||[[Special Symbols|⍙]]
||[[Symbol Dieresis Jot|⍤]]
||
||[[Symbol Squad|⌷]]
|-
||ALT
||
||[[Special Symbols|⍺]]
||[[Symbol Ceiling|⌈]]
||[[Symbol Floor|⌊]]
||[[Symbol Infinity|∞]]
||[[Del|∇]]
||[[Special Symbols|∆]]
||[[Symbol Jot|∘]]
||[[Symbol Quote|']]
||[[Symbol Quad|⎕]]
||[[Symbol Execute|⍎]]
||[[Symbol Format|⍕]]
|-
||Shift
||
||A
||S
||D
||F
||G
||H
||J
||K
||L
||[[Symbol Colon|:]]
||"
|-
||Key
||(Caps Lock)
||a
||s
||d
||f
||g
||h
||j
||k
||l
||[[Symbol Semicolon|;]]
||[[Symbol Quote|']]
|colspan=2|(enter)
|-
|colspan=15|
|-
||ALT+Shift
||
||[[Symbol Left Shoe Underbar|⊆]]
||[[Symbol Right Shoe Underbar|⊇]]
|colspan=3|
||[[Symbol Dieresis Down Tack|⍡]]
||[[Symbol Stile Tilde|⍭]]
|colspan=2|
||[[Symbol Circle Middle Dot|⊙]]
|-
||ALT
||
||[[Symbol Left Shoe|⊂]]
||[[Symbol Right Shoe|⊃]]
||[[Symbol Up Shoe|∩]]
||[[Symbol Down Shoe|∪]]
||[[Symbol Base Value|⊥]]
||[[Symbol Represent|⊤]]
||[[Symbol Multiset|⍦]]
||[[Lamp|⍝]]
||[[Symbol Slope Bar|⍀]]
||[[Symbol Slash Bar|⌿]]
|-
||Shift
||
||Z
||X
||C
||V
||B
||N
||M
||[[Symbol Less Than|<]]
||[[Symbol Greater Than|>]]
||[[Symbol Query|?]]
|-
||Key
|(Shift)
||z
||x
||c
||v
||b
||n
||m
||[[Symbol Comma|,]]
||[[Symbol Dot|.]]
||[[Symbol Slash|/]]
||(Shift)
|}

{{Article footer}}

APL Font

2016-02-17T23:43:52Z

Robert Wallick: Added default keyboard layout link

==Default Font==

The default APL font for NARS (its APL Interpreter session, function editing, screen display and printing purposes) and this wiki is '''SImPL medium'''(Unicode based), '''SImPL''', or '''APL385 Unicode'''.

If the APL characters in the articles don't display correctly, you may obtain a copy of the '''SImPL medium''' font by downloading the current [http://www.nars2000.org/download/Download.html NARS2000 binary], or the '''SImPL''' font from [http://archive.vector.org.uk/resource/simpl02.zip here], or the '''APL385 Unicode''' font from [http://archive.vector.org.uk/resource/apl385.ttf here]. Normally font and file '''SimPL-Medium.ttf''' may be found in your downloaded NARS2000 program folder, e.g. '''C:\Program Files (x86)\NARS2000 (32-bit program)''' and or '''C:\Program Files\NARS2000 (64-bit version)'''.

If they still don't display correctly, [http://www.getfirefox.com/ download] FireFox.

==Default Keyboard Layout==

NARS default APL keyboard layout, based on the SImPL medium font, is found here '''[http://www.sudleyplace.com/APL/Keyboard.ahtml here]''', on SudleyPlace.com. Printing the keyboard layout and keeping it in front of you while using NARS - provides a handy reference. Just as typists eventually memorize the QWERTY keyboard layout, most APL'ers quickly memorize APL keyboard layouts. A printed keyboard reference is good to keep however, if only for some of the lesser used APL symbols. Several frequently used APL symbols are very easily keyboard-memorized: '''∊ (epsilon = Alt-e), ⍴ (rho = Alt-r) and ⍳ (iota = Alt-i)''' since the beginning letter of the symbol is same-placed as its qwerty letter equivalent in the alphabet.

==Font Issues==
Even if you have an APL font installed, that may not be the end of the story. Each font designer decides what glyphs to display and for which characters. Also, some implementations of supposedly Unicode fonts don't always display the same glyphs in the same places or in the same way. The '''SimPL Medium''' font, which comes with NARS2000, will display some characters with different glyphs than are displayed by the font '''APL385 Unicode'''. For example, these are the underlined letters A to Z, which are valid identifiers in APL: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z. Now, to display these characters in ''APL385 Unicode'', the characters use code positions 9398 through 9423, or 0x24B6 through 0x24CF, which show up as Ⓐ Ⓑ Ⓒ Ⓓ Ⓔ Ⓕ Ⓖ Ⓗ Ⓘ Ⓙ Ⓚ Ⓛ Ⓜ Ⓝ Ⓞ Ⓟ Ⓠ Ⓡ Ⓢ Ⓣ Ⓤ Ⓥ Ⓦ Ⓧ Ⓨ Ⓩ, which, while not the same, is very close. When copying underlined APL characters to the clipboard, you may convert them to lowercase by first setting the user preference "Underbar alphabet converted to lowercase".

The standard '''Arial''' font doesn't even have a built-in set of underlined characters, nor does SimPL. (Yet note some glyphs, as shown below, that are used by NARS2000, are not present in APL385.)

Also, the settings for Unicode for APL symbols, which are listed as being 0x2300 - 0x23F3, do not necessarily appear - or appear the same - in all APL fonts.

==Extra APL Glyphs==

While any Unicode APL font will display all of the standard APL glyphs, NARS2000 uses (or has plans to use) some extra glyphs not found in all Unicode APL fonts such as

{| border="0" summary="" cellspacing="0"
! style="border-bottom: solid black 1px;" |Name
! style="border-bottom: solid black 1px;" |Symbol
! style="border-bottom: solid black 1px;" |Unicode Code Point
! style="border-bottom: solid black 1px;" |Keystroke
! style="border-bottom: solid black 1px;" |Description
|-
||Section
| align="center" |<apll>§</apll>
| align="center" |&ensp;167 or U+00A7
| align="center" |'''Alt-S'''
| [[Multisets#Missing_Function|Multiset Symmetric Difference]]
|-
||Pi
| align="center"|<apll>π</apll>
| align="center"|&ensp;960 or U+03C0
| align="center"|'''Alt-p'''
|| [[Primes|Prime Decomposition and Number-theoretic]]
|-
||Root
| align="center"|<apll>√</apll>
| align="center"|8730 or U+221A
| align="center"|'''Alt-R'''
|| [[Root|Square Root and Nth Root]]
|-
||Infinity
| align="center"|<apll>∞</apll>
| align="center"|8734 or U+221E
| align="center"|'''Alt-f'''
|| [[Infinity]]
|-
|| Mismatch
| align="center"|<apll>≢</apll>
| align="center"|8802 or U+2262
| align="center"|'''Alt-@'''
|| [[Mismatch]]
|-
||Left-shoe-underbar
| align="center"|<apll>⊆</apll>
| align="center"|8838 or U+2286
| align="center"|'''Alt-Z'''
|| [[Sets|Subset of]]
|-
|| Right-shoe-underbar
| align="center"|<apll>⊇</apll>
| align="center"|8839 or U+2287
| align="center"|'''Alt-X'''
|| [[Sets|Superset of]]
|-
||Circle-middle-dot
| align="center"|<apll>⊙</apll>
| align="center"|8857 or U+2299
| align="center"|'''Alt-?'''
|| [[Null|Null operator]]
|-
||Quad-colon
| align="center"|<apll>⍠</apll>
| align="center"|9056 or U+2360
| align="center"|'''Alt-_'''
|| [[Variant|Variant operator]]
|-
||Dieresis-downtack
| align="center"|<apll>⍡</apll>
| align="center"|9057 or U+2361
| align="center"|'''Alt-N'''
|| [[Convolution|Convolution operator]]
|-
||Dieresis-del
| align="center"|<apll>⍢</apll>
| align="center"|9058 or U+2362
| align="center"|'''Alt-G'''
|| [[Dual|Dual operator]]&dagger;
|-
||Dieresis-star
| align="center"|<apll>⍣</apll>
| align="center"|9059 or U+2363
| align="center"|'''Alt-P'''
|| [[Power|Power operator]]&dagger;
|-
||Dieresis-jot
| align="center"|<apll>⍤</apll>
| align="center"|9060 or U+2364
| align="center"|'''Alt-J'''
|| [[Rank|Rank operator]]
|-
||Dieresis-circle
| align="center"|<apll>⍥</apll>
| align="center"|9061 or U+2365
| align="center"|'''Alt-O'''
|| [[Composition|Composition operator]]
|-
||Down-shoe-stile
| align="center"|<apll>⍦</apll>
| align="center"|9062 or U+2366
| align="center"|'''Alt-m'''
|| [[Multisets|Multiset operator]]
|-
||Dieresis-tilde
| align="center"|<apll>⍨</apll>
| align="center"|9064 or U+2368
| align="center"|'''Alt-T'''
|| [[Commute|Commute operator]]
|-
|| Del-tilde
| align="center"|<apll>⍫</apll>
| align="center"|9067 or U+236B
| align="center"|'''Alt-k'''
|| [[Commutator|Commutator operator]]&dagger;
|-
|| Zilde
| align="center"|<apll>⍬</apll>
| align="center"|9068 or U+236C
| align="center"|'''Alt-}'''
|| Empty simple numeric vector
|-
|| Stile-tilde
| align="center"|<apll>⍭</apll>
| align="center"|9069 or U+236D
| align="center"|'''Alt-M'''
|| [[Partition|Partition operator]]&dagger;
|}

&dagger; = Not currently implemented.

All of the above glyphs may be found in '''SImPL medium''', all but the Infinity symbol in '''SImPL''', and all but the Null operator in '''APL385 Unicode'''.

Symbol Take

2016-02-13T22:25:39Z

Robert Wallick: Added examples, expanded

__NOTOC__
<h1> {take} — Take symbol — Keystroke(usually) ALT+y ; Character (⎕UCS) 8593</h1>
==Usage==
'''Dyadic function A↑B''' - where '''A''' is the number of elements to take and '''B''' is the vector or array to operate on.
Take first(A is positive) n or last(A is negative) n elements of an array.
'''Take''' and '''Rho''' share a similar property - the left argument specifies the '''size''' of the resultant array.
==Examples==

<pre>
5↑1 ⍝Take the first 5 elements, given scalar integer 1
1 0 0 0 0 ⍝Result creates a vector of 5 elements, since only a single scalar was present, 4 additional zeroes are appended to the vector.

¯4↑45 78 33 99 10 11 12 13 ⍝Take the last 4 elements, given a vector of 8 integers
10 11 12 13 ⍝APL/NARS Interpreter returns the last 4 elements, a vector.

¯5↑'abcdefghijklmnop'
lmnop ⍝Result is the last 5 elements from the alphabet sub-string(take's right argument), result is similarly a string.

A←3 4⍴⍳12 ⍝Store a 3-row by 4-column matrix of the set of integers from 1 through 12 in variable A
A ⍝Display the contents of variable A, which has 3 rows and 4 columns of consecutive integers:
1 2 3 4
5 6 7 8
9 10 11 12
2 3↑A ⍝Take just the FIRST 2 rows and 3 columns of variable A, display the requested results:
1 2 3
5 6 7

¯2 3↑A ⍝Take the LAST 2 rows and FIRST 3 columns of variable A, display the results:
5 6 7
9 10 11

4 5↑A ⍝Take 4 rows and 5 columns of variable A, ZEROES are APPENDED when left arguments exceed array sizes of a NUMERIC matrix.
1 2 3 4 0
5 6 7 8 0
9 10 11 12 0
0 0 0 0 0

¯4 ¯5↑A ⍝Take negative 4 rows and negative 5 cols of variable A. Result: ZEROES are PREFIXED onto numeric matrix A:
0 0 0 0 0
0 1 2 3 4
0 5 6 7 8
0 9 10 11 12

</pre>

==See Also==
* [[Rho]]: '''⍴''' especially '''Dyadic rho''' and it's leftmost argument

{{Language Toolbar}}
[[Category:Mouse Group 6|T]]
[[Category:Symbols|T]]

Symbol Iota

2016-02-08T19:47:12Z

Robert Wallick: added ⎕IO quad IO

__NOTOC__
<h1> {iota} — iota or index; Keystroke ALT+i ; Character (⎕UCS) 9075</h1>
==Usage==

Monadic use:
* [[Index Generator]]: <apll>⍳R</apll>

Dyadic use:
* [[Index Of]]: <apll>L⍳R</apll>

==Examples==

<pre>
⍳20 ⍝ Monadic example, generate the set of integers 1 through 20
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

'ABCDEFG' ⍳ 'BG' ⍝ Dyadic example, find/lookup the letters B and G in the string 'ABCDEFG' (pos 1 = A, pos 2 = B, ... pos 7 = G)
2 7 ⍝ Results found at positions 2 and 7 of string 'ABCDEFG'
</pre>
==See Also==
* [[Index Generator]]: <apll>⍳R</apll>
* [[Index Of]]: <apll>L⍳R</apll>
* [[System_Variable_IO]] <apll>⎕IO</apll> or quad IO, Index Origin
* [[Array Lookup]]: <apll>L⍸R</apll>
* [[Indexing]]: <apll>R[L]</apll>,   <apll>R[L]←A</apll>,   <apll>R[L]f←A</apll>,   <apll>L⌷R</apll>,   <apll>L⍉R</apll>,    <apll>L⊃R</apll>
* [[Indices]]: <apll>⍸R</apll>

{{Language Toolbar}}
[[Category:Mouse Group 7|I]]
[[Category:Symbols|I]]

System Variable IO

2016-02-08T19:45:42Z

Robert Wallick: example of changing quad IO

<h1><apl>{quad}IO</apl> - Index Origin</h1>
{{BoxStart|<apll>Z←⎕IO</apll>
| returns the current value of the Index Origin. }}
{{BoxEnd|<apll>Z</apll> is an integer vector containing the current value of ⎕IO. This is the lowest value of an array subscript, and is either 1 or 0.}} 

{| border="1" cellpadding="5" cellspacing="0" rules="none" summary=""
|| <apll>⎕IO←0</apll> || set the lowest subscript of an array to 0.
|-
| valign="top" |<apll>⎕IO←1</apll> || sets the lowest subscript for arrays to 1
|-
|}
 
⎕IO determines the lowest subscript for arrays. The default is 1, but can be changed to 0. If an attempt is made to set ⎕IO to a value higher than 1, it is set to 1. If an attempt is made to set ⎕IO to a value loweer than 0, it is set to 0. Setting ⎕IO to anything other than a number causes a DOMAIN ERROR.

<pre>
⎕IO ⍝ default ⎕IO (quad IO) is 1 in a clear workspace
1
⍳5 ⍝ iota 5
1 2 3 4 5

⎕IO←0 ⍝ Set index origin ⎕IO to 0 (zero)

⍳5 ⍝ iota 5 again but compare the results just below to just above
0 1 2 3 4
</pre>

{{System Variables}}
{{Article footer}}

Symbol Iota

2016-02-08T18:28:45Z

Robert Wallick:

__NOTOC__
<h1> {iota} — iota or index; Keystroke ALT+i ; Character (⎕UCS) 9075</h1>
==Usage==

Monadic use:
* [[Index Generator]]: <apll>⍳R</apll>

Dyadic use:
* [[Index Of]]: <apll>L⍳R</apll>

==Examples==

<pre>
⍳20 ⍝ Monadic example, generate the set of integers 1 through 20
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

'ABCDEFG' ⍳ 'BG' ⍝ Dyadic example, find/lookup the letters B and G in the string 'ABCDEFG' (pos 1 = A, pos 2 = B, ... pos 7 = G)
2 7 ⍝ Results found at positions 2 and 7 of string 'ABCDEFG'
</pre>
==See Also==
* [[Index Generator]]: <apll>⍳R</apll>
* [[Index Of]]: <apll>L⍳R</apll>
* [[Array Lookup]]: <apll>L⍸R</apll>
* [[Indexing]]: <apll>R[L]</apll>,   <apll>R[L]←A</apll>,   <apll>R[L]f←A</apll>,   <apll>L⌷R</apll>,   <apll>L⍉R</apll>,    <apll>L⊃R</apll>
* [[Indices]]: <apll>⍸R</apll>

{{Language Toolbar}}
[[Category:Mouse Group 7|I]]
[[Category:Symbols|I]]

Symbol Iota

2016-02-08T18:27:11Z

Robert Wallick: expanded

__NOTOC__
<h1> {iota} — iota or index; Keystroke ALT+i ; Character (⎕UCS) 9075</h1>
==Usage==

Monadic use:
* [[Index Generator]]: <apll>⍳R</apll>

Dyadic use:
* [[Index Of]]: <apll>L⍳R</apll>

==Examples==

<pre>
⍳20 ⍝ Monadic example, generate the set of integers 1 through 20
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

'ABCDEFG' ⍳ 'BG' ⍝ Dyadic example, find/lookup the letters B and G in the string 'ABCDEFG' (pos 1 = A, pos 2 = B, ... pos 7 = G)
2 7 ⍝ Results found at positions 2 and 7 of string 'ABCDEFG'
</pre>
==See Also==
* [[Index Generator]]: <apll>⍳R</apll>
* [[Index Of]]: <apll>L⍳R</apll>

* [[Array Lookup]]: <apll>L⍸R</apll>
* [[Find]]: <apll>L⍷R</apll>
* [[Indexing]]: <apll>R[L]</apll>,   <apll>R[L]←A</apll>,   <apll>R[L]f←A</apll>,   <apll>L⌷R</apll>,   <apll>L⍉R</apll>,    <apll>L⊃R</apll>
* [[Indices]]: <apll>⍸R</apll>

{{Language Toolbar}}
[[Category:Mouse Group 7|I]]
[[Category:Symbols|I]]

Operators

2016-02-08T17:25:10Z

Robert Wallick:

In NARS2000, operators are symbols used to perform an action based on the arguments to the left, the right, or the left and right of the operator. Operators can be niladic, monadic, dyadic or a combination of these. 
'''Click''' on an '''APL symbol''' just below to view its use:

{{Article footer}}

{{stub}}
[[Category:Definitions]]

Introduction to APL

2016-02-08T17:22:45Z

Robert Wallick: Filled in operators, primitives, etc. links

Welcome to the wonderful world of APL. Whether you've never done programming before or you're a journeyman programmer, APL is going to be something new to you. APL works like no other programming language. First, if you've done any programming, you "know" that when you have an assignment or something like a piece of code is executed, it's "always" done right to left and mathematical formulas are always evaluated right to left according to precedence, so that exponentiation is done first, then multiplication and division, then addition and subtraction. Well, APL is going to blow you away because ''everything you know is wrong''.

First, APL is "backwards" to what you know. APL operates from ''right to left''. All other programming languages operate from left to right. When it comes to computing mathematical formulas, APL has no precedence; unless you put something in parenthesis, all mathematical computations are done strictly right to left to produce the result.

Also, APL uses a specialized set of symbols, and before we had graphical systems, it even had its own specialized keyboard. Many of the actions you have to write a program in other languages can be done in one character in APL. While your typical programming language would show 3 times 4 as '''3*4''', APL has a multiply symbol, so it is written as '''3{times}4''', and to create one half or '''1/2''' in most languages, in APL you would enter '''1{divide}2''' .

So, for example, if you have the following mathematical expression
: 4*5-10 (in normal programming languages), or in APL: 4 {times} 5 - 10
Your typical programming language would compute it as 4{times}5 which is (20), then 20 - 10, resulting in 10. APL will compute it as 5-10 (-5) * 4, or -20. You can adjust this by placing arguments within parenthesis. If your expression was written as
: (4 {times} 5) - 10
It would produce the same answer no matter what programming language you use.

Where APL shines is its ability to handle arrays as easily as most programs handle single values. For example, the '''plus reduce''' operator is used to sum a list of numbers, so in a typical programming language like C or C++ you'd have
: K == 5 + 6 + 8 + 9 + 12 +14
In APL, you'd do the same thing with
: K {:=} +/5 6 8 9 12 14
Now, that by itself isn't very exciting. But what if you had an array X of 1000 numbers. In C you'd have to do something like 
<code>
     k == 0; 
     for (i=1;i++;i<1001) { 
          k += X[i]; 
     }</code> 
You'd do the same thing in APL with
: k {:=} +/ X
APL will take all of the entries in the array X and sum them, in one instruction. You don't even have to know how many entries are in the array X; APL will handle it for you.

To be able to program in APL you'll have to learn what all of the operators do. Links to pages describing APL/APL2 symbols and what they do, just below:
* [[Operators]]
* [[Language_Features]]

Symbol Epsilon

2016-02-08T17:17:12Z

Robert Wallick: added examples, expanded

__NOTOC__
<h1> {epsilon} — '''is an Element of''' — Keystroke is usually Alt-e; Character(⎕UCS) 8714</h1>
==Usage==
==Examples==
<pre>
5 ∊ 1 2 3 4 5 ⍝ determine if 5 is an element of the set of numbers from 1 through 5, result just below 1 = Yes or true, so 5 IS an element of 1 through 5.
1

1 2 3 4 5 ∊ 5 ⍝ determine if the set of numbers from 1 through 5 contains the integer 5. Results 0=False, 1=True
0 0 0 0 1

(⍳5) ∊ 5 ⍝ determine if the set of numbers from 1 through 5 (iota 5) contains the integer 5.
0 0 0 0 1

'this is text' ∊ 't' ⍝ determine if a text phrase contains the letter 't', 1=True, 0=False
1 0 0 0 0 0 0 0 1 0 0 1
</pre>
==See Also==

{{Language Toolbar}}
[[Category:Mouse Group 7|E]]
[[Category:Symbols|E]]

NARS System Developer Suggested Knowledge Prerequisites

2015-12-11T23:56:26Z

Robert Wallick: /* Strongly Recommended C/C++ Programming Knowledge Prerequisites */

'''<big>NARS Systems Developer Suggested Knowledge Prerequisites:</big>'''

== Background ==

All existing computer systems generally require some basic level or prerequisite of programming knowledge in order to better understand their systems, interoperability, platform dependencies, how those systems work, maintain systems and most importantly - improve functionality. If you are an APL programmer yet want to further learn more about how NARS APL Interpreter works, by all means, jump right in and start looking at NARS '''C Programming Language''' source code; strong C/C++ language familiarity is not necessary if you merely want to do APL programming in NARS highly evolved APL. Again and however, if you want to take a giant next step toward 'improving NARS system functionality' and better understanding how NARS APL Nested Arrays (in C) Interpreter works - then continue reading on.

== Strongly Recommended C/C++ Programming Knowledge Prerequisites ==

NARS APL Interpreter is technically written in the C programming language, although its source code also and in many important ways resembles the C++ programming language. Therefore a strong working knowledge of C/C++ is highly recommended and suggested, particularly if you are seriously interested in NARS source code.

Further, NARS makes intensive use of Pointers. Without a highly detailed, comprehensive and broad-based knowledge of working with Pointers in C/C++ you will find it extraordinarily difficult to comprehend much of NARS C Source Code - even to the point where you might give up or abandon an otherwise fascinating APL and '''nested arrays system''' exploration, written using a high-level programming language.

As a first step and to test your knowledge of Pointers, try taking the following C/C++ Pointers tests at '''[http://www.sanfoundry.com/ SanFoundry]:'''
# '''[http://www.sanfoundry.com/c-plus-plus-aptitude-question-answer-pointers/ SanFoundry Aptitude Questions and Answers on Pointers].'''
# '''[http://www.sanfoundry.com/c-plus-plus-language-interview-questions-pointers-into-arrays/ C++ Programming Questions and Answers – Pointers into Arrays].'''
# '''[http://www.sanfoundry.com/c-programming-questions-and-answers-pointer-to-function-1/ Pointers to Functions].'''
If you can score 95% or higher on the above combined tests, your knowledge of Pointers in C/C++ is probably sufficient to better understand and work with pointers in NARS source code. Additionally, it is not just good enough to memorize the answers at the above exercises/links. Take any and all time necessary to fully explore and deeply comprehend how and why the given exercise answers apply, including all syntax involved and what each item of syntax attempts to perform/create/solve. Expert, successful programming - is all about getting the details right, as well as correctly implementing overall desired functionalities.

Obviously, a B.S./B.A. degree in Computer Science would be very helpful to better understand NARS source code - although equivalent and or more experience time actually programming in C/C++ and or other computer languages is/are very helpful.

The above requirements are '''not''' designed to block or deter any serious or determined programmer from working with or augmenting NARS C Source Code. It is something, however, to seriously consider.

NARS in its entirely represents a highly evolved, '''very''' machine-efficient and expert APL programming system, originally conceived of and developed [primarily even solely] by Bob Smith. If you are serious about improving APL/NARS - then a serious, thorough working knowledge of C/C++ is a minimum prerequisite, to effectively work with NARS' '''professional,''' virtuoso level, '''standards-compliant''' source code and APL/nested arrays system.

In short, beginners are welcome, experts-highly-in-demand. This by the way is also true of programming workplaces, and the programming world generally.

Happy computing! 
Go or return to - '''[[Building_An_Executable|Building NARS Executable]].'''

NARS System Developer Suggested Knowledge Prerequisites

2015-12-11T23:46:26Z

Robert Wallick: added text, links to suggested prerequisite level-of-accomplishment tests

NARS System Developer Suggested Knowledge Prerequisites

2015-12-11T22:34:29Z

Robert Wallick: created page NARS System Developer Suggested Knowledge Prerequisites

'''<big>NARS Systems Developer Suggested Knowledge Prerequisites:</big>'''

== Background ==

All existing computer systems generally require some basic level of programming knowledge in order to better understand their system(s), how they work, maintain those systems and improve their functionality. If you are an APL programmer and want to learn more about how the NARS APL Interpreter works, by all means, jump right in and start looking at NARS '''C Programming Language''' source code. This is not necessary if you just want to perform programming in NARS highly evolved APL but -- if you want to take the next step toward 'improving NARS functionality' and better understanding how NARS Interpreter works - then read more on this web page.

== Strong Recommended Knowledge Prerequisites ==

NARS APL Interpreter is technically written in the C programming language, although its code also and in many important ways resembles the C++ programming language. Therefore a strong working knowledge of C/C++ is highly suggested if you are seriously interested in NARS source code.

Further, NARS makes intensive use of pointers. Without a very detailed comprehensive and broad-based knowledge of working with Pointers in C/C++ you will find it extraordinarily difficult to comprehend much of NARS C Source Code - even to the point where you might give up or abandon an otherwise fascinating APL and nested arrays system, written using a high-level programming language.

Building An Executable

2015-12-11T22:33:43Z

Robert Wallick: added NARS Systems Developer Knowledge Prerequisites section

<div style="float:right; padding-left:5px;">
{| style="text-align:left; border:1px solid #aaaaaa; background-color:#f9f9f9;width: 200px;font-family: Verdana, sans-serif;"
|- padding:5px;padding-top:0.5em;font-size: 95%;
|
----
<div style="border:1px solid #ccc; background: #fff; border-right:3px solid #ccc; border-bottom:3px solid #ccc; text-align: center; padding:3px; float:right; font-size: smaller; line-height: 1.3; margin-right: 4px;">
<div style="width:100%">{{CURRENTDAYNAME}}</div>
<div style="font-size: x-large; width: 100%;">{{CURRENTDAY}}</div>
<div style="width: 100%;"> {{CURRENTMONTHNAME}}</div>
<div style="width: 100%;">{{CURRENTYEAR}}</div>
<div style="background: #aaa; color: #000;">'''{{CURRENTTIME}}''' UTC</div>
</div>
<big>'''NARS2000 Building The Executable'''</big>
----
<div style="text-align:center;">
</div>
|-
|
__TOC__
|}
</div>
==Update Notice==

Although it is not an 'only compiler - IDE choice,' the below uses '''Visual Studio 2013''' as its designated C/C++ Compiler and IDE(Integrated Developer's Environment, GUI/Graphical User Interface for programming). All source code compiles correctly and multiple APL workspaces have been tested for correct APL/NARS functionality. This page is current, up-to-date re NARS working with VS2013's compiler and standards. The conversion to VS2013 resulted in a more up-to-date (5 years[2008 to 2013] more current software technology) program for the GUI Builder and Compiler interface, including newer C/C++ programming standards. This has represented a major cyclical software upgrade and results in greater APL user functionality via improved C coding. Recent releases of NARS2000.exe (32 and 64-bit versions) are fully functional.
<div align="right">v---- '''Useful Developer links:''' ----v [http://svnbook.red-bean.com Version Control with Subversioning - Conceptual Gen Bkgnd.] [http://sourceforge.net/p/forge/documentation/svn/ Source Forge Versioning Documentation] [http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ Source Forge NARS2000 Source Code]</div>

==Why Build Your Own==

First of all, you do not have to build your own. NARS has already created a great existing Nested Arrays Research System APL interpreter. NARS2000.exe is freely available at [http://www.nars2000.org/download/Download.html NARS Downloads]. Downloads includes Beta releases for APLers so inclined.

On the other hand, why not expand your programming/software and computer skill horizons? Many people think and believe '''Kenneth Iverson's''' work remains that of a true genius, a bright light among some very bright intellectual lights, both from a theoretical as well as a software implementation perspective. Here's your opportunity to attempt to improve upon some very substantive, preexisting software development work - to further it, to make it even better, and perhaps best of all - '''it's free'''.

Personalize some already pretty amazing software for yourself, or share it with others and get '''their feedback''' for even greater insight and subsequent improvement. NARS version of APL already has over a quarter million lines of source code, subroutines, macros, functions, etc. - 50 years of sometimes intense and continuing evolution, so you are not creating something from undeveloped scratch, but inheriting and working from already highly evolved, rigidly disciplined concepts and rigorously debugged software over time.

'''APL/2''' has been used in physics, science, genetic engineering-DNA studies, advanced mathematics, robotics, engineering, artificial intelligence, image processing, bio-medicine, VLSI, financial, statistical and social science applications. NASA and Astronomers have used APL.

Now APL/2 is 100% customizable. Perhaps you will be the first to customize APL to safely drive a vehicle, help save a life, make new discoveries or make some process(es) more efficient.

It's '''free'''. It's '''evolved'''. Once you start examining NARS/APL/APL2 source code you'll find it is comprehensive, elegant, process-symbol-efficient, focused toward the end-user, evolved over some fifty years of use, structurally enigmatic, tirelessly debugged and rich with coding techniques - a great learning tool, even if absolutely nothing else - and NARS believes it is far, far better than just a learning tool. You'll learn about Bison Parsing, how it helps define compilers and interpreters. Further, NARS is a tremendous opportunity to learn more about the human-machine interface; how machine hardware operates and - better understand how software and hardware interact together.

One of the stellar, intellectually expansive aspects of APL/2 is - how fully the language embraces the breadth of hardware functionality. This includes instructions running core processor chip(s) and peripheral devices. This is not your grandparents' punch-card software program run on a room-sized computer, although that was marvelous at its time, but it may have taken him/her several days to get results back for in an introductory chemistry or math lab course. Today '''[http://phys.org/news/2015-03-quantum-unexpected-ways.html data structures influence speed of quantum search in unexpected ways]'''.

==Platforms==

The current version of NARS2000 may be run and built on a variety of Windows platforms, including most or all post-Windows-98 OS versions. Furthermore, a long-term goal is to enable NARS to be built on Linux, Mac OS, etc. as per user requests and Developer interests. If you do not have a Windows machine, the following may be helpful to you:

'''[http://www.howtogeek.com/187359/5-ways-to-run-windows-software-on-a-mac/ Five ways to run Windows software on a Mac.]''' From HowToGeek.com, methods include 1)Virtual Machines, 2)Boot Camp, 3)Wine, 4)CrossOver Mac (not free) and 5)Remote Desktop.

'''[http://www.howtogeek.com/133515/4-ways-to-run-windows-software-on-linux/ Four ways to run Windows software on Linux.]''' Again from HowToGeek.com, methods include 1)Use Wine, 2)Run Windows in a Virtual Machine, 3)Try Crossover (not free) and 4)Remote Desktop. A fifth way per [http://www.pcworld.com/article/2900497/how-to-run-windows-software-in-linux-everything-you-need-to-know.html PC World] is dual booting both Linux and Windows on your machine. This essentially involves partitioning hard drives with a portion reserved for Linux and a portion reserved for Windows. With costs of external hard drives continuing to decline, buying an external or network hard drive may free up hard drive storage space requirements.

'''[http://www.howtogeek.com/173353/how-to-run-windows-software-on-a-chromebook/ How to Run Windows Software on a Chromebook {notebook or tablet PC}.]''' Again from HowToGeek.com, methods include 1)Access a Windows Desktop Remotely, 2)Use Developer Mode and Install Wine (not available for all Chromebooks), 3)Use Developer Mode and Install a Virtual Machine (may require an Intel Chromebook).

Furthermore, if you work using a tablet or other computing device which supports remote desktop software such as '''[http://teamviewer.com Team Viewer]''' and you have a home or work computer running Windows - then you can remotely use NARS over your network and internet using that computer as a host and your local device as a client. Network and internet speeds are sufficiently fast and TeamViewer, for instance, is very good at making your remote desktop seem and respond as if virtually right in front of you.

For the present, the following sections detail descriptions for building the executable with bias towards Windows.

==Downloads==

To build the executable in summary you'll need the following:

# C Compiler and Linker
## Make program
## Resource Compiler
## Windows SDK
# Parser Generator
# Zip Utility
# PHP (Hypertext Preprocessor)
# NARS2000 Source Code
# NARS2000 External Libraries
# Optionally, Multi-precision Library Source
# STDINT.H header file
# Version Control program
# Doctor Dump SDK
# Optionally, a File Differencing/Merge program
 All of the tools you'll need are '''freely available'''. Some of them happen to be Microsoft-specific. Bill Gates while at Harvard actually worked a bit on/with APL, obviously he discovered the importance of working with arrays and symbolic notation. At the same time there is no reason more generic tools (such as [http://www.delorie.com/djgpp/ DJGPP], [http://www.cygwin.com/ Cygwin] or [http://www.mingw.org/ MinGW]) can't be used, a task NARS is hoping someone will volunteer to investigate. In particular, the '''tools currently used''' to create the APL Executable, in detail, are as follows:
 
# '''C''' (needed for this NARS2000 project is '''Visual C++ 2013''' = C++ GUI development environment and compiler for the C language, which much of APL's interpreter is written in). Compiler and Linker: '''[https://app.vssps.visualstudio.com/profile/review?download=true&family=VisualStudioExpressDesktop&release=VisualStudio2013Upd4&type=web&slcid=0x409 Microsoft Visual Studio 2013 Express for Desktop Windows]''' (download requires a FREE Microsoft/Visual Studio account) OS requires Windows XP or later — includes Link, Make, a Resource Compiler, and an SDK (among others). Download/Installation Notes: The '''downloaded file''' may be double-clicked in Windows Explorer. VS 2013 does NOT Install to a mapped or network drive(but to something like C:\Program Files\...). It must be Installed on a local PC drive (e.g. C:\...) and '''unmapped directory''' (but you can map to it later) - Microsoft apparently requires installation to a local machine drive letter such as "C:\...".   VS2013 Desktop is free '''and''' it includes a GUI or graphical user interface (icon-based IDE or integrated developer's environment), which is geometrically easier to use than a command-line interface. Windows 8.1 SDK (does NOT require Windows 8.1, but does update for some 8.1 capabilities, especially useful for using Visual Studio 2013; '''[https://msdn.microsoft.com/en-us/windows/desktop/bg162891.aspx?f=255&MSPPError=-2147217396 download is available at Microsoft]'''. '''Windows SDK''' (the following MAY NOT BE NECESSARY, SDK=Software Developers Kit, sometimes needed for '''64-bit installations''', usually choose download file GRMSDKX_EN_DVD.iso even for Intel machines) '''[http://www.microsoft.com/en-us/download/details.aspx?id=18950 download here]''', with '''installation instructions [https://github.com/enGits/engrid/wiki/Configure-Microsoft-Visual-Studio-2008-Express-to-also-build-for-Windows-x64 here]'''.
# '''Parser Generator''': '''[https://cygwin.com/install.html Bison]''', a Cygwin package, Save and run either '''setup-x86.exe''' (32-bit systems) or '''setup-x86_64.exe''' (64-bit systems) as appropriate to your system, '''Choose A Download Source''': Install from Internet, '''Select Root Install Directory''', '''Select Local Package Directory''', '''Select Your Internet Connection''', '''Choose A Download Site''', '''Select Packages''': Leave alone '''All (Default)''' - first time through, just click [Next], '''Devel''', and '''bison''', other dependent packages may be installed along with '''bison''', if not then '''after first''' Cygwin installation finishes, double-click the downloaded Cygwin file in Windows Explorer, downloaded filename should be something like '''setup-x86_64.exe''' and the '''second time through''' do specifically download and install '''Dev''', '''Bison''' - informally note the '''tree structure''' during the Bison download/install since '''creating parse trees''' is '''very much''' a ''Bison program specialty'', a strength. Compilers and even APL itself relies heavily on correct statement type recognition and parsing. To make sure you successfully downloaded and installed '''bison.exe''', the file should be '''found''' or reside in the C:\Cygwin\bin or C:\cygwin64\bin folder. Make note of the folder location since you will need it when setting the PARGEN environment variable shortly, below.
# '''Zip Utility''': '''[http://www.7-zip.org/ 7-Zip]''' (Latest version, 32- or 64-bit, as appropriate to your system; needed to Extract/Unzip the files and folders you are downloading for this project.) If you already have a Zip utility program on your PC, Tablet or Server such as WinZip, you can normally skip the 7-Zip download/install.
# '''PHP''' (Hypertext Preprocessor): '''[http://www.php.net/downloads.php Downloads]''' (Windows downloads for Windows systems.) (Windows binaries/VC9 x86 Thread Safe/Latest version/Zip or Installer, your choice) (Items to Install: Entire '''Script Executable''', and entire '''Extras'''). Place the unzipped file's contents into something like "C:\PHP". The executable file "php.exe" needs to be "on your directory or environmental path" when later compiling or building the APL executable.
# '''NARS2000 Source Code''': Click on '''[http://sourceforge.net/projects/nars2000/ Browse Code] button''' at '''NARS''' SourceForge.net '''code repository'''. You may also use a Version Control program, e.g. see Tortoise SVN below and [http://tortoisesvn.net/ here, see their download page]. '''Prior''' non-current NARS Source Code versions available at [http://code.google.com/p/nars2000/source/checkout Code Google].
# '''NARS2000 External Libraries''': [http://www.nars2000.org/download/binaries/misc.zip Miscellaneous Library] (misc.zip, which contains 4 .php files and 1 .ttf file - all directly unzipped into C:\NARS2000) and the following NARS libraries:
## [http://www.nars2000.org/download/binaries/mplibs.zip '''MPIR/MPFR/ECM Libraries'''] - These libraries(mplibs.zip) should be directly extracted or unzipped into the C:\NARS2000 folder such that three(3) distinct sub-directories are '''directly''' created: \ecm, \mpfr and \mpir, e.g. C:\NARS2000\ecm.
## [http://www.nars2000.org/download/binaries/gsldir.zip '''gsl Library'''] - This library(gsldir.zip) should be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\gsl'''. Folder structure "C:\NARS2000\gsldir\gsl" would be invalid.
## [http://www.nars2000.org/download/binaries/qdebug.zip '''qdebug Library'''] - This library(qdebug.zip) should also be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\qdebug'''. Make sure it is NOT double-enclosed when unzipped, for example the following would be an invalid folder setup structure: C:\NARS2000\qdebug\qdebug.
# '''Multi-precision Library Source Code: [http://www.nars2000.org/download/binaries/mpfns-src.zip MPIR/MPFR/ECM Source]'''. This zipped download is large (roughly 0.5GB) and is needed primarily to reproduce files in the MPIR/MPFR/ECM Library download so as to satisfy requirements of the GNU General Public License (GPL) v3. For more details on using the files in the download, look in the zipped file for <code>readme.txt</code>. If you are content to use the already-compiled existing binary libraries in [http://www.nars2000.org/download/binaries/mplibs.zip MPIR/MPFR/ECM Libraries], you may not immediately need the MPIR/MPFR/ECM Source Code; on the other hand - 128-bit CPU chips are in manufacturing production pipelines, quadruple-precision 128-bit floating-point format has been standardized by the IEEE and ultra-precise calculations are already needed in such fields as quantum physics, ref. [http://phys.org/news/2014-06-physicists-quantum-ultra-precise.html Physicists take quantum leap toward ultra-precise measurement], 6/2/2014. One of APL's strengths is its handling of mathematically precise calculations and the '''large size''' of the multi-precision source code library reinforces that.
# [http://msinttypes.googlecode.com/svn/trunk/stdint.h STDINT.H] header file installed in the MS Visual Studio 2013 include directory (V:\VC\include -- see below)
# '''SubVersion Control program''': [http://tortoisesvn.net/downloads Tortoise SVN] (Current version, 32- or 64-bit depending upon your OS)
# '''Doctor Dump SDK''': [https://drdump.com/public/DoctorDumpSDK/DoctorDumpSDK.zip Doctor Dump SDK] - e.g. DoctorDumpSDK.zip.
# '''File Differencing/Merge program''': [http://winmerge.org/ WinMerge] ('''Latest stable version''', usually downloads to something like WinMerge-k.m.n-Setup.exe where k, m and n are version/sub-version numbers.)

==Install Tools==

'''Preface''', Convention: '''x86''' generally refers to '''32-bit''' software installations while 64 (or blank) represents 64-bit software installations on a Windows OS machine. NARS works on '''both''' 32-bit and 64-bit systems, but you should decide '''in advance''' which type of install you want 64 vs. 32-bit - ditto for all tool installs. Installation examples:
# C:\Program Files (x86)\        Represents 32-bit software program installation, normal folder location.
# C:\Program Files\                 Represents 64-bit software program installation, normal folder location.
Also, '''both''' folder locations just above frequently and even always exist on most machines, but for consistency and integration purposes the software should be 32 '''or''' 64-bit. Most people choose 64-bit installs if their Windows OS supports the 64-bit architecture, with 32-bit available for backward software compatibility in conjunction with less current systems. If you don't know which architecture your system uses, go to the Control Panel, System Information. Downloads usually get placed into a Downloads folder. Several of the unzipped NARS tools get placed directly into the C:\NARS2000 folder, see individual tools for exact locations. 

To install the Microsoft '''Visual Studio 2013 Express C compiler''', see Downloads(detail, #1 above). Visual C++ 2013 usually installs into something like, "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" (64-bit loc) and you may want to place a '''Shortcut''' to '''VCExpress.exe''' on your Desktop by right-clicking on that VCExpress.exe file in Windows Explorer and Send To - Desktop (create shortcut). (Windows 8 Users: You can also '''Pin VCExpress.exe To your Taskbar''' for quick, easy access.) (Prior/obs. Microsoft setup routine name: run the vcsetup.exe program.) Afterwards including after drive plus folder remapping - the files '''msobj80.dll''', '''mspdb80.dll''', '''mspdbcore.dll''', and '''mspdbsrv.exe''' all need to be copied from '''V:\Common7\IDE''' to '''V:\VC\bin''', where the '''V''' drive is a substitute/mapping for '''C:\Program Files\Microsoft Visual Studio 9.0'''. See the discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

To install the Parser Generator (Bison), see the instructions above. When the Cygwin setup program asks you to choose a '''Default Text File Type''', choose '''DOS/text''' so any committed files are the same as in the version control repository.

To install Doctor Dump SDK, unzip it in a directory at or above %NARSROOT%, this usually means unzipping into folder C:\DoctorDumpSDK. See also discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

Install the rest of the tools as per their instructions above, in the Downloads section.

==Install The Source Code==

<ol>
<li>First create a NARS2000 '''root folder''' somewhere on one of your hard drives, perhaps calling it '''NARS2000''', as in '''C:\NARS2000''' (most common) or perhaps at some lower level. The source code and external libraries are typically installed at or into this level, e.g. qdebug.zip into C:\NARS2000 as C:\NARS2000\qdebug.</li>
<li>Under the root folder make three folders: '''trunk''', '''msieve''', and '''branches'''. The first folder ('''trunk''') will hold the main body of NARS/APL built exe interpreter '''source''' code. The second ('''msieve''') will be utilized for code used to '''factor numbers''', and the third ('''branches''') will contain individual developer branches of the main code not as yet ready for release, but made public for other developers to see.</li>
<li>Using a Version Control program such as '''TortoiseSVN''', download-checkout the source code (see [[#Check_Out_The_Source_Code|Check Out The Source Code]]),</li>
<li>Download the '''misc.zip''', '''qdebug.zip''', '''gsldir.zip''', and '''mplibs.zip''' files into the root folder and unzip them (directly into that root folder, e.g. C:\NARS2000) using e.g. '''7z.exe''' (unzip/extract program used) as in '''7z x misc.zip''', '''7z x qdebug.zip''', '''7z x gsldir.zip''', and '''7z x mplibs.zip''' - or double-click on those downloaded zip file names using Windows File Explorer and Extract All (again typically directly into NARS root folder previously set up).</li>
</ol>

==Check Out The Source Code==

An easy way to initialize your copy of the source code for the first time, although it may initially appear cumbersome to an SVN newcomer, is to use a version control program such as TortoiseSVN, mentioned above. One very helpful feature of TortoiseSVN is that it integrates well with Windows File Explorer. After downloading and installing TortoiseSVN and then rebooting your PC, there are two directories you will need to Install/initialize-checkout/TortoiseSVN-on.
# '''First''' bring up Windows Explorer, right-click on the '''trunk''' folder you manually created, and choose '''SVN Checkout'''. The online NARS URL of repository: is '''svn://svn.code.sf.net/p/nars2000/code/trunk''' and your local Checkout directory: is '''C:\NARS2000\trunk''' (or wherever your trunk folder is) - quite likely you will have to edit the TortoiseSVN repository field or program local folder field because default text inserted by TortoiseSVN usually does not match folder location(s) identically. Depth should show Fully recursive, the default. To begin source code downloading/checkout into your locally created '''trunk''' folder click the '''OK''' button. Code downloading/checkout should then begin. With a high-speed Internet connection, time required to TortoiseSVN download/checkout NARS code is on the order of roughly two minutes. When successfully complete, you should get a return message at the end of the downloads list, like '''Completed at revision nnnn'''.
# '''Second''' (and this is a similar repeat step but using folder '''msieve''' instead of trunk), bring up Windows Explorer, right-click on the '''msieve''' folder you likewise manually created - and choose '''SVN Checkout...'''. This time online NARS '''URL of repository:''' is '''svn://svn.code.sf.net/p/nars2000/code/msieve''' (this address is slightly different than step 1) and your local '''Checkout directory:''' is '''C:\NARS2000\msieve''' (or wherever your '''msieve''' folder is). Again, depth should be fully recursive and click the '''OK''' button to begin. This step two normally completes in under five seconds, downloading far fewer files than the trunk download. Normally, the same msieve revision number should appear after finishing this download as per trunk download in step 1.

The above '''two''' steps/distinct-folders need be initialized this first checkout time through - in order to establish the special hidden SVN directories for subversion "synching" between your local source code and NARS online code repository. As a brief check that your '''local''' NARS source code files match NARS, there should be green check marks on folders trunk and msieve on your PC, placed there by TortoiseSVN. [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-wcstatus.html TortoiseSVN Status Information.]

You will still or now need to download and unzip '''qdebug.zip''', '''misc.zip''', '''gsldir.zip''', and '''mplibs.zip''' as described above.

Subsequently, you may quickly and easily update your local copy of NARS source code by right-clicking on the '''trunk''' and/or '''msieve''' folders and choose '''SVN Update'''. One useful feature of sub-versioning programs such as TortoiseSVN is that only '''changed files''' from the online latest official version will need to be subsequently downloaded as changes are made in futuro, re subsequent NARS revisions.

Since you may be unfamiliar with the download process your first time through, it make take slightly longer; however, the second or third time you Check Out The Source Code, over time, the entire "update to most current NARS source code revision" process will probably take under 3 to 5 minutes total, depending however on your (high-speed) Internet service provider's(ISP) download speed.

==Folders==

After unzipping the above files, the structure under the '''NARS2000 root folder''' should look very much like the following('''leftmost column'''), where lower level sub-directories and individual sub-folder file names have been omitted:
{|class="wikitable"| style="width: 40%; border:1px dotted blue;"
!'''NARS2000''' SubFolder:
! Downloaded Zip '''Source''' File or Checkout Process:
|-
| branches\
| class="Unicode" style="text-align:center;" | Created manually(1)
|-
| ecm\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| gsl\
| class="Unicode" style="text-align:center;" | '''gsldir'''.zip
|-
| mpfr\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| mpir\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| msieve\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''msieve'''
|-
| qdebug\
| class="Unicode" style="text-align:center;" | '''qdebug'''.zip
|-
| trunk\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\binaries\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\Extensions\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\htdocs\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\images\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\MediaWiki\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\ReleaseNotes\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\WineHQ\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
|}
(1) Subfolder '''\branches''' should be '''created manually''' (e.g. Windows Explorer, right-click, New, Folder). It is used to hold subprojects you may develop. For example if your name is Bill Gates, you might have the following subfolders, each representing a NARS subproject: 
C:\NARS2000\branches\bgates\NARS_Spreadsheets 
C:\NARS2000\branches\bgates\NARS_WordProcPlusAPLEdits 
C:\NARS2000\branches\bgates\EZMenus 
C:\NARS2000\branches\bgates\Graphics 

==Choose How To Build==

The following sections describe two alternate ways to build the executable. One is the GUI interface of VC++ Express, the other is a command line interface using a '''makefile'''.

==Set Up VC++ Express==

If you are using Visual Studio 2013/VC++ Express, the project file is in the '''trunk''' folder and is called '''NARS2000.vcproj'''. You may load it manually every time you invoke VC++ Express, or you may load it automatically by placing the path to the project file on the command line in the VC++ Express shortcut as in '''"C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" C:\NARS2000\trunk\NARS2000.vcproj''' or wherever you defined your NARS2000 root folder.

The vast majority of the project settings are found in the above file with some exceptions.

==Set Up Makefile and Environment Variables==

<hr width=25%>
'''Windows 8''': Setting up Environment and Path Variable(s):
Under Settings, Control Panel, System and Security, System, Advanced System Settings, Advanced (Tab) '''or''' in Control Panel Search for '''Environment Variables''',
* Click '''Environment Variables''' button - There is both a '''Temp Variable''' and '''Path Variable'''.
:: There are 2 sections, User Account Variables and System Variables. You normally want to add new '''System Variables'''.
::: Click '''[New]''' button for a New System Variable:
:::: Variable name       '''PARGEN'''
:::: Variable value       '''C:\cygwin64\bin\bison'''       << typical for a 64 bit install(for bison.exe in subfolder bin), for 32 bits installs see below for variable '''set''' values.
* Normally add a '''New''' variable (var Name plus Value) for each of the '''eight Set''' vars commands listed below, 8 environment variable names - such as NARSROOT, CS_DIR, ZIPPRG, PARGEN, etc.
* If you need to add another Path to an existing variable, each new or added path is separated with a semi-colon.
* After updating any Environment/Path variable(s) you apparently need to reboot since the above variable changes only affect changes in the Registry until PC is rebooted.
* The instructions below should also or alternatively work.
<hr width=25%>
If you are building from the '''makefile''' or working with the GUI C++ Compiler, you'll need to set '''eight environment variables''' in your '''autoexec.bat''' file ('''or''' see just above for setting Environment Variables via '''Windows Control Panel'''). Note that ''Environment variable #n's'' just below are shown only for helpful reference purposes.
<pre>
REM Path of the root of the NARS2000 project *ending with a backslash*
Set NARSROOT=C:\NARS2000^\                         Environment variable #1

REM Path to Doctor Dump SDK root
Set CS_DIR=C:\DoctorDumpSDK^\                      Environment variable #2

REM Path and name of zip program (7-Zip)
Set ZIPPRG="C:\Program Files\7-Zip\7z"             Environment variable #3

REM Path and name of parser generator (bison)      Environment variable #4 (next line)
Set PARGEN=C:\Cygwin\bin\bison         OR for a 64-bit install >>   Set PARGEN=C:\cygwin64\bin\bison

REM Path and name of makedep program
Set MAKEDEP=%NARSROOT%makedep.php                  Environment variable #5

REM Path and name of the <makepro.php> program
Set MAKEPRO=%NARSROOT%makepro.php                  Environment variable #6

REM Folder of SDK ("C:\Program Files\Microsoft SDKs\Windows\v7.0A")
Set SDK=U:^\                                       Environment variable #7

REM MSVC compiler ("C:\Program Files\Microsoft Visual Studio 9.0")
Set MSVC=V:\VC^\                                   Environment variable #8
</pre>
<hr width="75%">
'''Mapping Virtual Drive Letters:''' 
You will be using Windows '''subst''' command to map drive letters as references to drives '''U:''' and '''V:''' that several of the above '''environment variables''' refer to. Microsoft explanation of '''[https://technet.microsoft.com/en-us/library/bb491006.aspx subst command here]'''. 
Modify your C:\AutoExec.bat file to include something approximating the following highlighted text(version#/32/64 bit installs each vary), '''include''' the enclosing quote chars just below: 
'''subst U: "C:\Program Files\Microsoft SDKs\Windows\v7.0A"'''      (or whatever your current version is) 
'''subst V: "C:\Program Files\Microsoft Visual Studio 9.0"'''             (ditto re version 9.0=Visual Studio 2008)
 
If you do not have an '''AutoExec.bat''' file (many '''Windows 7 and 8''' users may not):
: Create a new text document using Windows File Explorer, rename it as AutoExec.bat and move(or copy) it to the '''C:\''' drive folder '''with the above two subst''' commands in it.
: Windows 7 and 8 users: File AutoExec.bat no longer automatically gets run at system-user boot-up so '''place a Shortcut to AutoExec.bat''' in the Program files '''Startup''' folder location(navigate Windows File Explorer to '''one''' of the below locations, right-click, '''New''', '''Shortcut''', '''AutoExec.bat'''). The Windows 7/8 Startup Folder usually is located as follows:
:: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup                                         (general/all users Startup folder) '''OR'''
:: C:\Users\'''UserName'''\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup       (single user Startup folder, '''UserName varies''')
'''IMPORTANT''': A successfully mapped '''V''' drive should contain a sub-sub-subfolder which then contains the '''amd64\nmake.exe''' (64-bit systems) file or '''bin\nmake.exe''' (32-bit systems), e.g. '''typical''' 64-bit configuration/location: '''C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\nmake.exe'''.
:The V drive map would '''only''' include linking through subfolder '''\Visual Studio 9.0'''. After creating the linked drives, just '''check''' to make sure your mapped '''V''' drive has the '''nmake.exe''' contained one or several subfolder levels below it. The NARS2000.exe automated Compile/Build uses '''nmake.exe''' during exe construction. 64-bit installs require the '''amd64\nmake.exe''' file - paradoxically even if your machine's chipset is Intel, a minor Microsoft variation. 
Typical mapped configurations just below, but again each install/version# may vary: 
'''U''' =     '''C:\Program Files\Microsoft SDKs\Windows\v7.0A'''     (or v6.0A or whatever your downloaded/current version is) 
'''V''' =     '''C:\Program Files\Microsoft Visual Studio 9.0'''           (or '''C:\Program Files (x86)\Microsoft Studio 9.0''' for 64-bit installs, again look for nmake.exe in a subfolder) 
As a '''check''' to make sure the '''subst''' commands worked, there should now be '''2 new drive letters visible in Windows Explorer, in the leftmost window for virtual drives/mapped folders - U and V'''. ''To avoid having to reboot'' at present, just '''open'''(not edit but run) '''AutoExec.bat AFTER''' making sure it is 100% correctly configured. Having a correctly configured AutoExec.bat file will ensure not having to manually link drives U and V each time the NARS2000.exe is built-rebuilt.
<hr width="40%">
If you install NARS project tools in other folders, make appropriate changes to the above mappings.

'''Lastly don't forget:''' To append three folders: '''C:\cygwin64\bin''' , '''V:\Common7\IDE''' and '''C:\PHP''' to your '''Path''' variable '''PATH=%PATH%;C:\cygwin64\bin;V:\Common7\IDE;C:\PHP''' or see '''Control Panel''' search for '''Path''', then '''Edit''' System Environment Variables for your account, system variable named '''Path'''; append to that '''Path''' variable   ''';C:\cygwin64\bin;V:\Common7\IDE;C:\PHP'''   - (three additional paths, semicolon separated) so Visual C's '''Make''' plus '''Compiler''' can find DLLs, exe's and Tools you have so diligently downloaded, then installed.

==Pre First Compile and Localization Notes==

Make/Compile local Environment Variable '''%NARSROOT%''' is presently set using file '''C:\NARS2000\trunk\wcustomize.bat'''. This bat file is called by other major trigger-compile bat files such as mk32.bat, mk64.bat, w32.bat and w64.bat - which oversee-initiate compilation. The %NARSROOT% environment variable is important in indicating where Make/Compilation will occur. Before first locally compiling NARS2000, you likely need to manually edit (using Notepad or a local text file editor) file '''trunk\wcustomize.bat''' and make sure the following are initially correct per your 'local PC NARS installation' i.e. within wcustomize.bat: 
'''Set NARSROOT=C:\NARS2000^\'''       (Note: '''No %''' symbols are needed in set/specification rows in wcustomize.bat, e.g. replace 'R:\NARS2000' to 'C:\NARS2000' as shown at left) 
'''Set CS_DIR=C:\DoctorDumpSDK^\'''     (again R:\ was changed to C:\) 
The additional hat(^) symbol in the above bat commands is needed for directory/folder recombination purposes, essentially sub-directory parse-point identification and or recombination point, where NARS may use subdirectories/parsing.

'''Prior''' to using '''Visual Studio''' and its '''IDE'''(integrated developer's environment) for NARS Building/Compilation purposes a first time, and to help ensure the proper installation of NARS source code - it is very helpful/necessary to open a CMD.EXE window using <big>'''Windows Start''', '''CMD.EXE'''</big>. This will open up a small CMD window. While <big>inside the opened CMD.EXE window</big>, navigate to your local C:\NARS2000\trunk folder, using <big>'''cd C:\NARS2000\trunk'''</big> where cd represents change directory. Now run <big>'''mk32.bat'''</big> by typing it in, to compile NARS2000's 32-bit executable. If mk32.bat is successful and if your installation is 100% correct, two identical files in separate folders will be created(built and compiled) using bat commands from inside that CMD window/session: 
'''C:\NARS2000\trunk\RET\ND32\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND32\NARS2000.exe''' 
If that 32-bit NARS make/build was successful, then from the same CMD.EXE window, type <big>'''mk64.bat'''</big>. This should likewise compile locally the '''64-bit''' NARS Executable, with again two resulting '''exe output files:''' 
'''C:\NARS2000\trunk\RET\ND64\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND64\NARS2000.exe'''

Successfully completing mk32.bat and mk64.bat along with presence of their respective '''NARS2000.exe''' output files generally confirm successful installation of NARS source code, as well as correct installation for several associated tandem utility tools re compiling NARS2000.exe on your server, PC, notebook or tablet computer.

==Building The Executable==

Congratulations, if you've successfully arrived at this section, your resume now includes such useful terms as software installation wizard and relentless software engineering candidate. You are part of an elite group - the few, the proud, NARS geek marines; also known as tomorrow's APL-symbol-set event-horizon squad. You've managed to easily or otherwise cross several potentially deep programming ravines in the process.

At this point you should be ready to build the executable, again - this time however from inside Visual Studio's IDE(integrated developer's environment). There are two general ways to build NARS executable. Method one: Involves the time-honored command-line batch file compile mode using files mk32.bat or mk64.bat - as you should have previously discovered in the section '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' while using Windows CMD.EXE.

Method two: Involves again first opening a (Windows Start button) '''CMD.EXE''' window and running '''w32.bat start''' (all one command) or '''w64.bat start'''. Immediately or shortly, you should see Visual Studio 2013's program visualize, load and run - with either the 32-bit or 64-bit NARS2000 project/program loaded. After Visual Studio 2013 finishes loading - simply click Build. Full use of Visual Studio 2013's IDE (integrated developer's environment) should now be available for you to experiment with, develop code on, debug and customize APL as you may choose. Your first time through with running '''w32.bat start''' and '''w64.bat start''':
* There is usually a Visual Studio '''One Way Migration''' message which displays. This is normal, TBE(to be expected), and yes you DO at that point want to migrate the NARS2000 project to Visual Studio 2013. There are usually roughly 20 migration warnings which also show up in an Internet Browser page re the Migration Report - again, all normally to be expected. However, there should be '''zero errors''' in the migration report.
* If all went satisfactorily well with the Migration, you should be able to select/choose/Click '''Build Solution''' under Build in VS2013's IDE to fully compile NARS2000 executable. After Build, there should likewise be zero errors.

Special note regarding '''w32.bat start''' and '''w64.bat start''' while in Visual Studio's IDE for the NARS2000 project:
When switching between 32 and 64-bit versions, i.e. w32.bat start '''versus''' w64.bat start: There is a '''Property''' adjustment required when using Visual Studio's IDE. After Visual Studio opens up and in the Solution Explorer window (usually on the upper right hand side of your screen) click on "Solution 'nars2000' (1 project)." This should then show a Properties Window just below it. Look for a line which reads: '''Active config'''. If you ran w32.bat start then Active config should have a value of '''Debug32|Win32'''. If you ran w64.bat start then Active config should have a value of '''Debug64|Win32'''.

== NARS Systems Developer Suggested Knowledge Prequisites ==

For a strongly recommended set of knowledge prerequisites - in order to effectively understand, maintain or improve NARS functionality - please see '''[[NARS System Developer Suggested Knowledge Prerequisites|NARS System Developer Suggested Knowledge Prerequisites]]'''.

==Developer Experiments with NARS Source Code==

This section is for Developers who have successfully downloaded NARS source code and want to Experiment with it, or further develop NARS APL Interpreter's source code.

For development and debugging purposes: You as APL Interpreter developer normally want to want to first write new source code/model using the 32-bit version of NARS2000 (w32.bat start). This is because the 32-bit version is easier to debug than the 64-bit version; error messages can be less complex. Migrating '''correct source code''' forward from the 32-bit version to the 64-bit version is also easier than a reverse migration.

You will also at some point still need to be synched-with or later synch-back-to NARS online source code - i.e. after experimenting/changing local PC source code. This is equivalent to a ChemLab 101 at home/home-office and cleaning up all experiments at the end of the chemistry class, except as it applies to software developers, NARS software developers, and or those inclined to experiment safely.

Here is where Tortoise SVN provides excellent and time-tested source-code clean-up tools for your local PC, including '''Resolve, Revert, Clean up, and Undo changes'''. Pull up these TortoiseSVN utilities by navigating Windows File Explorer to directory C:\NARS2000. If you successfully previously downloaded and Installed TortoiseSVN and NARS2000 source code, as outlined earlier/above, you may right click on say the \trunk subfolder in C:\NARS2000. A mouse right-click on \trunk should show an option labeled TortoiseSVN. Further choosing/selecting TortoiseSVN should then reveal multiple clean up options - Resolve, Revert, Clean up and Undo changes. '''TortoiseSVN Documentation on:''' [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-cleanup.html Clean up.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-revert.html Undo Changes.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-conflicts.html Resolving Conflicts.] 

At least one method to safely synch-back-to NARS is to:
# Select '''TortoiseSVN''' after right-clicking on the trunk folder
# Select '''Revert''', click '''OK''', let it run.
# Select '''Clean up''', check '''Refresh shell overlays''', click '''OK''', let it run.
Per TortoiseSVN there should again be green check marks appearing on your trunk folder as well as your msieve folder.

For revision tracking and long-term software program maintenance purposes: '''Keep track of which files (file names) you personally modify, including a brief purpose''' for that edit. You will need to this information later for Release Notes purposes (see folder C:\NARS2000\trunk\ReleaseNotes for best-practice-examples of developer note-taking) and if you later synch to a new online NARS version, you may have to carry-forward your edit changes into a newly downloaded set of NARS source code files which may or may not reflect your prior local computer edit changes.

==Periodic NARS Updates==

Incremental Update - Method 1: 
Periodically, NARS APL interpreter developers should ensure changes done by other developers get incorporated into their local machine's source code working copy. This is the process of integrating/downloading changes from NARS SourceForge server '''to''' your local copy. Updating may be performed on single files, a set of selected files, or recursively on entire directory hierarchies. To update, select the files and/or '''directories''' you want (usually \trunk and or \msieve), right click and select '''TortoiseSVN → Update''' in the explorer context menu for that trunk or msieve folder. A window will pop up displaying the progress of the update as it runs. Changes done by other developers will be merged into your local files, '''keeping''' any changes you may have done to the same files - if you did not want to keep your local changes but do want to keep the downloaded changes, select TortoiseSVN and Revert '''prior''' to running TortoiseSVN Update. NARS repository at SourceForge is '''not''' affected by an update to your local copy. [http://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-dug-update.html Update Your Working Copy With Changes From Others]

Total Source Code Replacement - Method 2: 
For example from version r1325 to say version r1364 (note a significant revision/datetime gap between 1325 and 1364, hypothetically), whatever NARS latest revision number is. Total code replacement may be preferred over incremental updating when major structural changes or significant source code changes are newly in situ. 
Total Replacement Process: Visually scan NARS source code page at http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ and review the top 25 to 40 file entries or so, while mentally keeping track of the '''highest revision number found'''(e.g. r1379). If after your last/earlier TortoiseSVN Update, your local version number is lower than the latest revision number visually found online, then perform the following to update to the most recent NARS revision:
# Rename your existing NARS folder to something approximating C:\NARS2000_old_rev
# Create an entirely new C:\NARS2000 folder
# '''Copy all folders and files at the top level''' from C:\NARS2000_old_rev folder into C:\NARS2000 '''EXCEPT \trunk and \msieve subfolders (and their contents)'''. The \trunk and \msieve folders will shortly be downloaded from SourceForge.
# Create '''new empty folders called \trunk and \msieve''' in the new C:\NARS2000 folder.
# Revisit the section above called '''[[#Check_Out_The_Source_Code|Check Out The Source Code]]''' to again checkout/download to the absolute latest NARS version number, for both \trunk and \msieve folders.
# Also revisit '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' and text edit file \trunk\wcustomize.bat to localize the new version.
# Folder C:\NARS2000_old_rev may be '''Recycled''' after you are done copying non-trunk and non-msieve files/folders from it into your new C:\NARS2000 folder. If disk space is not restrictive and for 100% safety purposes, keep your prior folder available until after successfully '''Building/Compiling''' the newly downloaded 32-bit and 64-bit versions, and making sure you did not have any local personal changes now potentially being recycled.

Project Ideas

2015-09-26T19:53:28Z

Robert Wallick: ins xref to Developer's Notes

In case you are looking for how to get your feet wet, here are some ideas (in no particular order) to consider implementing:

* [[Partition Operator]]
* [[Power Operator]]
* [[Dual Operator]]
* [[Other System Functions]]
* [[File Systems]]
* [[Trace/Stop Controls]]
* [[Complex Numbers]]
* [[Hypercomplex Numbers]]
* [[Unicode Support]]
* [[Extensible Datatypes]]
* [[Line Continuation Marker]]
* [[Shared Variables]]
* [[Associative indexing]]

See also '''[[Developer's_Notes]]'''.

Developer's Notes

2015-09-26T19:49:52Z

Robert Wallick: wording

The topics in '''red''' (in no particular order) cover some of the areas that '''need documentation''' and or source-code implementation, i.e. no NARS wiki page yet exists for the topic(s). See also '''[[Project_Ideas|NARS Project Ideas]]'''. Feel free to add to the list as you may find appropriate. The topics in '''blue/purple''' are Developer Notes which have been initiated or at least partially and sometimes fully '''documented'''. The word "developer" as used on this wiki page generally refers primarily to APL Interpreter developers, particularly C programmers or persons interested in learning/programming in '''C'''; however, '''APL Developers and Programmers are preeminently''' also invited to submit topics on this wiki page for consideration, review, implementation, etc. See also [http://nars2000.forumatic.com/ NARS Discussion Forum]. 
[Listed below: Task/wiki page - status(if available). Description/explanation]

* [[Symbol and Hash Tables]] - wiki page created. Requires further development
* [[Intellisense - Tries Auto-Completion|Intellisense - Trie Auto-Completion]] - keyboard, autocompletion for APL variable names, function names, labels - contextually relevant suggestions, e.g. Tab-key selected
* [[Datatypes and Storage]]
* [[State Indicator]]
* [[Function Storage]]
* [[Parser]]
* [[Display and Formatting]]
* [[Saved Workspace Structure]]
* [[Building An Executable]] - completed. Building a NARS2000.exe file on your local machine using the latest source code version available at SourceForge.net
* [[Another Approach To Building]] - outdated/potentially obsolete, requires update and or integration.
* [[Creating New System Functions]] - in process. Creating new "quad" <apll>{quad}</apll> system functions for NARS2000.exe
* [[Debugging]]
* [[Committing Changes]]
* [[Reference Counts]]
* [[Tokens]]
* [[Macros]]
* [[Magic Functions]]
* [[VirtualAlloc vs. GlobalAlloc]]
* [[RESDEBUG Cover Functions]]
* [[Per Tab Data]]
* [[Unicode/Wide Chars]]
* [[Undo Buffer]]
* [[Translation on Copy/Paste]]
* [[Source File Formats]]
* [[Programming Practices]]
* [[Threads and Thread Local Storage]]
* [[Window Hierarchy]]

Developer's Notes

2015-09-26T19:41:03Z

Robert Wallick: wording

The topics in '''red''' (in no particular order) cover some of the areas that '''need documentation''' and or source-code implementation, i.e. no NARS wiki page yet exists for the topic(s). Feel free to add to the list as you may find appropriate. The topics in '''blue/purple''' are Developer Notes which have been '''documented'''. The word "developer" as used on this wiki page generally refers primarily to APL Interpreter developers; however, '''APL Developers and Programmers are preeminently''' also invited to submit topics on this wiki page for consideration, review, implementation, etc. See also [http://nars2000.forumatic.com/ NARS Discussion Forum]. 
[Listed below: Task/wiki page - status(if available). Description/explanation]

* [[Symbol and Hash Tables]] - wiki page created. Requires further development
* [[Intellisense - Tries Auto-Completion|Intellisense - Trie Auto-Completion]] - keyboard, autocompletion for APL variable names, function names, labels - contextually relevant suggestions, e.g. Tab-key selected
* [[Datatypes and Storage]]
* [[State Indicator]]
* [[Function Storage]]
* [[Parser]]
* [[Display and Formatting]]
* [[Saved Workspace Structure]]
* [[Building An Executable]] - completed. Building a NARS2000.exe file on your local machine using the latest source code version available at SourceForge.net
* [[Another Approach To Building]] - outdated/potentially obsolete, requires update and or integration.
* [[Creating New System Functions]] - in process. Creating new "quad" <apll>{quad}</apll> system functions for NARS2000.exe
* [[Debugging]]
* [[Committing Changes]]
* [[Reference Counts]]
* [[Tokens]]
* [[Macros]]
* [[Magic Functions]]
* [[VirtualAlloc vs. GlobalAlloc]]
* [[RESDEBUG Cover Functions]]
* [[Per Tab Data]]
* [[Unicode/Wide Chars]]
* [[Undo Buffer]]
* [[Translation on Copy/Paste]]
* [[Source File Formats]]
* [[Programming Practices]]
* [[Threads and Thread Local Storage]]
* [[Window Hierarchy]]

Intellisense - Tries Auto-Completion

2015-09-26T17:52:07Z

Robert Wallick: added quad NL, edit changes

<big>Intellisense - Trie Structure - Auto-Completion</big> for '''APL variable names, function names and labels'''. 

System Programming Task in C: Introduce into NARS: Auto-Completion of variable names, function names, and labels (with the TAB key, for instance). 

# Such a feature might best be an on/off option, such as setting up a keyboard layout, except with the ability to turn it on/off from '''within''' NARS. 
# It should probably be tied in to NARS System Functions ⎕NC and ⎕NL, APL's name classifications and names list functions respectively, ref. '''[http://wiki.nars2000.org/index.php/System_Function_NC NARS Quad NC]''' and '''[http://wiki.nars2000.org/index.php/System_Function_NL NARS Quad NL]'''. 
# It is also called '''Intellisense''' within Microsoft's Visual Studio 20xx and programmatically referred to as a '''Trie''' structure in Computer Science: a Trie, also called digital tree and sometimes radix tree or prefix tree (as they can be searched by prefixes), is an ordered tree data structure that is used to store a dynamic set or associative array where the keys are usually strings, ref. [https://en.wikipedia.org/wiki/Trie Wikipedia entry]. Google's search feature (and Internet Explorer's search box and web pages address textbox) uses the concept, as does the Android OS - particularly for text messaging where word suggestions become invoked for the current [partial] word being typed in and or contextually/definitionally relevant '''suggestions'''. Here is a link to implementing an algorithm, re [http://rmandvikar.blogspot.com/2008/10/trie-examples.html Google Trie example]. 
# Interesting do-it-yourself Intellisense project or DIY Intellisense, ref. '''[http://www.codeproject.com/Articles/5839/DIY-Intellisense Intellisense DIY Code Project]'''. Another C Implementation: '''[http://simplestcodings.blogspot.com/2012/11/trie-implementation-in-c.html Trie implementation in C]'''. Still another C Implementation / C Code for Radix Tree or Trie: '''[http://programminggeeks.com/c-code-for-radix-tree-or-trie/ C code for Radix Tree (or Trie)]'''. 

Actually programming the interface into NARS is not impossible. It would be less easy than implementing a new system quad function into NARS, which can frequently be no easy task in and of itself, but again not impossible. The above hyperlinks were valid as of 9/26/2015.

Intellisense - Tries Auto-Completion

2015-09-26T14:46:24Z

Robert Wallick: Trie Structure: Created page for task

<big>Intellisense - Trie Structure - Auto-Completion</big> for '''APL variable names, function names and labels'''. 

System Programming Task in C: Introduce into NARS: Auto-Completion of variable names, function names, and labels (with the TAB key, for instance). 

# Such a feature might best be an on/off option, such as setting up a keyboard layout, except with the ability to turn it on/off from within NARS. 
# It should probably be tied in to NARS System Function ⎕NC, APL's name classifications function, ref. '''[http://wiki.nars2000.org/index.php/System_Function_NC NARS Quad NC]'''. 
# It is also called '''Intellisense''' within Visual Studio 20xx and programmatically referred to as a '''Trie''' structure in Computer Science: a Trie, also called digital tree and sometimes radix tree or prefix tree (as they can be searched by prefixes), is an ordered tree data structure that is used to store a dynamic set or associative array where the keys are usually strings, ref. [https://en.wikipedia.org/wiki/Trie Wikipedia entry]. Google's search feature uses the concept, as does the Android OS. Here is a link to implementing an algorithm, re [http://rmandvikar.blogspot.com/2008/10/trie-examples.html Google Trie example]. 
# Interesting do it yourself Intellisense project or DIY Intellisense, ref. '''[http://www.codeproject.com/Articles/5839/DIY-Intellisense Intellisense DIY Code Project]'''. Another C Implementation: '''[http://simplestcodings.blogspot.com/2012/11/trie-implementation-in-c.html Trie implementation in C]'''. Still another C Implementation / C Code for Radix Tree or Trie: '''[http://programminggeeks.com/c-code-for-radix-tree-or-trie/ C code for Radix Tree (or Trie)]'''. 

Actually programming the interface into NARS is not impossible. It would be less easy than implementing a new system quad function into NARS, which can frequently be no easy task in and of itself, but again not impossible. The above hyperlinks were valid as of 9/26/2015.

Developer's Notes

2015-09-26T14:25:22Z

Robert Wallick: Trie structure - autocompletion

The topics in '''red''' (in no particular order) cover some of the areas that '''need documentation''' and or source-code implementation, i.e. no NARS wiki page yet exists for the topic(s). Feel free to add to the list as you may find appropriate. The topics in '''blue/purple''' are Developer Notes which have been '''documented'''. The word "developer" as used on this wiki page generally refers primarily to APL Interpreter developers; however, '''APL Developers and Programmers are preeminently''' also invited to submit topics on this wiki page for consideration, review, implementation, etc. See also [http://nars2000.forumatic.com/ NARS Discussion Forum]. 
[Listed below: Task/wiki page - status(if available). Description/explanation]

* [[Symbol and Hash Tables]] - wiki page created. Requires further development
* [[Intellisense - Tries Auto-Completion]] - keyboard, autocompletion for APL variable names, function names, labels
* [[Datatypes and Storage]]
* [[State Indicator]]
* [[Function Storage]]
* [[Parser]]
* [[Display and Formatting]]
* [[Saved Workspace Structure]]
* [[Building An Executable]] - completed. Building a NARS2000.exe file on your local machine using the latest source code version available at SourceForge.net
* [[Another Approach To Building]] - outdated/potentially obsolete, requires update and or integration.
* [[Creating New System Functions]] - in process. Creating new "quad" <apll>{quad}</apll> system functions for NARS2000.exe
* [[Debugging]]
* [[Committing Changes]]
* [[Reference Counts]]
* [[Tokens]]
* [[Macros]]
* [[Magic Functions]]
* [[VirtualAlloc vs. GlobalAlloc]]
* [[RESDEBUG Cover Functions]]
* [[Per Tab Data]]
* [[Unicode/Wide Chars]]
* [[Undo Buffer]]
* [[Translation on Copy/Paste]]
* [[Source File Formats]]
* [[Programming Practices]]
* [[Threads and Thread Local Storage]]
* [[Window Hierarchy]]

Symbol Goto

2015-09-13T14:44:29Z

Robert Wallick: Added see also

__NOTOC__
<h1> {goto} — Branch to a line in a function — Keystroke ALT+] — Character 8594 or 0x2192</h1>
[[File:APLKB-Goto.png]]
==Alternate Names==
This symbol is also known as <big>right arrow</big> or APL text symbol '''{rightarrow}'''.

==Usage==
The goto symbol may be used as a conditional branch (branch based on a comparison) or an unconditional branch, or it may be used to exit a function. It is most often used in a function to transfer control, but can be used from the session manager to transfer to a line in a suspended function.

===Conditional branch===
The value to the right of the arrow is a boolean expression or non-negative number surrounded by parentheses, followed by a slash symbol and the line number to transfer to if the expression is true for a boolean expression or nonzero for a numeric value. A DOMAIN ERROR occurs if the numeric value is negative. In the following line 5 of a function:
:'''<tt> [5] {rightarrow}(A{lessthan}1)/22</tt>'''
Will branch to line 22 of the function if the value of A is less than 1. Execution would continue on line 6 if A was 1 or more.

 As per the example from above, there are syntactically three parts to a conditional branch:
# Leftmost, the branch symbol itself, '''{rightarrow}'''
# Boolean test to perform, usually within parentheses, '''(A{lessthan}1)'''
# Statement number or label to go to if the test within parentheses is true(1), '''/22''' - note use of the reduction or slash symbol.

 The test inside the parentheses may be '''simple''', as per the above example. The branch's boolean test may also be '''compound''', ref. the following:
 
:<tt> '''{rightarrow}((A{lessthan}1){downcaret}(A{morethan}10))/OR_Case'''</tt>
In this example if '''A''' is less than 1 OR '''A''' is greater than 10, the user function will branch to line label '''OR_Case:''' in the function. This occurs because if either test is true, the compound test evaluates to true - union of 2 tests(boolean 1 in either test results in a branch). 
Another compound or dual boolean test, this time a boolean AND: 
:<tt> '''{rightarrow}((A{lessthan}1){upcaret}(A{morethan}-10))/AND_NegativeCase'''</tt>
Branching will occur only if BOTH tests evaluate to true. The user function will go to line label AND_NegativeCase: in the function only if (-10<A<1) or if '''A{epsilon}(-9 -8 -7 -6 -5 -4 -3 -2 -1 0}''' - intersection of 2 tests(boolean 1 if BOTH tests evaluate to true results in a branch).
 
In setting up boolean '''go to''' tests also bear in mind use of APL's '''{tilde}''' or '''not''' symbol, thus: 
:'''<tt> [5] {rightarrow}({tilde}A{lessthan}1)/22</tt>'''
Thus APL would go to line number 22 only if A is greater than or equal to 1.
 

===Unconditional branch===
The goto symbol is followed on the right either by the line number or a label. Execution continues in the function at that line (unless the line specified is 0, in which case the function exits.)

===Exit Function===
The goto symbol may be used to exit a function and return to the calling function (or return to the session manager if the function was called by the user typing its name) by using 0 as the line number to goto. This is the same as <tt>:return</tt>

==Examples==

===Exit Function===
In the following example, [[function]] one calls function two, which exits part way through the function, returning to function 1.
<tt>
:{delta}one 
[0] one 
[1] 'This is one' 
[2] two 
[3] 'return to one from two'
:{delta}

:{delta}two
[0] two 
[1] 'This is two' 
[2] {goto}0 
[3] 'Two Continues'
:{delta}

:one
This is one 
This is two 
return to one from two
</tt> 
<big>Another Example see: '''[[Control_Structures#Cases_Branching_Example_1|Control Structures - Branching Example]]'''</big>
 
<big>See also: '''[[Symbol_Tilde|Symbol Tilde or Not]] and [[Symbol_Slash|Symbol Slash or Reduce]]'''</big>
 
{{Article footer}}
{{Symbol footer|1|G}}

Symbol Goto

2015-09-13T14:35:43Z

Robert Wallick: /* Conditional branch */ expanded conditional branch, added compound boolean test examples, tilde

__NOTOC__
<h1> {goto} — Branch to a line in a function — Keystroke ALT+] — Character 8594 or 0x2192</h1>
[[File:APLKB-Goto.png]]
==Alternate Names==
This symbol is also known as <big>right arrow</big> or APL text symbol '''{rightarrow}'''.

==Usage==
The goto symbol may be used as a conditional branch (branch based on a comparison) or an unconditional branch, or it may be used to exit a function. It is most often used in a function to transfer control, but can be used from the session manager to transfer to a line in a suspended function.

===Conditional branch===
The value to the right of the arrow is a boolean expression or non-negative number surrounded by parentheses, followed by a slash symbol and the line number to transfer to if the expression is true for a boolean expression or nonzero for a numeric value. A DOMAIN ERROR occurs if the numeric value is negative. In the following line 5 of a function:
:'''<tt> [5] {rightarrow}(A{lessthan}1)/22</tt>'''
Will branch to line 22 of the function if the value of A is less than 1. Execution would continue on line 6 if A was 1 or more.

 As per the example from above, there are syntactically three parts to a conditional branch:
# Leftmost, the branch symbol itself, '''{rightarrow}'''
# Boolean test to perform, usually within parentheses, '''(A{lessthan}1)'''
# Statement number or label to go to if the test within parentheses is true(1), '''/22''' - note use of the reduction or slash symbol.

 The test inside the parentheses may be '''simple''', as per the above example. The branch's boolean test may also be '''compound''', ref. the following:
 
:<tt> '''{rightarrow}((A{lessthan}1){downcaret}(A{morethan}10))/OR_Case'''</tt>
In this example if '''A''' is less than 1 OR '''A''' is greater than 10, the user function will branch to line label '''OR_Case:''' in the function. This occurs because if either test is true, the compound test evaluates to true - union of 2 tests(boolean 1 in either test results in a branch). 
Another compound or dual boolean test, this time a boolean AND: 
:<tt> '''{rightarrow}((A{lessthan}1){upcaret}(A{morethan}-10))/AND_NegativeCase'''</tt>
Branching will occur only if BOTH tests evaluate to true. The user function will go to line label AND_NegativeCase: in the function only if (-10<A<1) or if '''A{epsilon}(-9 -8 -7 -6 -5 -4 -3 -2 -1 0}''' - intersection of 2 tests(boolean 1 if BOTH tests evaluate to true results in a branch).
 
In setting up boolean '''go to''' tests also bear in mind use of APL's '''{tilde}''' or '''not''' symbol, thus: 
:'''<tt> [5] {rightarrow}({tilde}A{lessthan}1)/22</tt>'''
Thus APL would go to line number 22 only if A is greater than or equal to 1.
 

===Unconditional branch===
The goto symbol is followed on the right either by the line number or a label. Execution continues in the function at that line (unless the line specified is 0, in which case the function exits.)

===Exit Function===
The goto symbol may be used to exit a function and return to the calling function (or return to the session manager if the function was called by the user typing its name) by using 0 as the line number to goto. This is the same as <tt>:return</tt>

==Examples==

===Exit Function===
In the following example, [[function]] one calls function two, which exits part way through the function, returning to function 1.
<tt>
:{delta}one 
[0] one 
[1] 'This is one' 
[2] two 
[3] 'return to one from two'
:{delta}

:{delta}two
[0] two 
[1] 'This is two' 
[2] {goto}0 
[3] 'Two Continues'
:{delta}

:one
This is one 
This is two 
return to one from two
</tt> 
'''Another Example see: [[Control_Structures#Cases_Branching_Example_1|Control Structures - Branching Example]]'''

{{Article footer}}
{{Symbol footer|1|G}}

Platforms

2015-09-02T09:43:36Z

Robert Wallick: added TeamViewer / remote desktop software

Although NARS2000 is primarily established as a Windows-based program for both 32- and or 64-bit systems, it can be usable on a variety of platforms.

The current version of NARS2000 may be run on a variety of Windows platforms, including most or all post-Windows-98 OS versions. Furthermore, a long-term goal is to enable NARS to be built on Linux, Mac OS, etc. as per user requests and Developer interests. If you do not have a Windows machine, the following may be helpful to you:

'''[http://www.howtogeek.com/187359/5-ways-to-run-windows-software-on-a-mac/ Five ways to run Windows software on a Mac.]''' From HowToGeek.com, methods include 1)Virtual Machines, 2)Boot Camp, 3)Wine, 4)CrossOver Mac (not free) and 5)Remote Desktop.

'''[http://www.howtogeek.com/133515/4-ways-to-run-windows-software-on-linux/ Four ways to run Windows software on Linux.]''' Again from HowToGeek.com, methods include 1)Use Wine, 2)Run Windows in a Virtual Machine, 3)Try Crossover (not free) and 4)Remote Desktop. A fifth way per [http://www.pcworld.com/article/2900497/how-to-run-windows-software-in-linux-everything-you-need-to-know.html PC World] is dual booting both Linux and Windows on your machine. This essentially involves partitioning hard drives with a portion reserved for Linux and a portion reserved for Windows. With costs of external hard drives continuing to decline, buying an external or network hard drive may free up hard drive storage space requirements.

'''[http://www.howtogeek.com/173353/how-to-run-windows-software-on-a-chromebook/ How to Run Windows Software on a Chromebook {notebook or tablet PC}.]''' Again from HowToGeek.com, methods include 1)Access a Windows Desktop Remotely, 2)Use Developer Mode and Install Wine (not available for all Chromebooks), 3)Use Developer Mode and Install a Virtual Machine (may require an Intel Chromebook).

Furthermore, if you work using a tablet or other computing device which supports remote desktop software such as '''[http://teamviewer.com Team Viewer]''' and you have a home or work computer running Windows - then you can remotely use NARS over your network and internet using that computer as a host and your local device as a client. Network and internet speeds are sufficiently fast and TeamViewer, for instance, is very good at making your remote desktop seem and respond as if virtually right in front of you.

==Wine = "Wine Is Not an Emulator"==

However that doesn't mean it can't run on other operating systems such as Linux or Mac OS thanks to a translation layer program such as [http://www.winehq.org Wine]. From the WineHQ website

"Wine is a translation layer (a program loader) capable of running Windows applications on Linux and other POSIX compatible operating systems. Windows programs running in Wine act as native programs would, running without the performance or memory usage penalties of an emulator, with a similar look and feel to other applications on your desktop."

Indeed, NARS2000 has been tested running under Wine on Linux-based systems without a hitch.

==Mac OS==

NARS2000 has yet to be tested on Mac OS. Although that OS isn't as yet officially supported by the Wine developers, there are [http://wiki.winehq.org/MacOSX instructions] for installing Wine and running programs under it.

==How To Run NARS2000 Under Wine==

To run NARS2000 on your non-Windows operating system, go to the [http://www.winehq.org/download/ download] section of the Wine website and download a binary version of Wine appropriate to your system, [http://winehq.org/site/docs/wineusr-guide/getting-wine install] it, [http://www.nars2000.org/download download] the latest version of NARS2000, unzip it, and run it as

<pre>wine NARS2000.exe</pre>

Building An Executable

2015-09-02T09:41:16Z

Robert Wallick: /* Platforms */ added TeamViewer / remote desktop software

<div style="float:right; padding-left:5px;">
{| style="text-align:left; border:1px solid #aaaaaa; background-color:#f9f9f9;width: 200px;font-family: Verdana, sans-serif;"
|- padding:5px;padding-top:0.5em;font-size: 95%;
|
----
<div style="border:1px solid #ccc; background: #fff; border-right:3px solid #ccc; border-bottom:3px solid #ccc; text-align: center; padding:3px; float:right; font-size: smaller; line-height: 1.3; margin-right: 4px;">
<div style="width:100%">{{CURRENTDAYNAME}}</div>
<div style="font-size: x-large; width: 100%;">{{CURRENTDAY}}</div>
<div style="width: 100%;"> {{CURRENTMONTHNAME}}</div>
<div style="width: 100%;">{{CURRENTYEAR}}</div>
<div style="background: #aaa; color: #000;">'''{{CURRENTTIME}}''' UTC</div>
</div>
<big>'''NARS2000 Building The Executable'''</big>
----
<div style="text-align:center;">
</div>
|-
|
__TOC__
|}
</div>
==Update Notice==

NARS Conversion from Visual Studio 2008 to Visual Studio 2013 is complete! All source code compiles correctly and multiple APL workspaces have been tested for correct APL/NARS functionality. This page is current, up-to-date re NARS working with VS2013's compiler and standards. The conversion to VS2013 results in a more up-to-date (5 years more current software technology) program for the GUI Builder and Compiler interface, including newer C/C++ programming standards. This has represented a major cyclical software upgrade and results in greater APL user functionality via improved C coding. The recent Beta releases of NARS2000.exe (32 and 64-bit versions) are fully functional.
<div align="right">v---- '''Useful Developer links:''' ----v [http://svnbook.red-bean.com Version Control with Subversioning - Conceptual Gen Bkgnd.] [http://sourceforge.net/p/forge/documentation/svn/ Source Forge Versioning Documentation] [http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ Source Forge NARS2000 Source Code]</div>

==Why Build Your Own==

First of all, you do not have to build your own. NARS has already created a great existing Nested Arrays Research System APL interpreter. NARS2000.exe is freely available at [http://www.nars2000.org/download/Download.html NARS Downloads]. Downloads includes Beta releases for APLers so inclined.

On the other hand, why not expand your programming/software and computer skill horizons? Many people think and believe '''Kenneth Iverson's''' work remains that of a true genius, a bright light among some very bright intellectual lights, both from a theoretical as well as a software implementation perspective. Here's your opportunity to attempt to improve upon some very substantive, preexisting software development work - to further it, to make it even better, and perhaps best of all - '''it's free'''.

Personalize some already pretty amazing software for yourself, or share it with others and get '''their feedback''' for even greater insight and subsequent improvement. NARS version of APL already has over a quarter million lines of source code, subroutines, macros, functions, etc. - 50 years of sometimes intense and continuing evolution, so you are not creating something from undeveloped scratch, but inheriting and working from already highly evolved, rigidly disciplined concepts and rigorously debugged software over time.

'''APL/2''' has been used in physics, science, genetic engineering-DNA studies, advanced mathematics, robotics, engineering, artificial intelligence, image processing, bio-medicine, VLSI, financial, statistical and social science applications. NASA and Astronomers have used APL.

Now APL/2 is 100% customizable. Perhaps you will be the first to customize APL to safely drive a vehicle, help save a life, make new discoveries or make some process(es) more efficient.

It's '''free'''. It's '''evolved'''. Once you start examining NARS/APL/APL2 source code you'll find it is comprehensive, elegant, process-symbol-efficient, focused toward the end-user, evolved over some fifty years of use, structurally enigmatic, tirelessly debugged and rich with coding techniques - a great learning tool, even if absolutely nothing else - and NARS believes it is far, far better than just a learning tool. You'll learn about Bison Parsing, how it helps define compilers and interpreters. Further, NARS is a tremendous opportunity to learn more about the human-machine interface; how machine hardware operates and - better understand how software and hardware interact together.

One of the stellar, intellectually expansive aspects of APL/2 is - how fully the language embraces the breadth of hardware functionality. This includes instructions running core processor chip(s) and peripheral devices. This is not your grandparents' punch-card software program run on a room-sized computer, although that was marvelous at its time, but it may have taken him/her several days to get results back for in an introductory chemistry or math lab course. Today '''[http://phys.org/news/2015-03-quantum-unexpected-ways.html data structures influence speed of quantum search in unexpected ways]'''.

==Platforms==

The current version of NARS2000 may be run and built on a variety of Windows platforms, including most or all post-Windows-98 OS versions. Furthermore, a long-term goal is to enable NARS to be built on Linux, Mac OS, etc. as per user requests and Developer interests. If you do not have a Windows machine, the following may be helpful to you:

'''[http://www.howtogeek.com/187359/5-ways-to-run-windows-software-on-a-mac/ Five ways to run Windows software on a Mac.]''' From HowToGeek.com, methods include 1)Virtual Machines, 2)Boot Camp, 3)Wine, 4)CrossOver Mac (not free) and 5)Remote Desktop.

'''[http://www.howtogeek.com/133515/4-ways-to-run-windows-software-on-linux/ Four ways to run Windows software on Linux.]''' Again from HowToGeek.com, methods include 1)Use Wine, 2)Run Windows in a Virtual Machine, 3)Try Crossover (not free) and 4)Remote Desktop. A fifth way per [http://www.pcworld.com/article/2900497/how-to-run-windows-software-in-linux-everything-you-need-to-know.html PC World] is dual booting both Linux and Windows on your machine. This essentially involves partitioning hard drives with a portion reserved for Linux and a portion reserved for Windows. With costs of external hard drives continuing to decline, buying an external or network hard drive may free up hard drive storage space requirements.

'''[http://www.howtogeek.com/173353/how-to-run-windows-software-on-a-chromebook/ How to Run Windows Software on a Chromebook {notebook or tablet PC}.]''' Again from HowToGeek.com, methods include 1)Access a Windows Desktop Remotely, 2)Use Developer Mode and Install Wine (not available for all Chromebooks), 3)Use Developer Mode and Install a Virtual Machine (may require an Intel Chromebook).

Furthermore, if you work using a tablet or other computing device which supports remote desktop software such as '''[http://teamviewer.com Team Viewer]''' and you have a home or work computer running Windows - then you can remotely use NARS over your network and internet using that computer as a host and your local device as a client. Network and internet speeds are sufficiently fast and TeamViewer, for instance, is very good at making your remote desktop seem and respond as if virtually right in front of you.

For the present, the following sections detail descriptions for building the executable with bias towards Windows.

==Downloads==

To build the executable in summary you'll need the following:

# C Compiler and Linker
## Make program
## Resource Compiler
## Windows SDK
# Parser Generator
# Zip Utility
# PHP (Hypertext Preprocessor)
# NARS2000 Source Code
# NARS2000 External Libraries
# Optionally, Multi-precision Library Source
# STDINT.H header file
# Version Control program
# Doctor Dump SDK
# Optionally, a File Differencing/Merge program
 All of the tools you'll need are '''freely available'''. Some of them happen to be Microsoft-specific. Bill Gates while at Harvard actually worked a bit on/with APL, obviously he discovered the importance of working with arrays and symbolic notation. At the same time there is no reason more generic tools (such as [http://www.delorie.com/djgpp/ DJGPP], [http://www.cygwin.com/ Cygwin] or [http://www.mingw.org/ MinGW]) can't be used, a task NARS is hoping someone will volunteer to investigate. In particular, the '''tools currently used''' to create the APL Executable, in detail, are as follows:
 
# '''C''' (needed for this NARS2000 project is '''Visual C++ 2013''' = C++ GUI development environment and compiler for the C language, which much of APL's interpreter is written in). Compiler and Linker: '''[https://app.vssps.visualstudio.com/profile/review?download=true&family=VisualStudioExpressDesktop&release=VisualStudio2013Upd4&type=web&slcid=0x409 Microsoft Visual Studio 2013 Express for Desktop Windows]''' (download requires a FREE Microsoft/Visual Studio account) OS requires Windows XP or later — includes Link, Make, a Resource Compiler, and an SDK (among others). Download/Installation Notes: The '''downloaded file''' may be double-clicked in Windows Explorer. VS 2013 does NOT Install to a mapped or network drive(but to something like C:\Program Files\...). It must be Installed on a local PC drive (e.g. C:\...) and '''unmapped directory''' (but you can map to it later) - Microsoft apparently requires installation to a local machine drive letter such as "C:\...".   VS2013 Desktop is free '''and''' it includes a GUI or graphical user interface (icon-based IDE or integrated developer's environment), which is geometrically easier to use than a command-line interface. Windows 8.1 SDK (does NOT require Windows 8.1, but does update for some 8.1 capabilities, especially useful for using Visual Studio 2013; '''[https://msdn.microsoft.com/en-us/windows/desktop/bg162891.aspx?f=255&MSPPError=-2147217396 download is available at Microsoft]'''. '''Windows SDK''' (the following MAY NOT BE NECESSARY, SDK=Software Developers Kit, sometimes needed for '''64-bit installations''', usually choose download file GRMSDKX_EN_DVD.iso even for Intel machines) '''[http://www.microsoft.com/en-us/download/details.aspx?id=18950 download here]''', with '''installation instructions [https://github.com/enGits/engrid/wiki/Configure-Microsoft-Visual-Studio-2008-Express-to-also-build-for-Windows-x64 here]'''.
# '''Parser Generator''': '''[https://cygwin.com/install.html Bison]''', a Cygwin package, Save and run either '''setup-x86.exe''' (32-bit systems) or '''setup-x86_64.exe''' (64-bit systems) as appropriate to your system, '''Choose A Download Source''': Install from Internet, '''Select Root Install Directory''', '''Select Local Package Directory''', '''Select Your Internet Connection''', '''Choose A Download Site''', '''Select Packages''': Leave alone '''All (Default)''' - first time through, just click [Next], '''Devel''', and '''bison''', other dependent packages may be installed along with '''bison''', if not then '''after first''' Cygwin installation finishes, double-click the downloaded Cygwin file in Windows Explorer, downloaded filename should be something like '''setup-x86_64.exe''' and the '''second time through''' do specifically download and install '''Dev''', '''Bison''' - informally note the '''tree structure''' during the Bison download/install since '''creating parse trees''' is '''very much''' a ''Bison program specialty'', a strength. Compilers and even APL itself relies heavily on correct statement type recognition and parsing. To make sure you successfully downloaded and installed '''bison.exe''', the file should be '''found''' or reside in the C:\Cygwin\bin or C:\cygwin64\bin folder. Make note of the folder location since you will need it when setting the PARGEN environment variable shortly, below.
# '''Zip Utility''': '''[http://www.7-zip.org/ 7-Zip]''' (Latest version, 32- or 64-bit, as appropriate to your system; needed to Extract/Unzip the files and folders you are downloading for this project.) If you already have a Zip utility program on your PC, Tablet or Server such as WinZip, you can normally skip the 7-Zip download/install.
# '''PHP''' (Hypertext Preprocessor): '''[http://www.php.net/downloads.php Downloads]''' (Windows downloads for Windows systems.) (Windows binaries/VC9 x86 Thread Safe/Latest version/Zip or Installer, your choice) (Items to Install: Entire '''Script Executable''', and entire '''Extras'''). Place the unzipped file's contents into something like "C:\PHP". The executable file "php.exe" needs to be "on your directory or environmental path" when later compiling or building the APL executable.
# '''NARS2000 Source Code''': Click on '''[http://sourceforge.net/projects/nars2000/ Browse Code] button''' at '''NARS''' SourceForge.net '''code repository'''. You may also use a Version Control program, e.g. see Tortoise SVN below and [http://tortoisesvn.net/ here, see their download page]. '''Prior''' non-current NARS Source Code versions available at [http://code.google.com/p/nars2000/source/checkout Code Google].
# '''NARS2000 External Libraries''': [http://www.nars2000.org/download/binaries/misc.zip Miscellaneous Library] (misc.zip, which contains 4 .php files and 1 .ttf file - all directly unzipped into C:\NARS2000) and the following NARS libraries:
## [http://www.nars2000.org/download/binaries/mplibs.zip '''MPIR/MPFR/ECM Libraries'''] - These libraries(mplibs.zip) should be directly extracted or unzipped into the C:\NARS2000 folder such that three(3) distinct sub-directories are '''directly''' created: \ecm, \mpfr and \mpir, e.g. C:\NARS2000\ecm.
## [http://www.nars2000.org/download/binaries/gsldir.zip '''gsl Library'''] - This library(gsldir.zip) should be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\gsl'''. Folder structure "C:\NARS2000\gsldir\gsl" would be invalid.
## [http://www.nars2000.org/download/binaries/qdebug.zip '''qdebug Library'''] - This library(qdebug.zip) should also be directly un-zipped into the C:\NARS2000 folder such that it becomes '''C:\NARS2000\qdebug'''. Make sure it is NOT double-enclosed when unzipped, for example the following would be an invalid folder setup structure: C:\NARS2000\qdebug\qdebug.
# '''Multi-precision Library Source Code: [http://www.nars2000.org/download/binaries/mpfns-src.zip MPIR/MPFR/ECM Source]'''. This zipped download is large (roughly 0.5GB) and is needed primarily to reproduce files in the MPIR/MPFR/ECM Library download so as to satisfy requirements of the GNU General Public License (GPL) v3. For more details on using the files in the download, look in the zipped file for <code>readme.txt</code>. If you are content to use the already-compiled existing binary libraries in [http://www.nars2000.org/download/binaries/mplibs.zip MPIR/MPFR/ECM Libraries], you may not immediately need the MPIR/MPFR/ECM Source Code; on the other hand - 128-bit CPU chips are in manufacturing production pipelines, quadruple-precision 128-bit floating-point format has been standardized by the IEEE and ultra-precise calculations are already needed in such fields as quantum physics, ref. [http://phys.org/news/2014-06-physicists-quantum-ultra-precise.html Physicists take quantum leap toward ultra-precise measurement], 6/2/2014. One of APL's strengths is its handling of mathematically precise calculations and the '''large size''' of the multi-precision source code library reinforces that.
# [http://msinttypes.googlecode.com/svn/trunk/stdint.h STDINT.H] header file installed in the MS Visual Studio 2013 include directory (V:\VC\include -- see below)
# '''SubVersion Control program''': [http://tortoisesvn.net/downloads Tortoise SVN] (Current version, 32- or 64-bit depending upon your OS)
# '''Doctor Dump SDK''': [https://drdump.com/public/DoctorDumpSDK/DoctorDumpSDK.zip Doctor Dump SDK] - e.g. DoctorDumpSDK.zip.
# '''File Differencing/Merge program''': [http://winmerge.org/ WinMerge] ('''Latest stable version''', usually downloads to something like WinMerge-k.m.n-Setup.exe where k, m and n are version/sub-version numbers.)

==Install Tools==

'''Preface''', Convention: '''x86''' generally refers to '''32-bit''' software installations while 64 (or blank) represents 64-bit software installations on a Windows OS machine. NARS works on '''both''' 32-bit and 64-bit systems, but you should decide '''in advance''' which type of install you want 64 vs. 32-bit - ditto for all tool installs. Installation examples:
# C:\Program Files (x86)\        Represents 32-bit software program installation, normal folder location.
# C:\Program Files\                 Represents 64-bit software program installation, normal folder location.
Also, '''both''' folder locations just above frequently and even always exist on most machines, but for consistency and integration purposes the software should be 32 '''or''' 64-bit. Most people choose 64-bit installs if their Windows OS supports the 64-bit architecture, with 32-bit available for backward software compatibility in conjunction with less current systems. If you don't know which architecture your system uses, go to the Control Panel, System Information. Downloads usually get placed into a Downloads folder. Several of the unzipped NARS tools get placed directly into the C:\NARS2000 folder, see individual tools for exact locations. 

To install the Microsoft '''Visual Studio 2013 Express C compiler''', see Downloads(detail, #1 above). Visual C++ 2013 usually installs into something like, "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" (64-bit loc) and you may want to place a '''Shortcut''' to '''VCExpress.exe''' on your Desktop by right-clicking on that VCExpress.exe file in Windows Explorer and Send To - Desktop (create shortcut). (Windows 8 Users: You can also '''Pin VCExpress.exe To your Taskbar''' for quick, easy access.) (Prior/obs. Microsoft setup routine name: run the vcsetup.exe program.) Afterwards including after drive plus folder remapping - the files '''msobj80.dll''', '''mspdb80.dll''', '''mspdbcore.dll''', and '''mspdbsrv.exe''' all need to be copied from '''V:\Common7\IDE''' to '''V:\VC\bin''', where the '''V''' drive is a substitute/mapping for '''C:\Program Files\Microsoft Visual Studio 9.0'''. See the discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

To install the Parser Generator (Bison), see the instructions above. When the Cygwin setup program asks you to choose a '''Default Text File Type''', choose '''DOS/text''' so any committed files are the same as in the version control repository.

To install Doctor Dump SDK, unzip it in a directory at or above %NARSROOT%, this usually means unzipping into folder C:\DoctorDumpSDK. See also discussion below on [[#Set_Up_Makefile_Environment_Variables|Set Up Makefile Environment Variables]].

Install the rest of the tools as per their instructions above, in the Downloads section.

==Install The Source Code==

<ol>
<li>First create a NARS2000 '''root folder''' somewhere on one of your hard drives, perhaps calling it '''NARS2000''', as in '''C:\NARS2000''' (most common) or perhaps at some lower level. The source code and external libraries are typically installed at or into this level, e.g. qdebug.zip into C:\NARS2000 as C:\NARS2000\qdebug.</li>
<li>Under the root folder make three folders: '''trunk''', '''msieve''', and '''branches'''. The first folder ('''trunk''') will hold the main body of NARS/APL built exe interpreter '''source''' code. The second ('''msieve''') will be utilized for code used to '''factor numbers''', and the third ('''branches''') will contain individual developer branches of the main code not as yet ready for release, but made public for other developers to see.</li>
<li>Using a Version Control program such as '''TortoiseSVN''', download-checkout the source code (see [[#Check_Out_The_Source_Code|Check Out The Source Code]]),</li>
<li>Download the '''misc.zip''', '''qdebug.zip''', '''gsldir.zip''', and '''mplibs.zip''' files into the root folder and unzip them (directly into that root folder, e.g. C:\NARS2000) using e.g. '''7z.exe''' (unzip/extract program used) as in '''7z x misc.zip''', '''7z x qdebug.zip''', '''7z x gsldir.zip''', and '''7z x mplibs.zip''' - or double-click on those downloaded zip file names using Windows File Explorer and Extract All (again typically directly into NARS root folder previously set up).</li>
</ol>

==Check Out The Source Code==

An easy way to initialize your copy of the source code for the first time, although it may initially appear cumbersome to an SVN newcomer, is to use a version control program such as TortoiseSVN, mentioned above. One very helpful feature of TortoiseSVN is that it integrates well with Windows File Explorer. After downloading and installing TortoiseSVN and then rebooting your PC, there are two directories you will need to Install/initialize-checkout/TortoiseSVN-on.
# '''First''' bring up Windows Explorer, right-click on the '''trunk''' folder you manually created, and choose '''SVN Checkout'''. The online NARS URL of repository: is '''svn://svn.code.sf.net/p/nars2000/code/trunk''' and your local Checkout directory: is '''C:\NARS2000\trunk''' (or wherever your trunk folder is) - quite likely you will have to edit the TortoiseSVN repository field or program local folder field because default text inserted by TortoiseSVN usually does not match folder location(s) identically. Depth should show Fully recursive, the default. To begin source code downloading/checkout into your locally created '''trunk''' folder click the '''OK''' button. Code downloading/checkout should then begin. With a high-speed Internet connection, time required to TortoiseSVN download/checkout NARS code is on the order of roughly two minutes. When successfully complete, you should get a return message at the end of the downloads list, like '''Completed at revision nnnn'''.
# '''Second''' (and this is a similar repeat step but using folder '''msieve''' instead of trunk), bring up Windows Explorer, right-click on the '''msieve''' folder you likewise manually created - and choose '''SVN Checkout...'''. This time online NARS '''URL of repository:''' is '''svn://svn.code.sf.net/p/nars2000/code/msieve''' (this address is slightly different than step 1) and your local '''Checkout directory:''' is '''C:\NARS2000\msieve''' (or wherever your '''msieve''' folder is). Again, depth should be fully recursive and click the '''OK''' button to begin. This step two normally completes in under five seconds, downloading far fewer files than the trunk download. Normally, the same msieve revision number should appear after finishing this download as per trunk download in step 1.

The above '''two''' steps/distinct-folders need be initialized this first checkout time through - in order to establish the special hidden SVN directories for subversion "synching" between your local source code and NARS online code repository. As a brief check that your '''local''' NARS source code files match NARS, there should be green check marks on folders trunk and msieve on your PC, placed there by TortoiseSVN. [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-wcstatus.html TortoiseSVN Status Information.]

You will still or now need to download and unzip '''qdebug.zip''', '''misc.zip''', '''gsldir.zip''', and '''mplibs.zip''' as described above.

Subsequently, you may quickly and easily update your local copy of NARS source code by right-clicking on the '''trunk''' and/or '''msieve''' folders and choose '''SVN Update'''. One useful feature of sub-versioning programs such as TortoiseSVN is that only '''changed files''' from the online latest official version will need to be subsequently downloaded as changes are made in futuro, re subsequent NARS revisions.

Since you may be unfamiliar with the download process your first time through, it make take slightly longer; however, the second or third time you Check Out The Source Code, over time, the entire "update to most current NARS source code revision" process will probably take under 3 to 5 minutes total, depending however on your (high-speed) Internet service provider's(ISP) download speed.

==Folders==

After unzipping the above files, the structure under the '''NARS2000 root folder''' should look very much like the following('''leftmost column'''), where lower level sub-directories and individual sub-folder file names have been omitted:
{|class="wikitable"| style="width: 40%; border:1px dotted blue;"
!'''NARS2000''' SubFolder:
! Downloaded Zip '''Source''' File or Checkout Process:
|-
| branches\
| class="Unicode" style="text-align:center;" | Created manually(1)
|-
| ecm\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| gsl\
| class="Unicode" style="text-align:center;" | '''gsldir'''.zip
|-
| mpfr\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| mpir\
| class="Unicode" style="text-align:center;" | '''mplibs'''.zip
|-
| msieve\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''msieve'''
|-
| qdebug\
| class="Unicode" style="text-align:center;" | '''qdebug'''.zip
|-
| trunk\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\binaries\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\Extensions\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\htdocs\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\images\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\MediaWiki\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\ReleaseNotes\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
| trunk\WineHQ\
| class="Unicode" style="text-align:center;" | TortoiseSVN Checkout '''trunk'''
|-
|}
(1) Subfolder '''\branches''' should be '''created manually''' (e.g. Windows Explorer, right-click, New, Folder). It is used to hold subprojects you may develop. For example if your name is Bill Gates, you might have the following subfolders, each representing a NARS subproject: 
C:\NARS2000\branches\bgates\NARS_Spreadsheets 
C:\NARS2000\branches\bgates\NARS_WordProcPlusAPLEdits 
C:\NARS2000\branches\bgates\EZMenus 
C:\NARS2000\branches\bgates\Graphics 

==Choose How To Build==

The following sections describe two alternate ways to build the executable. One is the GUI interface of VC++ Express, the other is a command line interface using a '''makefile'''.

==Set Up VC++ Express==

If you are using VC++ Express, the project file is in the '''trunk''' folder and is called '''NARS2000.vcproj'''. You may load it manually every time you invoke VC++ Express, or you may load it automatically by placing the path to the project file on the command line in the VC++ Express shortcut as in '''"C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" C:\NARS2000\trunk\NARS2000.vcproj''' or wherever you defined your NARS2000 root folder.

The vast majority of the project settings are found in the above file with some exceptions.

==Set Up Makefile and Environment Variables==

<hr width=25%>
'''Windows 8''': Setting up Environment and Path Variable(s):
Under Settings, Control Panel, System and Security, System, Advanced System Settings, Advanced (Tab) '''or''' in Control Panel Search for '''Environment Variables''',
* Click '''Environment Variables''' button - There is both a '''Temp Variable''' and '''Path Variable'''.
:: There are 2 sections, User Account Variables and System Variables. You normally want to add new '''System Variables'''.
::: Click '''[New]''' button for a New System Variable:
:::: Variable name       '''PARGEN'''
:::: Variable value       '''C:\cygwin64\bin\bison'''       << typical for a 64 bit install(for bison.exe in subfolder bin), for 32 bits installs see below for variable '''set''' values.
* Normally add a '''New''' variable (var Name plus Value) for each of the '''eight Set''' vars commands listed below, 8 environment variable names - such as NARSROOT, CS_DIR, ZIPPRG, PARGEN, etc.
* If you need to add another Path to an existing variable, each new or added path is separated with a semi-colon.
* After updating any Environment/Path variable(s) you apparently need to reboot since the above variable changes only affect changes in the Registry until PC is rebooted.
* The instructions below should also or alternatively work.
<hr width=25%>
If you are building from the '''makefile''' or working with the GUI C++ Compiler, you'll need to set '''eight environment variables''' in your '''autoexec.bat''' file ('''or''' see just above for setting Environment Variables via '''Windows Control Panel'''). Note that ''Environment variable #n's'' just below are shown only for helpful reference purposes.
<pre>
REM Path of the root of the NARS2000 project *ending with a backslash*
Set NARSROOT=C:\NARS2000^\                         Environment variable #1

REM Path to Doctor Dump SDK root
Set CS_DIR=C:\DoctorDumpSDK^\                      Environment variable #2

REM Path and name of zip program (7-Zip)
Set ZIPPRG="C:\Program Files\7-Zip\7z"             Environment variable #3

REM Path and name of parser generator (bison)      Environment variable #4 (next line)
Set PARGEN=C:\Cygwin\bin\bison         OR for a 64-bit install >>   Set PARGEN=C:\cygwin64\bin\bison

REM Path and name of makedep program
Set MAKEDEP=%NARSROOT%makedep.php                  Environment variable #5

REM Path and name of the <makepro.php> program
Set MAKEPRO=%NARSROOT%makepro.php                  Environment variable #6

REM Folder of SDK ("C:\Program Files\Microsoft SDKs\Windows\v7.0A")
Set SDK=U:^\                                       Environment variable #7

REM MSVC compiler ("C:\Program Files\Microsoft Visual Studio 9.0")
Set MSVC=V:\VC^\                                   Environment variable #8
</pre>
<hr width="75%">
'''Mapping Virtual Drive Letters:''' 
You will be using Windows '''subst''' command to map drive letters as references to drives '''U:''' and '''V:''' that several of the above '''environment variables''' refer to. Microsoft explanation of '''[https://technet.microsoft.com/en-us/library/bb491006.aspx subst command here]'''. 
Modify your C:\AutoExec.bat file to include something approximating the following highlighted text(version#/32/64 bit installs each vary), '''include''' the enclosing quote chars just below: 
'''subst U: "C:\Program Files\Microsoft SDKs\Windows\v7.0A"'''      (or whatever your current version is) 
'''subst V: "C:\Program Files\Microsoft Visual Studio 9.0"'''             (ditto re version 9.0=Visual Studio 2008)
 
If you do not have an '''AutoExec.bat''' file (many '''Windows 7 and 8''' users may not):
: Create a new text document using Windows File Explorer, rename it as AutoExec.bat and move(or copy) it to the '''C:\''' drive folder '''with the above two subst''' commands in it.
: Windows 7 and 8 users: File AutoExec.bat no longer automatically gets run at system-user boot-up so '''place a Shortcut to AutoExec.bat''' in the Program files '''Startup''' folder location(navigate Windows File Explorer to '''one''' of the below locations, right-click, '''New''', '''Shortcut''', '''AutoExec.bat'''). The Windows 7/8 Startup Folder usually is located as follows:
:: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup                                         (general/all users Startup folder) '''OR'''
:: C:\Users\'''UserName'''\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup       (single user Startup folder, '''UserName varies''')
'''IMPORTANT''': A successfully mapped '''V''' drive should contain a sub-sub-subfolder which then contains the '''amd64\nmake.exe''' (64-bit systems) file or '''bin\nmake.exe''' (32-bit systems), e.g. '''typical''' 64-bit configuration/location: '''C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\nmake.exe'''.
:The V drive map would '''only''' include linking through subfolder '''\Visual Studio 9.0'''. After creating the linked drives, just '''check''' to make sure your mapped '''V''' drive has the '''nmake.exe''' contained one or several subfolder levels below it. The NARS2000.exe automated Compile/Build uses '''nmake.exe''' during exe construction. 64-bit installs require the '''amd64\nmake.exe''' file - paradoxically even if your machine's chipset is Intel, a minor Microsoft variation. 
Typical mapped configurations just below, but again each install/version# may vary: 
'''U''' =     '''C:\Program Files\Microsoft SDKs\Windows\v7.0A'''     (or v6.0A or whatever your downloaded/current version is) 
'''V''' =     '''C:\Program Files\Microsoft Visual Studio 9.0'''           (or '''C:\Program Files (x86)\Microsoft Studio 9.0''' for 64-bit installs, again look for nmake.exe in a subfolder) 
As a '''check''' to make sure the '''subst''' commands worked, there should now be '''2 new drive letters visible in Windows Explorer, in the leftmost window for virtual drives/mapped folders - U and V'''. ''To avoid having to reboot'' at present, just '''open'''(not edit but run) '''AutoExec.bat AFTER''' making sure it is 100% correctly configured. Having a correctly configured AutoExec.bat file will ensure not having to manually link drives U and V each time the NARS2000.exe is built-rebuilt.
<hr width="40%">
If you install NARS project tools in other folders, make appropriate changes to the above mappings.

'''Lastly don't forget:''' To append three folders: '''C:\cygwin64\bin''' , '''V:\Common7\IDE''' and '''C:\PHP''' to your '''Path''' variable '''PATH=%PATH%;C:\cygwin64\bin;V:\Common7\IDE;C:\PHP''' or see '''Control Panel''' search for '''Path''', then '''Edit''' System Environment Variables for your account, system variable named '''Path'''; append to that '''Path''' variable   ''';C:\cygwin64\bin;V:\Common7\IDE;C:\PHP'''   - (three additional paths, semicolon separated) so Visual C's '''Make''' plus '''Compiler''' can find DLLs, exe's and Tools you have so diligently downloaded, then installed.

==Pre First Compile and Localization Notes==

Make/Compile local Environment Variable '''%NARSROOT%''' is presently set using file '''C:\NARS2000\trunk\wcustomize.bat'''. This bat file is called by other major trigger-compile bat files such as mk32.bat, mk64.bat, w32.bat and w64.bat - which oversee-initiate compilation. The %NARSROOT% environment variable is important in indicating where Make/Compilation will occur. Before first locally compiling NARS2000, you likely need to manually edit (using Notepad or a local text file editor) file '''trunk\wcustomize.bat''' and make sure the following are initially correct per your 'local PC NARS installation' i.e. within wcustomize.bat: 
'''Set NARSROOT=C:\NARS2000^\'''       (Note: '''No %''' symbols are needed in set/specification rows in wcustomize.bat, e.g. replace 'R:\NARS2000' to 'C:\NARS2000' as shown at left) 
'''Set CS_DIR=C:\DoctorDumpSDK^\'''     (again R:\ was changed to C:\) 
The additional hat(^) symbol in the above bat commands is needed for directory/folder recombination purposes, essentially sub-directory parse-point identification and or recombination point, where NARS may use subdirectories/parsing.

'''Prior''' to using '''Visual Studio''' and its '''IDE'''(integrated developer's environment) for NARS Building/Compilation purposes a first time, and to help ensure the proper installation of NARS source code - it is very helpful/necessary to open a CMD.EXE window using <big>'''Windows Start''', '''CMD.EXE'''</big>. This will open up a small CMD window. While <big>inside the opened CMD.EXE window</big>, navigate to your local C:\NARS2000\trunk folder, using <big>'''cd C:\NARS2000\trunk'''</big> where cd represents change directory. Now run <big>'''mk32.bat'''</big> by typing it in, to compile NARS2000's 32-bit executable. If mk32.bat is successful and if your installation is 100% correct, two identical files in separate folders will be created(built and compiled) using bat commands from inside that CMD window/session: 
'''C:\NARS2000\trunk\RET\ND32\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND32\NARS2000.exe''' 
If that 32-bit NARS make/build was successful, then from the same CMD.EXE window, type <big>'''mk64.bat'''</big>. This should likewise compile locally the '''64-bit''' NARS Executable, with again two resulting '''exe output files:''' 
'''C:\NARS2000\trunk\RET\ND64\NARS2000.exe''' 
'''C:\NARS2000\trunk\binaries\ND64\NARS2000.exe'''

Successfully completing mk32.bat and mk64.bat along with presence of their respective '''NARS2000.exe''' output files generally confirm successful installation of NARS source code, as well as correct installation for several associated tandem utility tools re compiling NARS2000.exe on your server, PC, notebook or tablet computer.

==Building The Executable==

Congratulations, if you've successfully arrived at this section, your resume now includes such useful terms as software installation wizard and relentless software engineering candidate. You are part of an elite group - the few, the proud, NARS geek marines; also known as tomorrow's APL-symbol-set event-horizon squad. You've managed to easily or otherwise cross several potentially deep programming ravines in the process.

At this point you should be ready to build the executable, again - this time however from inside Visual Studio's IDE(integrated developer's environment). There are two general ways to build NARS executable. Method one: Involves the time-honored command-line batch file compile mode using files mk32.bat or mk64.bat - as you should have previously discovered in the section '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' while using Windows CMD.EXE.

Method two: Involves again first opening a (Windows Start button) '''CMD.EXE''' window and running '''w32.bat start''' (all one command) or '''w64.bat start'''. Immediately or shortly, you should see Visual Studio 2013's program visualize, load and run - with either the 32-bit or 64-bit NARS2000 project/program loaded. After Visual Studio 2013 finishes loading - simply click Build. Full use of Visual Studio 2013's IDE (integrated developer's environment) should now be available for you to experiment with, develop code on, debug and customize APL as you may choose. Your first time through with running '''w32.bat start''' and '''w64.bat start''':
* There is usually a Visual Studio '''One Way Migration''' message which displays. This is normal, TBE(to be expected), and yes you DO at that point want to migrate the NARS2000 project to Visual Studio 2013. There are usually roughly 20 migration warnings which also show up in an Internet Browser page re the Migration Report - again, all normally to be expected. However, there should be '''zero errors''' in the migration report.
* If all went satisfactorily well with the Migration, you should be able to select/choose/Click '''Build Solution''' under Build in VS2013's IDE to fully compile NARS2000 executable. After Build, there should likewise be zero errors.

Special note regarding '''w32.bat start''' and '''w64.bat start''' while in Visual Studio's IDE for the NARS2000 project:
When switching between 32 and 64-bit versions, i.e. w32.bat start '''versus''' w64.bat start: There is a '''Property''' adjustment required when using Visual Studio's IDE. After Visual Studio opens up and in the Solution Explorer window (usually on the upper right hand side of your screen) click on "Solution 'nars2000' (1 project)." This should then show a Properties Window just below it. Look for a line which reads: '''Active config'''. If you ran w32.bat start then Active config should have a value of '''Debug32|Win32'''. If you ran w64.bat start then Active config should have a value of '''Debug64|Win32'''.

==Developer Experiments with NARS Source Code==

This section is for Developers who have successfully downloaded NARS source code and want to Experiment with it, or further develop NARS APL Interpreter's source code.

For development and debugging purposes: You as APL Interpreter developer normally want to want to first write new source code/model using the 32-bit version of NARS2000 (w32.bat start). This is because the 32-bit version is easier to debug than the 64-bit version; error messages can be less complex. Migrating '''correct source code''' forward from the 32-bit version to the 64-bit version is also easier than a reverse migration.

You will also at some point still need to be synched-with or later synch-back-to NARS online source code - i.e. after experimenting/changing local PC source code. This is equivalent to a ChemLab 101 at home/home-office and cleaning up all experiments at the end of the chemistry class, except as it applies to software developers, NARS software developers, and or those inclined to experiment safely.

Here is where Tortoise SVN provides excellent and time-tested source-code clean-up tools for your local PC, including '''Resolve, Revert, Clean up, and Undo changes'''. Pull up these TortoiseSVN utilities by navigating Windows File Explorer to directory C:\NARS2000. If you successfully previously downloaded and Installed TortoiseSVN and NARS2000 source code, as outlined earlier/above, you may right click on say the \trunk subfolder in C:\NARS2000. A mouse right-click on \trunk should show an option labeled TortoiseSVN. Further choosing/selecting TortoiseSVN should then reveal multiple clean up options - Resolve, Revert, Clean up and Undo changes. '''TortoiseSVN Documentation on:''' [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-cleanup.html Clean up.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-revert.html Undo Changes.] [http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-conflicts.html Resolving Conflicts.] 

At least one method to safely synch-back-to NARS is to:
# Select '''TortoiseSVN''' after right-clicking on the trunk folder
# Select '''Revert''', click '''OK''', let it run.
# Select '''Clean up''', check '''Refresh shell overlays''', click '''OK''', let it run.
Per TortoiseSVN there should again be green check marks appearing on your trunk folder as well as your msieve folder.

For revision tracking and long-term software program maintenance purposes: '''Keep track of which files (file names) you personally modify, including a brief purpose''' for that edit. You will need to this information later for Release Notes purposes (see folder C:\NARS2000\trunk\ReleaseNotes for best-practice-examples of developer note-taking) and if you later synch to a new online NARS version, you may have to carry-forward your edit changes into a newly downloaded set of NARS source code files which may or may not reflect your prior local computer edit changes.

==Periodic NARS Updates==

Incremental Update - Method 1: 
Periodically, NARS APL interpreter developers should ensure changes done by other developers get incorporated into their local machine's source code working copy. This is the process of integrating/downloading changes from NARS SourceForge server '''to''' your local copy. Updating may be performed on single files, a set of selected files, or recursively on entire directory hierarchies. To update, select the files and/or '''directories''' you want (usually \trunk and or \msieve), right click and select '''TortoiseSVN → Update''' in the explorer context menu for that trunk or msieve folder. A window will pop up displaying the progress of the update as it runs. Changes done by other developers will be merged into your local files, '''keeping''' any changes you may have done to the same files - if you did not want to keep your local changes but do want to keep the downloaded changes, select TortoiseSVN and Revert '''prior''' to running TortoiseSVN Update. NARS repository at SourceForge is '''not''' affected by an update to your local copy. [http://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-dug-update.html Update Your Working Copy With Changes From Others]

Total Source Code Replacement - Method 2: 
For example from version r1325 to say version r1364 (note a significant revision/datetime gap between 1325 and 1364, hypothetically), whatever NARS latest revision number is. Total code replacement may be preferred over incremental updating when major structural changes or significant source code changes are newly in situ. 
Total Replacement Process: Visually scan NARS source code page at http://sourceforge.net/p/nars2000/code/HEAD/tree/trunk/ and review the top 25 to 40 file entries or so, while mentally keeping track of the '''highest revision number found'''(e.g. r1379). If after your last/earlier TortoiseSVN Update, your local version number is lower than the latest revision number visually found online, then perform the following to update to the most recent NARS revision:
# Rename your existing NARS folder to something approximating C:\NARS2000_old_rev
# Create an entirely new C:\NARS2000 folder
# '''Copy all folders and files at the top level''' from C:\NARS2000_old_rev folder into C:\NARS2000 '''EXCEPT \trunk and \msieve subfolders (and their contents)'''. The \trunk and \msieve folders will shortly be downloaded from SourceForge.
# Create '''new empty folders called \trunk and \msieve''' in the new C:\NARS2000 folder.
# Revisit the section above called '''[[#Check_Out_The_Source_Code|Check Out The Source Code]]''' to again checkout/download to the absolute latest NARS version number, for both \trunk and \msieve folders.
# Also revisit '''[[#Pre_First_Compile_and_Localization_Notes|Pre First Compile and Localization Notes]]''' and text edit file \trunk\wcustomize.bat to localize the new version.
# Folder C:\NARS2000_old_rev may be '''Recycled''' after you are done copying non-trunk and non-msieve files/folders from it into your new C:\NARS2000 folder. If disk space is not restrictive and for 100% safety purposes, keep your prior folder available until after successfully '''Building/Compiling''' the newly downloaded 32-bit and 64-bit versions, and making sure you did not have any local personal changes now potentially being recycled.

C Source Code Conventions and Abbreviations Dictionary

2015-08-24T23:25:52Z

Robert Wallick: /* Abbreviations Dictionary */ added ODS

'''<big>NARS C Source Code Conventions and Abbreviations Dictionary:</big>'''

==Conventions==

{| class="wikitable" style="width: 50%"
! Convention
! Syntax
! Description/Where Used
! Sample Use
! Purpose
|-
| '''PrimFn'''
| Prefix
| name prefix to all Primary APL functions
| '''PrimFn'''Rho_EM_YY
| Quickly identify such names
|-
| '''SysFn'''
| Prefix
| name prefix to all Quad type System Functions
| '''SysFn'''WA_EM_YY
| Quickly identify such names
|-
| '''_EM_YY'''
| Suffix
| name suffix to all Primary APL functions AND Quad System Functions, including monadic and dyadic calls
| SysFnTS'''_EM_YY'''
| Quickly identify such names, referencing
|-
|}

==Abbreviations Dictionary==

{| class="wikitable" style="width: 70%"
! Abbrev
! Meaning
! Definition Location, Purpose, Cross Ref's
! Sample Source Code Usage
|-
| '''APA'''
| Arithmetic Progression Array
| C code suffix to variable type, sometimes variable names. for example, ⍳6 or iota-6 is an '''arithmetic progression array''' of integers. Definition for ARRAY_'''APA''' found in file <datatype.h>
| ARRAY_'''APA''' is a variable type. Ref. wiki '''[[APA|documentation page APA]]'''. For closely examining '''APA ''' datatypes, see also '''[[System_Function_DR|System Function ⎕DR]]'''.
|-
| '''lp'''
| long pointer
| Usually found as a prefix to variable names. NARS makes frequent use of pointers to speed up processing times, to make NARS2000.exe more efficient.
| '''lp'''tkRhtArg (var name; long ptr to token var structure of a right hand argument for a function call)
|-
| '''NELM'''
| Number of Elements
| Usually embedded within variable names. Conceptually like '''[[Rho|Rho or <apll>{rho}</apll>]]''' of a vector.
| APL'''NELM''' apl'''NELM'''Rht; // VarType VarName; Right arg NELM for variable type(APLNELM) and variable named aplNELMRht
|-
| '''ODS'''
| OutputDebugString
| Variously used throughout program, especially see file <debug.c> for string printing to console, debugging. See function int oprintfW, usage example per <updates.c>, oprintfW (L"%3d: SetEvent on %p (IDC_DNLPAUSE_BN -- hSuspend)\n", guCnt++, dnlThrStr.hSuspend); % means "Prt var here"; 3 = "use at least 3 spaces(max width) to show, pad as needed"; d = "Var is int"; hex-%x; float-%f; str-%s; ptrs-%p. L prefix=unicode str
| int oprintfW(LPWCHAR lpwszFmt, ...) // Ptr to format string, variable list
|-
| '''PerTab'''
| per tab, esp. per APL workspace tab
| Embedded in var names. Detailed explanation of PerTab found in C source header file <pertab.h>. '''NARS supports multiple simultaneously open and running workspaces.''' Each workspace is displayed as a separate '''Tab''', much like folder tabs. All variables in all workspace are distinctly maintained, with each PerTab.
| LP'''PERTAB'''DATA lpMemPTD; where LP'''PERTAB'''DATA is the variable type and lpMemPTD is a pointer to PerTabData global memory
|-
| '''PTD'''
| per tab of data
| Embedded in var names. Each NARS workspace is kept separate and distinct in its own PTD.
| lpMem'''PTD''' structured var name, in this case a ptr to PerTabData global memory
|-
| '''Rank'''
| Rank
| Rank: Scalars=0, Vectors=1, Matrices=2..N. Like {rho}{rho} of an APL variable or contained data structure, see shape of the shape '''[[Rho|RhoRho or {rho}{rho}]]'''.
| APL'''RANK''' apl'''Rank'''Lft // Left arg rank (variable type, variable name)
|-
| '''SIS'''
| State Indicator Stack
| Frequently embedded within variable and function names. Detailed explanation of SIS found in C source header file <sis.h> See also APL's '''[[System_Command_SI|System Command )SI]]'''.
| lpMemPTD->lp'''SIS'''Cur->ResetFlag; (var name) AND Fill'''SIS'''Nxt (fcn name)
|-
| '''tk'''
| token
| Frequently found embedded in structured variable names. Tokens are [http://www.c4learn.com/c-programming/c-tokens-keywords-identifiers/ basic building blocks of C Programming]; hence '''tk''' vars frequently represent important structured variables in NARS.
| LPTOKEN lp'''tk'''RhtArg
|-
| '''TKT_'''
| token type
| Prefix to typed variable names. Most tokens are simple in that they have type and data only.e,g, TKT_LEFTPAREN and '('. Some frequently used tokens are complex in that their data points to other data. Token types are also associated with a Constant type '''value''', e.g. '''TKT_'''VARARRAY = '''1A'''(Hex val, 26 dec val). Token types may also represent APL/System Functions - '''TKT_'''FCNNAMED (52 hex) = a named function. Full explanation see file <tokens.h>. See also typedef structures '''[[Frequently_Used_TypeDef_Structures_and_Variables#TOKEN|TOKEN]]'''.
| '''TKT_'''VARARRAY - main workhorse token type. Its tkData is an HGLOBAL (global memory handle) which contains an array which is either simple, nested, or mixed(combination of diff data types, e.g. string int float and or double).
|-
| '''UTF'''
| Unicode Transformation Format
| Variable names, constants, [http://unicode.org/faq/utf_bom.html especially UTF16]; algorithmic mapping for Unicode code numbers (except surrogate code points) to unique byte sequencing (esp. 16-bit = 2-byte sequences). ASCII uses 2^7 bits=128 codes; EBSDIC 2^8=256 codes. Unicode 2-byte uses 2^16=65,536 codes, as currently does NARS, see also System Functions '''[[System_Function_AV|<apll>{quad}</apll>AV]]''' and '''[[System_Function_UCS|<apll>{quad}</apll>UCS]]'''. Both the 32-bit and 64-bit NARS2000.exe's use 16-bit uncodes; the 32 and 64 bit NARS exe's refer to numeric data computer representations and calculation precisions. List of defined '''UTF'''16_ vars see file <Unicode.h>.
| '''UTF'''16_RHO
|}

System Variable PP

2015-08-22T01:54:00Z

Robert Wallick: expanded example

<h1>{quad}PP - Print Precision</h1>
{{BoxStart|⎕PP
| Print Precision}}
{{BoxEnd|⎕PP←'VALUE'}}

System Variable '''⎕PP''' or '''Quad PP''' refers to Print Precision.
In NARS, the default Print Precision is:
<pre>
⎕PP
10
1÷3
0.3333333333 ⍝ 10 significant digits after the decimal point are shown
⍕1÷3
0.3333333333 ⍝ 10 significant digits after the decimal point are shown, for formatted result
⍴⍕1÷3
12 ⍝ 10 significant digits after the decimal point, plus 0 and decimal point itself = 12 chars (shape)

X←1÷3
X
0.3333333333
⎕PP←4 ⍝ print precision changed to 4 digits
X
0.3333
X←⍎⍕X ⍝ X is now formatted(printed) and re-executed into a number (for demonstration purposes only, AVOID in practice!!!)
X
0.3333
⎕PP←10 ⍝ print precision is restored to 10 digits
X
0.3333 ⍝ but X now only has 4 significant digits in it, as a result of ⎕PP reduction, formatting and re-execution into a number.
</pre>
Although 10 significant digits represent the print precision or displayed precision - actual computer stored formats are quite different. Historically or customarily, ⎕PP is normally assigned a value of between 1 and 16, although with 64-bit systems, higher print precision values are available. As an example, pollution is frequently cited in PPM's or parts per million or say 1 in 1,000,000 so 5-signficant digits in the data plus 7 digits within a million base might mean ⎕PP should be set as 5+7 = 12 significant digits, or greater for higher precision printed reports. Note that '''print precision does NOT normally affect stored/digitized numbers, unless''' the numbers were first formatted/printed, then re-executed into digital floating point numbers as the above example shows.

See also '''[[System_Function_DR|System Function ⎕DR]]'''. 
{{System Variables}}
{{Article footer}}
{{stub}}

System Variable PP

2015-08-22T01:40:42Z

Robert Wallick: added example

<h1>{quad}PP - Print Precision</h1>
{{BoxStart|⎕PP
| Print Precision}}
{{BoxEnd|⎕PP←'VALUE'}}

System Variable '''⎕PP''' or '''Quad PP''' refers to Print Precision.
In NARS, the default Print Precision is:
<pre>
⎕PP
10
1÷3
0.3333333333 ⍝ 10 significant digits after the decimal point are shown
⍕1÷3
0.3333333333 ⍝ 10 significant digits after the decimal point are shown, for formatted result
⍴⍕1÷3
12 ⍝ 10 significant digits after the decimal point, plus 0 and decimal point itself = 12 chars (shape)
</pre>
Although 10 significant digits represent the print precision or displayed precision - actual computer stored formats are quite different. Historically or customarily, ⎕PP is normally assigned a value of between 1 and 16, although with 64-bit systems, higher print precision values are available. As an example, pollution is frequently cited in PPM's or parts per million or say 1 in 1,000,000 so 5-signficant digits in the data plus 7 digits within a million base might mean ⎕PP should be set as 5+7 = 12 significant digits, or greater for higher precision printed reports. Note that print precision does NOT normally affect stored/digitized numbers, unless the numbers were first formatted/printed, then re-executed into digital floating point numbers.

See also '''[[System_Function_DR|System Function ⎕DR]]'''. 
{{System Variables}}
{{Article footer}}
{{stub}}

System Variable PP

2015-08-22T01:32:52Z

Robert Wallick: wording, description

System Function DR

2015-08-22T01:11:00Z

Robert Wallick: /* Dyadic Function */ expansion, correction

This function is available in both ''monadic'' and ''dyadic'' forms.
==Monadic Function==
{{BoxStart|<apll>Z←⎕DR R</apll>
|returns the data representation of <apll>R</apll>.}}
{{BoxLine |<apll>R</apll> is an arbitrary array.}}
{{BoxEnd |<apll>Z</apll> is a numeric scalar which represents the datatype of <apll>R</apll>.}}
 

The datatypes are encoded with a unique index in the low-order two digits, and (where appropriate) the bits per element in the higher-order digits:

*<apll> 110</apll>: Boolean, one bit per element
*<apll>1611</apll>: Character, 16 bits per element
*<apll>6412</apll>: Integer, 64 bits per element
*<apll>6413</apll>: Floating Point, 64 bits per element (double precision)
*<apll>  14</apll>: Rational, 16 bytes plus two 4- or 8-byte pointers plus size of limbs per element
*<apll>  15</apll>: Variable-precision Floating Point, 12 bytes plus one 4- or 8-byte pointer plus size of limbs per element
*<apll>  19</apll>: Arithmetic Progression Array, 64 bits each for the offset and multiplier
*<apll>  20</apll>: Heterogeneous, one 4- or 8-byte pointer per element
*<apll>  21</apll>: Nested, one 4- or 8-byte pointer per element

For example,

<apll>      ⎕DR 1 0 1 110 
      ⎕DR ⌈/⍬ 6413 
      ⎕DR 2 64⍴1</apll> — Note this is really an APA, not Boolean<apll> 19 
      ⎕DR 2 64⍴1 1</apll> — This one is Boolean because Reshape produces APAs for integer singleton right arguments only<apll> 110 </apll>
 

==Dyadic Function==
{{BoxStart|<apll>Z←L ⎕DR R</apll>
|converts <apll>R</apll> to the datatype indicated by <apll>L</apll>.}}
{{BoxLine|<apll>R</apll> is an arbitrary array.}}
{{BoxLine|<apll>L</apll> is an integer scalar or one-element vector datatype (see the table above), or a special value (see below).}}
{{BoxEnd|<apll>Z</apll> is <apll>R</apll> where each of the values are converted to the datatype indicated by <apll>L</apll>.}}
Returned value <big>'''Z'''</big> may alternatively be: numeric scalar, vector of numbers, or a character string - depending on what the value of left argument <big>'''L'''</big> was. 

If the conversion is from a narrower datatype to a wider datatype, there must be exactly enough columns in the right argument to match a multiple of the size of the wider datatype. For example, when converting from character (16-bit) to integer (64-bit), the last column of the right argument must be a multiple of 4 (= 64/16); otherwise, a <apll>LENGTH ERROR</apll> is signalled.

<apll>
      6412 ⎕DR 'NARS2000'</apll> — Eight 16-bit characters (=128 bits) converts to two 64-bit integers (in both NARS2000 32-bit AND 64-bit exe's since <big>L=6412</big>):<apll> 
23362775258562638 13511005043687474 
</apll>

If the conversion is from a wider datatype to a narrower datatype, the number of values in the result is a multiple of the ratio of the wider datatype to the narrower datatype. For example, when converting from integer (64-bit) to character (16-bit), the last column in the result is the product of last column of the right argument and 4 (= 64/16).

For example('''inverse''' of the example just above),

<apll>
      ⍴⎕←1611 ⎕DR 23362775258562638 13511005043687474 
NARS2000 
8 
</apll>

Keep in mind '''how [[APA|Arithmetic Progression Arrays]]''' are created and represented; they can fool both the casual programmer as well as an experienced coder. For example, one might try the following to convert from Boolean to integer:

<apll>
      6412 ⎕DR 2 64⍴1     ⍝ APA created 
1 0 2 64 
</apll>

However, this doesn't produce the expected result because this particular right argument is an <big>APA</big>, and not a simple Boolean vector of 1's. That is, under certain circumstances, the reshape primitive creates an APA. In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2</apll> rows and <apll>64</apll> cols. The usefulness of APA's in reducing data storage and processing times outweighs their sometimes added code complexity or additional insight, which may be required.

On the other hand, this expression:

<apll>
      6412 ⎕DR 2 64⍴1 1   ⍝ contrast to prior example - Boolean vec created here, NOT an APA 
 ¯1 
 ¯1 
</apll>

produces the expected result because the right argument is "right upon moment of vector '''1 1''' creation" - Boolean.

===Special Values===

There are several special values you may use as a left argument to <apll>⎕DR</apll>:

<ul>
<li>The value '''<apll>0</apll>''' displays the datatype of the right argument as a text '''string''' so you don't need to remember the datatype numbers.

For example,
<pre>
⎕DR 'a'
1611
⍴⎕DR 'a' ⍝ the shape of a scalar is null

⍴⍴⎕DR 'a'
0 ⍝ the shape of the shape of a scalar is always zero; monadic ⎕DR 'a' results in scalar number Z=1611
0 ⎕DR 'a'
Character (1611): 16 bits per element ⍝ string result returned where left arg of ⎕DR was zero
⍴0 ⎕DR 'a'
38 ⍝ the shape of the data returned is 38; dyadic 0 ⎕DR 'a' results in a character array, a string of length 38

0 ⎕DR ⍳12
Arithmetic Progression Array (19): 64 bit offset + 64 bit multiplier -- PV1 ⍝ 64-bit signatures re integer numeric progression
⍴0 ⎕DR ⍳12
76 ⍝ again dyadic ⎕DR results in a string, this time of length 76
</pre>
Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - runs similarly using both '''64-bit AND 32-bit NARS versions''', hence the 64-bit offset and 64-bit multiplier. This is because integer APAs are processed using 64-bit formats. Again, if ever there is any doubt or a need to precisely determine formats, use ⎕DR with its correct syntax, arguments. 

Many times in programming - for debugging, data scrutiny or other purposes - it is very important to know exactly how the data is represented by the program. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS. 

Some arrays have properties that may be displayed by this function:

<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
<tr><td><apll>PV0</apll></td>
<td>This array is a Permutation Vector, origin-0</td></tr>
<tr>
<td><apll>PV1</apll></td>
<td>This array is a Permutation Vector, origin-1</td>
</tr>
<tr>
<td><apll>All2s</apll></td>
<td>This array consists of all <apll>2</apll>s</td>
</tr>
<tr>
<td><apll>FPC</apll>nnn</td>
<td>This array is a VFP and all entries are represented in Precision nnn</td>
</tr>
<tr>
<td><apll>FPC-Mixed</apll></td>
<td>This array is a VFP whose entries are represented in two or more different precisions</td>
</tr>
</table>

</li>

<li>The value <apll>1</apll> converts between hex-character and floating point computer formats. This argument makes it very useful to view representations of floating point numbers - in order to better understand numeric precisions, program storage formats, debug multi-precision floating-point math routines(by NARS developers) or examine perceived floating point issues.

For example,

<apll>
      ⎕PP←99 
      1 ⎕DR 1.1 
3FF199999999999A    ⍝ note the hexadecimal char representation of 1.1 is shown at left 
      ⍴1 ⎕DR 1.1 
16                  ⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = both 64-bit and 32-bit NARS 
      1 ⎕DR '3fd',13⍴'5' 
0.3333333333333333 
      1 ⎕DR ¯∞ ∞ 
FFF0000000000000 
7FF0000000000000 
      1 ⎕DR '7fe',13⍴'f'</apll> — The largest positive number<apll> 
1.7976931348623157E308 
      1 ⎕DR '001',13⍴'0'</apll> — The smallest positive number<apll> 
2.2250738585072014E¯308 
      1 ⎕DR '801',13⍴'0'</apll> — The largest negative number<apll> 
¯2.2250738585072014E¯308 
      1 ⎕DR 'ffe',13⍴'f'</apll> — The smallest negative number<apll> 
¯1.7976931348623157E308 
</apll>
</li>

<li>The value <apll>2</apll> converts between character and 64-bit integer. This argument makes it easy to see the representation of integers.

For example,

<apll>
      2 ⎕DR ¯1 
FFFFFFFFFFFFFFFF 
      2 ⎕DR '7',15⍴'f'</apll> — The largest positive integer<apll> 
9223372036854775807 
      2 ⎕DR '8',15⍴'0'</apll> — The smallest negative integer<apll> 
¯9223372036854775808 
      2 ⎕DR 9223372036854775807 ¯9223372036854775808 
7FFFFFFFFFFFFFFF 
8000000000000000 
</apll>
</li>
</ul>

===A Word of Caution===

This system function allows you to create special numbers we don't support in that no other primitive generates these numbers and the behavior of all other primitives on these numbers is undefined. Examples of such special numbers include '''Quiet NaNs''', '''Signaling NaNs''', '''Negative Zero''', and '''Denormals'''. If the system doesn't behave as you expect when using these special numbers, don't be surprised.

For example,

<apll>
      ⎕CT←0 ⋄ ⎕PP←99 
      6413 ⎕DR ¯64↑1 
¯0 
      QNaN←6413 ⎕DR ¯64↑13⍴1</apll> — A Quiet NaN (Not a Number)<apll> 
      1 ⎕DR QNaN 
FFF8000000000000 
      QNaN=QNaN 
0 
      1 ⎕DR '000fffffffffffff'</apll> — The largest positive denormal<apll> 
2.225073858507201E¯308 
      1 ⎕DR '0000000000000001'</apll> — The smallest positive denormal<apll> 
5E¯324 
</apll>
 
See also '''[[System_Variable_CT|System Variable ⎕CT]]''' and '''[[System_Variable_PP|System Variable ⎕PP]]'''. 
{{SFDM|DR}}

C Source Code Conventions and Abbreviations Dictionary

2015-08-21T17:17:10Z

Robert Wallick: /* Abbreviations Dictionary */ added APA

'''<big>NARS C Source Code Conventions and Abbreviations Dictionary:</big>'''

==Conventions==

{| class="wikitable" style="width: 50%"
! Convention
! Syntax
! Description/Where Used
! Sample Use
! Purpose
|-
| '''PrimFn'''
| Prefix
| name prefix to all Primary APL functions
| '''PrimFn'''Rho_EM_YY
| Quickly identify such names
|-
| '''SysFn'''
| Prefix
| name prefix to all Quad type System Functions
| '''SysFn'''WA_EM_YY
| Quickly identify such names
|-
| '''_EM_YY'''
| Suffix
| name suffix to all Primary APL functions AND Quad System Functions, including monadic and dyadic calls
| SysFnTS'''_EM_YY'''
| Quickly identify such names, referencing
|-
|}

==Abbreviations Dictionary==

{| class="wikitable" style="width: 70%"
! Abbrev
! Meaning
! Definition Location, Purpose, Cross Ref's
! Sample Source Code Usage
|-
| '''APA'''
| Arithmetic Progression Array
| C code suffix to variable type, sometimes variable names. for example, ⍳6 or iota-6 is an '''arithmetic progression array''' of integers. Definition for ARRAY_'''APA''' found in file <datatype.h>
| ARRAY_'''APA''' is a variable type. Ref. wiki '''[[APA|documentation page APA]]'''. For closely examining '''APA ''' datatypes, see also '''[[System_Function_DR|System Function ⎕DR]]'''.
|-
| '''lp'''
| long pointer
| Usually found as a prefix to variable names. NARS makes frequent use of pointers to speed up processing times, to make NARS2000.exe more efficient.
| '''lp'''tkRhtArg (var name; long ptr to token var structure of a right hand argument for a function call)
|-
| '''NELM'''
| Number of Elements
| Usually embedded within variable names. Conceptually like '''[[Rho|Rho or <apll>{rho}</apll>]]''' of a vector.
| APL'''NELM''' apl'''NELM'''Rht; // VarType VarName; Right arg NELM for variable type(APLNELM) and variable named aplNELMRht
|-
| '''PerTab'''
| per tab, esp. per APL workspace tab
| Embedded in var names. Detailed explanation of PerTab found in C source header file <pertab.h>. '''NARS supports multiple simultaneously open and running workspaces.''' Each workspace is displayed as a separate '''Tab''', much like folder tabs. All variables in all workspace are distinctly maintained, with each PerTab.
| LP'''PERTAB'''DATA lpMemPTD; where LP'''PERTAB'''DATA is the variable type and lpMemPTD is a pointer to PerTabData global memory
|-
| '''PTD'''
| per tab of data
| Embedded in var names. Each NARS workspace is kept separate and distinct in its own PTD.
| lpMem'''PTD''' structured var name, in this case a ptr to PerTabData global memory
|-
| '''Rank'''
| Rank
| Rank: Scalars=0, Vectors=1, Matrices=2..N. Like {rho}{rho} of an APL variable or contained data structure, see shape of the shape '''[[Rho|RhoRho or {rho}{rho}]]'''.
| APL'''RANK''' apl'''Rank'''Lft // Left arg rank (variable type, variable name)
|-
| '''SIS'''
| State Indicator Stack
| Frequently embedded within variable and function names. Detailed explanation of SIS found in C source header file <sis.h> See also APL's '''[[System_Command_SI|System Command )SI]]'''.
| lpMemPTD->lp'''SIS'''Cur->ResetFlag; (var name) AND Fill'''SIS'''Nxt (fcn name)
|-
| '''tk'''
| token
| Frequently found embedded in structured variable names. Tokens are [http://www.c4learn.com/c-programming/c-tokens-keywords-identifiers/ basic building blocks of C Programming]; hence '''tk''' vars frequently represent important structured variables in NARS.
| LPTOKEN lp'''tk'''RhtArg
|-
| '''TKT_'''
| token type
| Prefix to typed variable names. Most tokens are simple in that they have type and data only.e,g, TKT_LEFTPAREN and '('. Some frequently used tokens are complex in that their data points to other data. Token types are also associated with a Constant type '''value''', e.g. '''TKT_'''VARARRAY = '''1A'''(Hex val, 26 dec val). Token types may also represent APL/System Functions - '''TKT_'''FCNNAMED (52 hex) = a named function. Full explanation see file <tokens.h>. See also typedef structures '''[[Frequently_Used_TypeDef_Structures_and_Variables#TOKEN|TOKEN]]'''.
| '''TKT_'''VARARRAY - main workhorse token type. Its tkData is an HGLOBAL (global memory handle) which contains an array which is either simple, nested, or mixed(combination of diff data types, e.g. string int float and or double).
|-
| '''UTF'''
| Unicode Transformation Format
| Variable names, constants, [http://unicode.org/faq/utf_bom.html especially UTF16]; algorithmic mapping for Unicode code numbers (except surrogate code points) to unique byte sequencing (esp. 16-bit = 2-byte sequences). ASCII uses 2^7 bits=128 codes; EBSDIC 2^8=256 codes. Unicode 2-byte uses 2^16=65,536 codes, as currently does NARS, see also System Functions '''[[System_Function_AV|<apll>{quad}</apll>AV]]''' and '''[[System_Function_UCS|<apll>{quad}</apll>UCS]]'''. Both the 32-bit and 64-bit NARS2000.exe's use 16-bit uncodes; the 32 and 64 bit NARS exe's refer to numeric data computer representations and calculation precisions. List of defined '''UTF'''16_ vars see file <Unicode.h>.
| '''UTF'''16_RHO
|}

System Function DR

2015-08-21T17:16:29Z

Robert Wallick: /* Dyadic Function */

This function is available in both ''monadic'' and ''dyadic'' forms.
==Monadic Function==
{{BoxStart|<apll>Z←⎕DR R</apll>
|returns the data representation of <apll>R</apll>.}}
{{BoxLine |<apll>R</apll> is an arbitrary array.}}
{{BoxEnd |<apll>Z</apll> is a numeric scalar which represents the datatype of <apll>R</apll>.}}
 

The datatypes are encoded with a unique index in the low-order two digits, and (where appropriate) the bits per element in the higher-order digits:

*<apll> 110</apll>: Boolean, one bit per element
*<apll>1611</apll>: Character, 16 bits per element
*<apll>6412</apll>: Integer, 64 bits per element
*<apll>6413</apll>: Floating Point, 64 bits per element (double precision)
*<apll>  14</apll>: Rational, 16 bytes plus two 4- or 8-byte pointers plus size of limbs per element
*<apll>  15</apll>: Variable-precision Floating Point, 12 bytes plus one 4- or 8-byte pointer plus size of limbs per element
*<apll>  19</apll>: Arithmetic Progression Array, 64 bits each for the offset and multiplier
*<apll>  20</apll>: Heterogeneous, one 4- or 8-byte pointer per element
*<apll>  21</apll>: Nested, one 4- or 8-byte pointer per element

For example,

<apll>      ⎕DR 1 0 1 110 
      ⎕DR ⌈/⍬ 6413 
      ⎕DR 2 64⍴1</apll> — Note this is really an APA, not Boolean<apll> 19 
      ⎕DR 2 64⍴1 1</apll> — This one is Boolean because Reshape produces APAs for integer singleton right arguments only<apll> 110 </apll>
 

==Dyadic Function==
{{BoxStart|<apll>Z←L ⎕DR R</apll>
|converts <apll>R</apll> to the datatype indicated by <apll>L</apll>.}}
{{BoxLine|<apll>R</apll> is an arbitrary array.}}
{{BoxLine|<apll>L</apll> is an integer scalar or one-element vector datatype (see the table above), or a special value (see below).}}
{{BoxEnd|<apll>Z</apll> is <apll>R</apll> where each of the values are converted to the datatype indicated by <apll>L</apll>.}}
Returned value <big>'''Z'''</big> may alternatively be: numeric scalar, vector of numbers, or a character string - depending on what the value of left argument <big>'''L'''</big> was. 

If the conversion is from a narrower datatype to a wider datatype, there must be exactly enough columns in the right argument to match a multiple of the size of the wider datatype. For example, when converting from character (16-bit) to integer (64-bit), the last column of the right argument must be a multiple of 4 (= 64/16); otherwise, a <apll>LENGTH ERROR</apll> is signalled.

<apll>
      6412 ⎕DR 'NARS2000'</apll> — Eight 16-bit characters (=128 bits) converts to two 64-bit integers:<apll> 
23362775258562638 13511005043687474 
</apll>

If the conversion is from a wider datatype to a narrower datatype, the number of values in the result is a multiple of the ratio of the wider datatype to the narrower datatype. For example, when converting from integer (64-bit) to character (16-bit), the last column in the result is the product of last column of the right argument and 4 (= 64/16).

For example('''inverse''' of the example just above),

<apll>
      ⍴⎕←1611 ⎕DR 23362775258562638 13511005043687474 
NARS2000 
8 
</apll>

Keep in mind '''how [[APA|Arithmetic Progression Arrays]]''' are created and represented; they can fool both the casual programmer as well as an experienced coder. For example, one might try the following to convert from Boolean to integer:

<apll>
      6412 ⎕DR 2 64⍴1     ⍝ APA created 
1 0 2 64 
</apll>

However, this doesn't produce the expected result because this particular right argument is an <big>APA</big>, and not a simple Boolean vector of 1's. That is, under certain circumstances, the reshape primitive creates an APA. In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2</apll> rows and <apll>64</apll> cols. The usefulness of APS's in reducing data storage and processing times outweighs their sometimes added code complexity or additional insight, which may be required.

On the other hand, this expression:

<apll>
      6412 ⎕DR 2 64⍴1 1   ⍝ contrast to prior example - Boolean vec created here, NOT an APA 
 ¯1 
 ¯1 
</apll>

produces the expected result because the right argument is "right upon moment of vector '''1 1''' creation" - Boolean.

===Special Values===

There are several special values you may use as a left argument to <apll>⎕DR</apll>:

<ul>
<li>The value '''<apll>0</apll>''' displays the datatype of the right argument as a text '''string''' so you don't need to remember the datatype numbers.

For example,
<pre>
⎕DR 'a'
1611
⍴⎕DR 'a' ⍝ the shape of a scalar is null

⍴⍴⎕DR 'a'
0 ⍝ the shape of the shape of a scalar is always zero; monadic ⎕DR 'a' results in scalar number Z=1611
0 ⎕DR 'a'
Character (1611): 16 bits per element ⍝ string result returned where left arg of ⎕DR was zero
⍴0 ⎕DR 'a'
38 ⍝ the shape of the data returned is 38; dyadic 0 ⎕DR 'a' results in a character array, a string of length 38

0 ⎕DR ⍳12
Arithmetic Progression Array (19): 64 bit offset + 64 bit multiplier -- PV1 ⍝ 64-bit signatures re integer numeric progression
⍴0 ⎕DR ⍳12
76 ⍝ again dyadic ⎕DR results in a string, this time of length 76
</pre>
Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - was run using the '''64-bit NARS version''', hence the 64-bit offset and 64-bit multiplier. Had it been run in '''32-bit NARS''', it would have returned 32-bit signatures.

Many times in programming for debugging, data scrutiny or other purposes: It is very important to know exactly how the data is represented by the program. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.

Some arrays have properties that may be displayed by this function:

<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
<tr><td><apll>PV0</apll></td>
<td>This array is a Permutation Vector, origin-0</td></tr>
<tr>
<td><apll>PV1</apll></td>
<td>This array is a Permutation Vector, origin-1</td>
</tr>
<tr>
<td><apll>All2s</apll></td>
<td>This array consists of all <apll>2</apll>s</td>
</tr>
<tr>
<td><apll>FPC</apll>nnn</td>
<td>This array is a VFP and all entries are represented in Precision nnn</td>
</tr>
<tr>
<td><apll>FPC-Mixed</apll></td>
<td>This array is a VFP whose entries are represented in two or more different precisions</td>
</tr>
</table>

</li>

<li>The value <apll>1</apll> converts between hex-character and floating point computer formats. This argument makes it very useful to view representations of floating point numbers - in order to better understand numeric precisions, program storage formats, debug multi-precision floating-point math routines(by NARS developers) or examine perceived floating point issues.

For example,

<apll>
      ⎕PP←99 
      1 ⎕DR 1.1 
3FF199999999999A    ⍝ note the hexadecimal char representation of 1.1 is shown at left 
      ⍴1 ⎕DR 1.1 
16                  ⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = 64-bit-NARS 
      1 ⎕DR '3fd',13⍴'5' 
0.3333333333333333 
      1 ⎕DR ¯∞ ∞ 
FFF0000000000000 
7FF0000000000000 
      1 ⎕DR '7fe',13⍴'f'</apll> — The largest positive number<apll> 
1.7976931348623157E308 
      1 ⎕DR '001',13⍴'0'</apll> — The smallest positive number<apll> 
2.2250738585072014E¯308 
      1 ⎕DR '801',13⍴'0'</apll> — The largest negative number<apll> 
¯2.2250738585072014E¯308 
      1 ⎕DR 'ffe',13⍴'f'</apll> — The smallest negative number<apll> 
¯1.7976931348623157E308 
</apll>
</li>

<li>The value <apll>2</apll> converts between character and 64-bit integer. This argument makes it easy to see the representation of integers.

For example,

<apll>
      2 ⎕DR ¯1 
FFFFFFFFFFFFFFFF 
      2 ⎕DR '7',15⍴'f'</apll> — The largest positive integer<apll> 
9223372036854775807 
      2 ⎕DR '8',15⍴'0'</apll> — The smallest negative integer<apll> 
¯9223372036854775808 
      2 ⎕DR 9223372036854775807 ¯9223372036854775808 
7FFFFFFFFFFFFFFF 
8000000000000000 
</apll>
</li>
</ul>

===A Word of Caution===

This system function allows you to create special numbers we don't support in that no other primitive generates these numbers and the behavior of all other primitives on these numbers is undefined. Examples of such special numbers include '''Quiet NaNs''', '''Signaling NaNs''', '''Negative Zero''', and '''Denormals'''. If the system doesn't behave as you expect when using these special numbers, don't be surprised.

For example,

<apll>
      ⎕CT←0 ⋄ ⎕PP←99 
      6413 ⎕DR ¯64↑1 
¯0 
      QNaN←6413 ⎕DR ¯64↑13⍴1</apll> — A Quiet NaN (Not a Number)<apll> 
      1 ⎕DR QNaN 
FFF8000000000000 
      QNaN=QNaN 
0 
      1 ⎕DR '000fffffffffffff'</apll> — The largest positive denormal<apll> 
2.225073858507201E¯308 
      1 ⎕DR '0000000000000001'</apll> — The smallest positive denormal<apll> 
5E¯324 
</apll>
 
{{SFDM|DR}}

System Function DR

2015-08-21T16:49:10Z

Robert Wallick: /* Dyadic Function */ wording

This function is available in both ''monadic'' and ''dyadic'' forms.
==Monadic Function==
{{BoxStart|<apll>Z←⎕DR R</apll>
|returns the data representation of <apll>R</apll>.}}
{{BoxLine |<apll>R</apll> is an arbitrary array.}}
{{BoxEnd |<apll>Z</apll> is a numeric scalar which represents the datatype of <apll>R</apll>.}}
 

The datatypes are encoded with a unique index in the low-order two digits, and (where appropriate) the bits per element in the higher-order digits:

*<apll> 110</apll>: Boolean, one bit per element
*<apll>1611</apll>: Character, 16 bits per element
*<apll>6412</apll>: Integer, 64 bits per element
*<apll>6413</apll>: Floating Point, 64 bits per element (double precision)
*<apll>  14</apll>: Rational, 16 bytes plus two 4- or 8-byte pointers plus size of limbs per element
*<apll>  15</apll>: Variable-precision Floating Point, 12 bytes plus one 4- or 8-byte pointer plus size of limbs per element
*<apll>  19</apll>: Arithmetic Progression Array, 64 bits each for the offset and multiplier
*<apll>  20</apll>: Heterogeneous, one 4- or 8-byte pointer per element
*<apll>  21</apll>: Nested, one 4- or 8-byte pointer per element

For example,

<apll>      ⎕DR 1 0 1 110 
      ⎕DR ⌈/⍬ 6413 
      ⎕DR 2 64⍴1</apll> — Note this is really an APA, not Boolean<apll> 19 
      ⎕DR 2 64⍴1 1</apll> — This one is Boolean because Reshape produces APAs for integer singleton right arguments only<apll> 110 </apll>
 

==Dyadic Function==
{{BoxStart|<apll>Z←L ⎕DR R</apll>
|converts <apll>R</apll> to the datatype indicated by <apll>L</apll>.}}
{{BoxLine|<apll>R</apll> is an arbitrary array.}}
{{BoxLine|<apll>L</apll> is an integer scalar or one-element vector datatype (see the table above), or a special value (see below).}}
{{BoxEnd|<apll>Z</apll> is <apll>R</apll> where each of the values are converted to the datatype indicated by <apll>L</apll>.}}
Returned value '''Z''' may alternatively be: numeric scalar, vector of numbers, or a character string - depending on what the value of the laft argument(L) was. 

If the conversion is from a narrower datatype to a wider datatype, there must be exactly enough columns in the right argument to match a multiple of the size of the wider datatype. For example, when converting from character (16-bit) to integer (64-bit), the last column of the right argument must be a multiple of 4 (= 64/16); otherwise, a <apll>LENGTH ERROR</apll> is signalled.

<apll>
      6412 ⎕DR 'NARS2000'</apll> — Eight 16-bit characters (=128 bits) converts to two 64-bit integers:<apll> 
23362775258562638 13511005043687474 
</apll>

If the conversion is from a wider datatype to a narrower datatype, the number of values in the result is a multiple of the ratio of the wider datatype to the narrower datatype. For example, when converting from integer (64-bit) to character (16-bit), the last column in the result is the product of last column of the right argument and 4 (= 64/16).

For example('''inverse''' of the example just above),

<apll>
      ⍴⎕←1611 ⎕DR 23362775258562638 13511005043687474 
NARS2000 
8 
</apll>

Keep in mind how [[APA|Arithmetic Progression Arrays]] are created and represented as they can fool you. For example, you might try the following to convert from Boolean to integer:

<apll>
      6412 ⎕DR 2 64⍴1 
1 0 2 64 
</apll>

However, this doesn't produce the expected result because this particular right argument is an APA, not a Boolean vector. That is, under certain circumstances, the reshape primitive creates an APA. In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2 64</apll>.

On the other hand, this expression

<apll>
      6412 ⎕DR 2 64⍴1 1 
 ¯1 
 ¯1 
</apll>

produces the expected result because the right argument is now Boolean.

===Special Values===

There are several special values you may use as a left argument to <apll>⎕DR</apll>:

<ul>
<li>The value '''<apll>0</apll>''' displays the datatype of the right argument as a text '''string''' so you don't need to remember the datatype numbers.

For example,
<pre>
⎕DR 'a'
1611
⍴⎕DR 'a' ⍝ the shape of a scalar is null

⍴⍴⎕DR 'a'
0 ⍝ the shape of the shape of a scalar is always zero; monadic ⎕DR 'a' results in scalar number Z=1611
0 ⎕DR 'a'
Character (1611): 16 bits per element ⍝ string result returned where left arg of ⎕DR was zero
⍴0 ⎕DR 'a'
38 ⍝ the shape of the data returned is 38; dyadic 0 ⎕DR 'a' results in a character array, a string of length 38

0 ⎕DR ⍳12
Arithmetic Progression Array (19): 64 bit offset + 64 bit multiplier -- PV1 ⍝ 64-bit signatures re integer numeric progression
⍴0 ⎕DR ⍳12
76 ⍝ again dyadic ⎕DR results in a string, this time of length 76
</pre>
Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - was run using the '''64-bit NARS version''', hence the 64-bit offset and 64-bit multiplier. Had it been run in '''32-bit NARS''', it would have returned 32-bit signatures.

Many times in programming for debugging, data scrutiny or other purposes: It is very important to know exactly how the data is represented by the program. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.

Some arrays have properties that may be displayed by this function:

<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
<tr><td><apll>PV0</apll></td>
<td>This array is a Permutation Vector, origin-0</td></tr>
<tr>
<td><apll>PV1</apll></td>
<td>This array is a Permutation Vector, origin-1</td>
</tr>
<tr>
<td><apll>All2s</apll></td>
<td>This array consists of all <apll>2</apll>s</td>
</tr>
<tr>
<td><apll>FPC</apll>nnn</td>
<td>This array is a VFP and all entries are represented in Precision nnn</td>
</tr>
<tr>
<td><apll>FPC-Mixed</apll></td>
<td>This array is a VFP whose entries are represented in two or more different precisions</td>
</tr>
</table>

</li>

<li>The value <apll>1</apll> converts between hex-character and floating point computer formats. This argument makes it very useful to view representations of floating point numbers - in order to better understand numeric precisions, program storage formats, debug multi-precision floating-point math routines(by NARS developers) or examine perceived floating point issues.

For example,

<apll>
      ⎕PP←99 
      1 ⎕DR 1.1 
3FF199999999999A    ⍝ note the hexadecimal char representation of 1.1 is shown at left 
      ⍴1 ⎕DR 1.1 
16                  ⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = 64-bit-NARS 
      1 ⎕DR '3fd',13⍴'5' 
0.3333333333333333 
      1 ⎕DR ¯∞ ∞ 
FFF0000000000000 
7FF0000000000000 
      1 ⎕DR '7fe',13⍴'f'</apll> — The largest positive number<apll> 
1.7976931348623157E308 
      1 ⎕DR '001',13⍴'0'</apll> — The smallest positive number<apll> 
2.2250738585072014E¯308 
      1 ⎕DR '801',13⍴'0'</apll> — The largest negative number<apll> 
¯2.2250738585072014E¯308 
      1 ⎕DR 'ffe',13⍴'f'</apll> — The smallest negative number<apll> 
¯1.7976931348623157E308 
</apll>
</li>

<li>The value <apll>2</apll> converts between character and 64-bit integer. This argument makes it easy to see the representation of integers.

For example,

<apll>
      2 ⎕DR ¯1 
FFFFFFFFFFFFFFFF 
      2 ⎕DR '7',15⍴'f'</apll> — The largest positive integer<apll> 
9223372036854775807 
      2 ⎕DR '8',15⍴'0'</apll> — The smallest negative integer<apll> 
¯9223372036854775808 
      2 ⎕DR 9223372036854775807 ¯9223372036854775808 
7FFFFFFFFFFFFFFF 
8000000000000000 
</apll>
</li>
</ul>

===A Word of Caution===

This system function allows you to create special numbers we don't support in that no other primitive generates these numbers and the behavior of all other primitives on these numbers is undefined. Examples of such special numbers include '''Quiet NaNs''', '''Signaling NaNs''', '''Negative Zero''', and '''Denormals'''. If the system doesn't behave as you expect when using these special numbers, don't be surprised.

For example,

<apll>
      ⎕CT←0 ⋄ ⎕PP←99 
      6413 ⎕DR ¯64↑1 
¯0 
      QNaN←6413 ⎕DR ¯64↑13⍴1</apll> — A Quiet NaN (Not a Number)<apll> 
      1 ⎕DR QNaN 
FFF8000000000000 
      QNaN=QNaN 
0 
      1 ⎕DR '000fffffffffffff'</apll> — The largest positive denormal<apll> 
2.225073858507201E¯308 
      1 ⎕DR '0000000000000001'</apll> — The smallest positive denormal<apll> 
5E¯324 
</apll>
 
{{SFDM|DR}}

Quad EC C Source Code Analysis

2015-08-21T16:30:34Z

Robert Wallick: /* Comparison Structure Configurations - Different Returned Outputs */ string/char_array example added

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Structure Configurations - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structure configuration for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT; // Or use IMMTYPE_INT for an integer
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec; // DataType APLFLOAT aplFloatSec Or use DataType APLINT with tkData.tkInteger
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structure configuration for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc (); // Setup line # 1 for lpYYRes
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY; // Setup line # 2 for lpYYRes
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes); // Setup line # 3 for lpYYRes
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex; // Setup line # 4 for lpYYRes
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data. From a purely structural perspective, excluding 1)pre-setup work in ⎕EC, 2)comment lines and 3)post-op processing C code, only 4 lines of C code were needed (above) to '''setup''' (not calculate) return result variable lpYYRes for ⎕EC.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structure configuration for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').

 4. '''[[System_Function_DR|⎕DR]]''' (file <'''qf_dr.c'''> code extract) detailed structure configuration for returned string (CHAR_ARRAY) '''char/string vector''' (extracted from function SysFnDR_Show_EM_YY):
<pre>
// Variable declarations (type varname), needed for C code extracted just below:
APLUINT ByteRes; // # bytes in the result
LPPL_YYSTYPE lpYYRes; // Ptr to the result
APLNELM aplNELMRes; // Result NELM
APLCHAR wszTemp[512]; // Temporary APLCHARs Unicode string variable
HGLOBAL hGlbRes; // Result ...
LPVOID lpMemRes; // Ptr to result global memory

// Get the result NELM
aplNELMRes = lstrlenW (wszTemp);

// Calculate space needed for the result
ByteRes = CalcArraySize (ARRAY_CHAR, aplNELMRes, 1);

// Check for overflow
if (ByteRes NE (APLU3264) ByteRes)
goto WSFULL_EXIT;

// Allocate space for the result
hGlbRes = DbgGlobalAlloc (GHND, (APLU3264) ByteRes);
if (hGlbRes EQ NULL)
goto WSFULL_EXIT;

// Lock the memory to get a ptr to it
lpMemRes = MyGlobalLock (hGlbRes);

#define lpHeader ((LPVARARRAY_HEADER) lpMemRes)
// Fill in the header
lpHeader->Sig.nature = VARARRAY_HEADER_SIGNATURE;
lpHeader->ArrType = ARRAY_CHAR;
////lpHeader->PermNdx = PERMNDX_NONE; // Already zero from GHND
////lpHeader->SysVar = FALSE; // Already zero from GHND
lpHeader->RefCnt = 1;
lpHeader->NELM = aplNELMRes;
lpHeader->Rank = 1;
#undef lpHeader

// Save the dimension in the result
*VarArrayBaseToDim (lpMemRes) = aplNELMRes;

// Point to the data (APLAPA struct)
lpMemRes = VarArrayDataFmBase (lpMemRes);

// Copy text to the result
CopyMemory (lpMemRes, wszTemp, (APLU3264) BytesIn (ARRAY_CHAR, aplNELMRes));

// No longer need this ptr
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
////lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
////lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>

System Function DR

2015-08-21T16:16:18Z

Robert Wallick: /* Special Values */ expanded

This function is available in both ''monadic'' and ''dyadic'' forms.
==Monadic Function==
{{BoxStart|<apll>Z←⎕DR R</apll>
|returns the data representation of <apll>R</apll>.}}
{{BoxLine |<apll>R</apll> is an arbitrary array.}}
{{BoxEnd |<apll>Z</apll> is a numeric scalar which represents the datatype of <apll>R</apll>.}}
 

The datatypes are encoded with a unique index in the low-order two digits, and (where appropriate) the bits per element in the higher-order digits:

*<apll> 110</apll>: Boolean, one bit per element
*<apll>1611</apll>: Character, 16 bits per element
*<apll>6412</apll>: Integer, 64 bits per element
*<apll>6413</apll>: Floating Point, 64 bits per element (double precision)
*<apll>  14</apll>: Rational, 16 bytes plus two 4- or 8-byte pointers plus size of limbs per element
*<apll>  15</apll>: Variable-precision Floating Point, 12 bytes plus one 4- or 8-byte pointer plus size of limbs per element
*<apll>  19</apll>: Arithmetic Progression Array, 64 bits each for the offset and multiplier
*<apll>  20</apll>: Heterogeneous, one 4- or 8-byte pointer per element
*<apll>  21</apll>: Nested, one 4- or 8-byte pointer per element

For example,

<apll>      ⎕DR 1 0 1 110 
      ⎕DR ⌈/⍬ 6413 
      ⎕DR 2 64⍴1</apll> — Note this is really an APA, not Boolean<apll> 19 
      ⎕DR 2 64⍴1 1</apll> — This one is Boolean because Reshape produces APAs for integer singleton right arguments only<apll> 110 </apll>
 

==Dyadic Function==
{{BoxStart|<apll>Z←L ⎕DR R</apll>
|converts <apll>R</apll> to the datatype indicated by <apll>L</apll>.}}
{{BoxLine|<apll>R</apll> is an arbitrary array.}}
{{BoxLine|<apll>L</apll> is an integer scalar or one-element vector datatype (see the table above), or a special value (see below).}}
{{BoxEnd|<apll>Z</apll> is <apll>R</apll> where each of the values are converted to the datatype indicated by <apll>L</apll>.}}
 

If the conversion is from a narrower datatype to a wider datatype, there must be exactly enough columns in the right argument to match a multiple of the size of the wider datatype. For example, when converting from character (16-bit) to integer (64-bit), the last column of the right argument must be a multiple of 4 (= 64/16); otherwise, a <apll>LENGTH ERROR</apll> is signalled.

<apll>
      6412 ⎕DR 'NARS2000'</apll> — Eight 16-bit characters (=128 bits) convert to two 64-bit integers<apll> 
23362775258562638 13511005043687474 
</apll>

If the conversion is from a wider datatype to a narrower datatype, the number of values in the result is a multiple of the ratio of the wider datatype to the narrower datatype. For example, when converting from integer (64-bit) to character (16-bit), the last column in the result is the product of last column of the right argument and 4 (= 64/16).

For example,

<apll>
      ⍴⎕←1611 ⎕DR 23362775258562638 13511005043687474 
NARS2000 
8 
</apll>

Keep in mind how [[APA|Arithmetic Progression Arrays]] are created and represented as they can fool you. For example, you might try the following to convert from Boolean to integer:

<apll>
      6412 ⎕DR 2 64⍴1 
1 0 2 64 
</apll>

However, this doesn't produce the expected result because this particular right argument is an APA, not a Boolean vector. That is, under certain circumstances, the reshape primitive creates an APA. In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2 64</apll>.

On the other hand, this expression

<apll>
      6412 ⎕DR 2 64⍴1 1 
 ¯1 
 ¯1 
</apll>

produces the expected result because the right argument is now Boolean.

===Special Values===

There are several special values you may use as a left argument to <apll>⎕DR</apll>:

<ul>
<li>The value '''<apll>0</apll>''' displays the datatype of the right argument as a text '''string''' so you don't need to remember the datatype numbers.

For example,
<pre>
⎕DR 'a'
1611
⍴⎕DR 'a' ⍝ the shape of a scalar is null

⍴⍴⎕DR 'a'
0 ⍝ the shape of the shape of a scalar is always zero; monadic ⎕DR 'a' results in scalar number Z=1611
0 ⎕DR 'a'
Character (1611): 16 bits per element ⍝ string result returned where left arg of ⎕DR was zero
⍴0 ⎕DR 'a'
38 ⍝ the shape of the data returned is 38; dyadic 0 ⎕DR 'a' results in a character array, a string of length 38

0 ⎕DR ⍳12
Arithmetic Progression Array (19): 64 bit offset + 64 bit multiplier -- PV1 ⍝ 64-bit signatures re integer numeric progression
⍴0 ⎕DR ⍳12
76 ⍝ again dyadic ⎕DR results in a string, this time of length 76
</pre>
Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - was run using the '''64-bit NARS version''', hence the 64-bit offset and 64-bit multiplier. Had it been run in '''32-bit NARS''', it would have returned 32-bit signatures.

Many times in programming for debugging, data scrutiny or other purposes: It is very important to know exactly how the data is represented by the program. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.

Some arrays have properties that may be displayed by this function:

<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
<tr><td><apll>PV0</apll></td>
<td>This array is a Permutation Vector, origin-0</td></tr>
<tr>
<td><apll>PV1</apll></td>
<td>This array is a Permutation Vector, origin-1</td>
</tr>
<tr>
<td><apll>All2s</apll></td>
<td>This array consists of all <apll>2</apll>s</td>
</tr>
<tr>
<td><apll>FPC</apll>nnn</td>
<td>This array is a VFP and all entries are represented in Precision nnn</td>
</tr>
<tr>
<td><apll>FPC-Mixed</apll></td>
<td>This array is a VFP whose entries are represented in two or more different precisions</td>
</tr>
</table>

</li>

<li>The value <apll>1</apll> converts between hex-character and floating point computer formats. This argument makes it very useful to view representations of floating point numbers - in order to better understand numeric precisions, program storage formats, debug multi-precision floating-point math routines(by NARS developers) or examine perceived floating point issues.

For example,

<apll>
      ⎕PP←99 
      1 ⎕DR 1.1 
3FF199999999999A    ⍝ note the hexadecimal char representation of 1.1 is shown at left 
      ⍴1 ⎕DR 1.1 
16                  ⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = 64-bit-NARS 
      1 ⎕DR '3fd',13⍴'5' 
0.3333333333333333 
      1 ⎕DR ¯∞ ∞ 
FFF0000000000000 
7FF0000000000000 
      1 ⎕DR '7fe',13⍴'f'</apll> — The largest positive number<apll> 
1.7976931348623157E308 
      1 ⎕DR '001',13⍴'0'</apll> — The smallest positive number<apll> 
2.2250738585072014E¯308 
      1 ⎕DR '801',13⍴'0'</apll> — The largest negative number<apll> 
¯2.2250738585072014E¯308 
      1 ⎕DR 'ffe',13⍴'f'</apll> — The smallest negative number<apll> 
¯1.7976931348623157E308 
</apll>
</li>

<li>The value <apll>2</apll> converts between character and 64-bit integer. This argument makes it easy to see the representation of integers.

For example,

<apll>
      2 ⎕DR ¯1 
FFFFFFFFFFFFFFFF 
      2 ⎕DR '7',15⍴'f'</apll> — The largest positive integer<apll> 
9223372036854775807 
      2 ⎕DR '8',15⍴'0'</apll> — The smallest negative integer<apll> 
¯9223372036854775808 
      2 ⎕DR 9223372036854775807 ¯9223372036854775808 
7FFFFFFFFFFFFFFF 
8000000000000000 
</apll>
</li>
</ul>

===A Word of Caution===

This system function allows you to create special numbers we don't support in that no other primitive generates these numbers and the behavior of all other primitives on these numbers is undefined. Examples of such special numbers include '''Quiet NaNs''', '''Signaling NaNs''', '''Negative Zero''', and '''Denormals'''. If the system doesn't behave as you expect when using these special numbers, don't be surprised.

For example,

<apll>
      ⎕CT←0 ⋄ ⎕PP←99 
      6413 ⎕DR ¯64↑1 
¯0 
      QNaN←6413 ⎕DR ¯64↑13⍴1</apll> — A Quiet NaN (Not a Number)<apll> 
      1 ⎕DR QNaN 
FFF8000000000000 
      QNaN=QNaN 
0 
      1 ⎕DR '000fffffffffffff'</apll> — The largest positive denormal<apll> 
2.225073858507201E¯308 
      1 ⎕DR '0000000000000001'</apll> — The smallest positive denormal<apll> 
5E¯324 
</apll>
 
{{SFDM|DR}}

Quad EC C Source Code Analysis

2015-08-20T21:58:45Z

Robert Wallick: /* Comparison Structure Configurations - Different Returned Outputs */

Quad EC C Source Code Analysis

2015-08-20T21:56:43Z

Robert Wallick: /* Comparison Prelim Setups - Different Returned Outputs */

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Structure Configurations - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structural setup for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT; // Or use IMMTYPE_INT for an integer
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec; // DataType APLFLOAT aplFloatSec Or use DataType APLINT with tkData.tkInteger
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structural setup for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc (); // Setup line # 1 for lpYYRes
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY; // Setup line # 2 for lpYYRes
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes); // Setup line # 3 for lpYYRes
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex; // Setup line # 4 for lpYYRes
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data. From a purely structural perspective, excluding 1)pre-setup work in ⎕EC, 2)comment lines and 3)post-op processing C code, only 4 lines of C code were needed (above) to '''setup''' (not calculate) return result variable lpYYRes for ⎕EC.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structural setup for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').

Quad EC C Source Code Analysis

2015-08-20T21:42:25Z

Robert Wallick: /* Comparison Prelim Setups - Different Returned Outputs */ expanded

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Prelim Setups - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structural setup for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT; // Or use IMMTYPE_INT for an integer
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec; // DataType APLFLOAT aplFloatSec Or use DataType APLINT with tkData.tkInteger
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structural setup for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc (); // Setup line # 1 for lpYYRes
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY; // Setup line # 2 for lpYYRes
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes); // Setup line # 3 for lpYYRes
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex; // Setup line # 4 for lpYYRes
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data. From a purely structural perspective, excluding 1)pre-setup work in ⎕EC, 2)comment lines and 3)post-op processing C code, only 4 lines of C code were needed (above) to '''setup''' (not calculate) return result variable lpYYRes for ⎕EC.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structural setup for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').

Frequently Used TypeDef Structures and Variables

2015-08-18T14:33:48Z

Robert Wallick: /* tkToken Commonly Used Structures */

'''<big>NARS C Source Code Frequently Used TypeDef Structures and Variables:</big>'''

NARS has multiple frequently used TypeDefs, Structures, Type-Variables and Variables. Familiarity with these structures, including variables employed, is essential toward gaining increased understanding of how NARS C source code works, including insight into C program flow.

==TypeDefs==

===LPPL_YYSTYPE===

Full definition for typedef '''LPPL_YYTYPE''': found in file <'''pl_parse.h'''>. '''Partial''', extracted, compiler-directives-excluded/simplified definition:
<pre>
typedef struct tagPL_YYSTYPE // YYSTYPE for ParseLine
{
// N.B.: The first item in this struct *MUST* be the TOKEN
// because when we pass it as an argument to an LPPRIMFNS
// we might need it to be an LPPL_YYSTYPE (for a function strand)
// or an LPTOKEN (single function).
TOKEN tkToken; // 00: Token info (28 bytes)
UINT TknCount; // 1C: Count of adjacent tokens including this one
UINT YYInuse:1, // 20: 00000001: This entry is in use
YYIndirect:1, // 00000002: Arg is indirect
YYPerm:1, // 00000004: Item is permanent, don't free
YYStranding:1, // 00000008: Item is in the process of being stranded
:28; // FFFFFFF0: Available bits

struct tagPL_YYSTYPE
*lpYYFcnBase, // 24: Ptr to base function/operator
// Not valid outside the enclosing
// invocation of ParseLine
*lpYYStrandBase, // 28: Ptr to this token's strand base
*lpplYYArgCurry, // 2C: Ptr to left argument curry
*lpplYYIdxCurry, // 30: Ptr to axis curry
*lpplYYFcnCurry, // 34: ... function ...
*lpplYYOpRCurry; // 38: ... right operand ...
LPTOKEN lptkLftBrace, // 3C: Ptr to the AFO's left brace token
lptkRhtBrace; // 40: ... right ...
// 44: Length
} PL_YYSTYPE, *LPPL_YYSTYPE; // Data type of yacc stack; most frequently used is LPPL_YYSTYPE, long pointer to the above structure.
</pre>
* In the above code snippet note the '''nested struct''' formation. '''Inner struct tagPL_YYSTYPE resides within code confines''' of outer struct ''same-name'' tagPL_YYSTYPE. This formation parallels nicely with APL's workspace '''[[System_Command_SI|State Indicator )SI]]''' intrinsic Interpreter design feature which is used for APL-programmer debugging purposes. 
* For ⎕ System Function and Primary APL Function calls, the above typedef is the normal or the expected - '''returned value-group''', the returned value-set structure. Further, since NARS by its very nature handles nested arrays, the above structure similarly manages nested data arrays well. In case it is not obvious to anyone reading this web page or examining NARS source code - NARS represents a highly evolved, data-fluid, APL Interpreter with a full, rich symbol-set programming environment.
 
'''LPPL_YYSTYPE''' is customarily used as a '''variable-type''', as per the following: 
LPPL_YYSTYPE lpYYRes = NULL, // initialize, lpYYRes will be Ptr to result of a ⎕ quad System Function or Primary APL Function call
and '''macro YYAlloc''' (def. file <macros.h>) call instantiated, then with specific values inserted: 
lpYYRes = YYAlloc (); // Allocate free memory, fill LPPL_YYSTYPE memory structure with default setup/values, e.g. <qf_ec.c>
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

<hr width=25%>

===TOKEN===

Full definition for typedef '''TOKEN''': found in file <'''tokens.h'''>:
<pre>
typedef struct tagTOKEN
{
TKFLAGS tkFlags; // 00: The flags part (numbers shown at left are beginning byte # in structure)
SO_ENUM tkSynObj; // 04: The Syntax Object for this token
TOKEN_DATA tkData; // 08: The data part (16 bytes=18 Hex - 08 Hex = 10 Hex)
int tkCharIndex; // 18: Index into the input line of this token
// 1C: Length (1C Hex = 16+12 decimal = byte #28)
} TOKEN, *LPTOKEN;
</pre>

Primary sample usage: Above typedef TOKEN is the first type-var found in '''[[Frequently_Used_TypeDef_Structures_and_Variables#LPPL_YYSTYPE|typedef LPPL_YYSTYPE]]''' above, ref. TOKEN use just below:
<pre>
TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)
</pre>
Linked or indirect referencing through typed variable-name example: (to fill in a result token):
<pre>
// Sample token type choices: TKT_VARNAMED, TKT_VARIMMED, TKT_LSTIMMED, TKT_LSTARRAY, TKT_LSTMULT, TKT_VARARRAY(primary), TKT_STRAND and TKT_STRING.
// Full list of token types found in file <tokens.h>. TKT_VARARRAY used just below:
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
</pre>

==tkToken Commonly Used Structures==
C Source Code Sample Short List of '''tkToken Structure Groupings''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References and '''Frequencies''' (per C:\NARS2000\trunk qf_*.c/pf_*.c files) as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure/Value
! Overall Found Freq
! Overall Found % Tot
|-
| qf_ec.c|| 237|| tkToken|| 820|| 100.0%
|-
| qf_a.c|| 67|| tkToken.tkCharIndex|| 134|| 16.3%
|-
| pf_cstile.c|| 182|| tkToken.tkData.tkBoolean|| 13|| 1.6%
|-
| qf_tc.c|| 162|| tkToken.tkData.tkChar|| 5|| 0.6%
|-
| qf_dl.c|| 179|| tkToken.tkData.tkFloat|| 9|| 1.1%
|-
| qf_a.c|| 66|| tkToken.tkData.tkGlbData|| 135|| 16.5%
|-
| qf_dr.c|| 98|| tkToken.tkData.tkInteger|| 25|| 3.0%
|-
| qf_dr.c|| 309|| tkToken.tkData.tkLongest|| 18|| 2.2%
|-
| qf_ec.c|| 275|| tkToken.tkData.tkSym|| 3|| 0.4%
|-
| qf_ec.c|| 268|| tkToken.tkData.tkVoid|| 1|| 0.1%
|-
| qf_a.c|| 64|| tkToken.tkFlags.ImmType|| 145|| 17.7%
|-
| qf_a.c|| 65|| tkToken.tkFlags.NoDisplay|| 140|| 17.1%
|-
| qf_a.c|| 63|| tkToken.tkFlags.TknType|| 148|| 18.0%
|-
| pf_index.c|| 774|| tkToken.tkSynObj|| 1|| 0.1%
|-
|}
One analogy to NARS tkToken structure groupings can be found in Particle Physics where Quarks, Leptons, Gluons and Gravitons comprise a particle class known as '''[http://physics.about.com/od/atomsparticles/a/particles.htm Fermions]'''; ''particle'' and ''C code'' subtypes or subclasses also exist. NARS tkToken structure groupings, just as is true for Fermions, allows for a wide range of C coded functionality groupings. tkToken is a convenient way of grouping several pieces of related information together with flexibility for handling '''potentially broadly different''' datatypes, shapes and even functionality. A nested matrix of mixed elements can be handled, as well accommodation for workspace state indicator stack value-sets - all within tkToken structures.

==tkToken Structures More Detailed Sample Uses Table==
C Source Code '''Sample Uses''' Unique (duplicates removed) List of '''tkToken Structure = Values''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References (per C:\NARS2000\trunk qf_*.c/pf_*.c files), sorted by source filename, as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Ref. Variable Name -> Structure Group = Value
|-
| qf_a.c|| 63|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| qf_a.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadA);
|-
| qf_a.c|| 67|| lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| qf_at.c|| 406|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
|-
| qf_av.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadAV);
|-
| qf_d.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadD);
|-
| qf_dl.c|| 176|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
|-
| qf_dl.c|| 177|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
|-
| qf_dl.c|| 179|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRht;
|-
| qf_dr.c|| 96|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_INT;
|-
| qf_dr.c|| 110|| lpYYRes->tkToken.tkData.tkInteger = DR_BOOL;
|-
| qf_dr.c|| 115|| lpYYRes->tkToken.tkData.tkInteger = DR_INT64;
|-
| qf_dr.c|| 120|| lpYYRes->tkToken.tkData.tkInteger = DR_FLOAT;
|-
| qf_dr.c|| 125|| lpYYRes->tkToken.tkData.tkInteger = DR_CHAR16;
|-
| qf_dr.c|| 130|| lpYYRes->tkToken.tkData.tkInteger = DR_APA;
|-
| qf_dr.c|| 135|| lpYYRes->tkToken.tkData.tkInteger = DR_HETERO;
|-
| qf_dr.c|| 140|| lpYYRes->tkToken.tkData.tkInteger = DR_NESTED;
|-
| qf_dr.c|| 145|| lpYYRes->tkToken.tkData.tkInteger = DR_RAT;
|-
| qf_dr.c|| 150|| lpYYRes->tkToken.tkData.tkInteger = DR_VFP;
|-
| qf_dr.c|| 307|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRes;
|-
| qf_dr.c|| 309|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRes;
|-
| qf_em.c|| 70|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRes;
|-
| qf_fx.c|| 353|| lpYYRes->tkToken.tkData.tkInteger = GetQuadIO () + SF_Fcns.uErrLine;
|-
| qf_mf.c|| 493|| lpYYRes->tkToken.tkData.tkInteger = aplIntegerRes;
|-
| qf_mf.c|| 506|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRes;
|-
| qf_mf.c|| 806|| lpYYRes->tkToken.tkFlags.NoDisplay = TRUE;
|-
| qf_nfns.c|| 275|| lpYYRes->tkToken.tkData.tkInteger = aplFileOff;
|-
| qf_nfns.c|| 592|| lpYYRes->tkToken.tkFlags.NoDisplay = (aplLongestRht NE 0);
|-
| qf_nfns.c|| 593|| lpYYRes->tkToken.tkData.tkInteger = TieNum;
|-
| qf_nfns.c|| 1083|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRht;
|-
| qf_nfns.c|| 1091|| lpYYRes->tkToken.tkData.tkInteger = aplLongestRht;
|-
| qf_nfns.c|| 3298|| lpYYRes->tkToken.tkData.tkInteger = aplFileSize;
|-
| qf_t.c|| 75|| lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
|-
| qf_tc.c|| 160|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_CHAR;
|-
| qf_tc.c|| 162|| lpYYRes->tkToken.tkData.tkChar = wc;
|-
| qf_ucs.c|| 206|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRht;
|-
| qf_wa.c|| 70|| lpYYRes->tkToken.tkData.tkInteger = msex.ullAvailPhys + msex.ullAvailPageFile;
|-
| pf_bar.c|| 323|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (*lphGlbRes);
|-
| pf_cslope.c|| 255|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_cslope.c|| 259|| lpYYRes2 = PrimFnDydCircleSlope_EM_YY (&lpYYRes->tkToken,
|-
| pf_cslope.c|| 416|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkData.tkSym->stFlags.ImmType;
|-
| pf_cslope.c|| 418|| lpYYRes->tkToken.tkData.tkLongest = lptkRhtArg->tkData.tkSym->stData.stLongest;
|-
| pf_cslope.c|| 425|| lpYYRes->tkToken = *lptkRhtArg;
|-
| pf_cstile.c|| 178|| lpYYRes->tkToken = tkZero;
|-
| pf_cstile.c|| 252|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_BOOL;
|-
| pf_cstile.c|| 374|| lpYYRes->tkToken = *CopyToken_EM (lptkRhtArg, FALSE);
|-
| pf_darrow.c|| 372|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeRht);
|-
| pf_domino.c|| 220|| lpYYRes->tkToken.tkData.tkBoolean = 1;
|-
| pf_domino.c|| 481|| lpYYRes->tkToken.tkFlags.TknType =
|-
| pf_domino.c|| 526|| lpYYRes->tkToken.tkData.tkGlbData =
|-
| pf_dshoe.c|| 161|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbZilde);
|-
| pf_dshoe.c|| 480|| hGlbGup = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_dtack.c|| 219|| lpYYRes->tkToken.tkData.tkBoolean = FALSE;
|-
| pf_dtack.c|| 224|| lpYYRes->tkToken.tkData.tkInteger = 0;
|-
| pf_dtack.c|| 229|| lpYYRes->tkToken.tkData.tkFloat = 0;
|-
| pf_dtack.c|| 234|| lpYYRes->tkToken.tkData.tkChar = L' ';
|-
| pf_dtack.c|| 248|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkFlags.ImmType;
|-
| pf_dtack.c|| 309|| lpYYRes->tkToken.tkData.tkGlbData = hSymGlbRes;
|-
| pf_dtackjot.c|| 375|| lpYYRes->tkToken.tkData.tkChar = aplCharRht;
|-
| pf_epsilon.c|| 2398|| hGlbGupLft = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 2429|| hGlbGupRht = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 3731|| bCmp = lpYYTmp->tkToken.tkData.tkBoolean;
|-
| pf_epsund.c|| 279|| lpYYRes->tkToken.tkData.tkBoolean =       // Filled in below
|-
| pf_epsund.c|| 288|| lpMemRes = &lpYYRes->tkToken.tkData.tkBoolean;
|-
| pf_equalund.c|| 532|| lpYYRes->tkToken.tkData.tkBoolean = (APLBOOL) ((BIT0 & aplIntegerRes) NE bNotEqual);
|-
| pf_index.c|| 117|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeNam);
|-
| pf_index.c|| 119|| lpYYRes->tkToken.tkData.tkLongest = aplLongestNam;
|-
| pf_index.c|| 120|| lpYYRes->tkToken.tkCharIndex = lptkLstArg->tkCharIndex;
|-
| pf_index.c|| 127|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbNam);
|-
| pf_index.c|| 591|| *((LPAPLBOOL) lpMemRes) |= lpYYItm->tkToken.tkData.tkBoolean << uBitIndex;
|-
| pf_index.c|| 604|| *((LPAPLINT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkInteger;
|-
| pf_index.c|| 610|| *((LPAPLFLOAT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkFloat;
|-
| pf_index.c|| 616|| *((LPAPLCHAR) lpMemRes)++ = lpYYItm->tkToken.tkData.tkChar;
|-
| pf_index.c|| 639|| lpSymTmp = MyGlobalLock (lpYYItm->tkToken.tkData.tkGlbData);
|-
| pf_index.c|| 645|| MyGlobalUnlock (lpYYItm->tkToken.tkData.tkGlbData); lpSymTmp = NULL;
|-
| pf_index.c|| 648|| DbgGlobalFree (lpYYItm->tkToken.tkData.tkGlbData); lpYYItm->tkToken.tkData.tkGlbData = NULL;
|-
| pf_index.c|| 774|| lpYYRes->tkToken.tkSynObj = soA;
|-
| pf_index.c|| 878|| lpYYRes->tkToken.tkFlags.ImmType = immTypeNam;
|-
| pf_index.c|| 2016|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTIMMED;
|-
| pf_index.c|| 2019|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTARRAY;
|-
| pf_index.c|| 2514|| lpMemRes[0] = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2546|| hGlbSubRht = lpYYSub->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2913|| lpYYRes2 = PrimFnDydRho_EM_YY (&lpYYRes1->tkToken,
|-
| pf_index.c|| 2924|| hGlbRes = lpYYRes2->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 3593|| hGlbSubLst2 = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 4536|| lpYYRes2 = ExecFuncStr_EM_YY (&lpYYRes1->tkToken,
|-
| pf_lshoe.c|| 212|| lpYYRes->tkToken.tkFlags.ImmType = ImmType;
|-
| pf_lshoe.c|| 214|| lpYYRes->tkToken.tkData.tkLongest = aplLongest;
|-
| pf_lshoe.c|| 316|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbRht);
|-
| pf_rshoe.c|| 263|| lpYYRes->tkToken.tkFlags.ImmType = immType;
|-
| pf_rshoe.c|| 1769|| lpYYRes2->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| pf_rshoe.c|| 1772|| lpYYRes2->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_rshoe.c|| 1773|| lpYYRes2->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| pf_rshoe.c|| 1776|| lpYYRes3 = PrimFnDydCircleSlope_EM_YY (&lpYYRes2->tkToken,
|-
| pf_rshoe.c|| 1996|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRht;
|-
| pf_rshoe.c|| 2396|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRes, aplTypeRht, lptkFunc);
|-
| pf_rshoe.c|| 3014|| lpYYRes->tkToken.tkFlags.ImmType = immTypeSubRht;
|-
| pf_rshoe.c|| 3016|| lpYYRes->tkToken.tkData.tkLongest = aplLongestSubRht;
|-
| pf_rshoe.c|| 3034|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRht, aplTypeRht, lptkFunc);
|-
| pf_rtack.c|| 188|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbArg);
|-
| pf_rtack.c|| 194|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplType);
|-
| pf_squad.c|| 228|| lpMemRht = &lpYYRht->tkToken.tkData.tkInteger;
|-
| pf_squad.c|| 232|| hGlbRht = lpYYRht->tkToken.tkData.tkGlbData;
|-
| pf_squad.c|| 278|| *lpMemRes++ = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_uarrow.c|| 232|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (lpSymGlb, aplTypeRht, lptkFunc);
|-
| pf_utackjot.c|| 379|| lpYYRes->tkToken.tkFlags.NoDisplay |= (exitType EQ EXITTYPE_NODISPLAY);
|-
|} 

==Variable Types==

==Variables==

Frequently Used TypeDef Structures and Variables

2015-08-18T14:19:31Z

Robert Wallick: /* tkToken Structures More Detailed Sample Uses Table */

'''<big>NARS C Source Code Frequently Used TypeDef Structures and Variables:</big>'''

NARS has multiple frequently used TypeDefs, Structures, Type-Variables and Variables. Familiarity with these structures, including variables employed, is essential toward gaining increased understanding of how NARS C source code works, including insight into C program flow.

==TypeDefs==

===LPPL_YYSTYPE===

Full definition for typedef '''LPPL_YYTYPE''': found in file <'''pl_parse.h'''>. '''Partial''', extracted, compiler-directives-excluded/simplified definition:
<pre>
typedef struct tagPL_YYSTYPE // YYSTYPE for ParseLine
{
// N.B.: The first item in this struct *MUST* be the TOKEN
// because when we pass it as an argument to an LPPRIMFNS
// we might need it to be an LPPL_YYSTYPE (for a function strand)
// or an LPTOKEN (single function).
TOKEN tkToken; // 00: Token info (28 bytes)
UINT TknCount; // 1C: Count of adjacent tokens including this one
UINT YYInuse:1, // 20: 00000001: This entry is in use
YYIndirect:1, // 00000002: Arg is indirect
YYPerm:1, // 00000004: Item is permanent, don't free
YYStranding:1, // 00000008: Item is in the process of being stranded
:28; // FFFFFFF0: Available bits

struct tagPL_YYSTYPE
*lpYYFcnBase, // 24: Ptr to base function/operator
// Not valid outside the enclosing
// invocation of ParseLine
*lpYYStrandBase, // 28: Ptr to this token's strand base
*lpplYYArgCurry, // 2C: Ptr to left argument curry
*lpplYYIdxCurry, // 30: Ptr to axis curry
*lpplYYFcnCurry, // 34: ... function ...
*lpplYYOpRCurry; // 38: ... right operand ...
LPTOKEN lptkLftBrace, // 3C: Ptr to the AFO's left brace token
lptkRhtBrace; // 40: ... right ...
// 44: Length
} PL_YYSTYPE, *LPPL_YYSTYPE; // Data type of yacc stack; most frequently used is LPPL_YYSTYPE, long pointer to the above structure.
</pre>
* In the above code snippet note the '''nested struct''' formation. '''Inner struct tagPL_YYSTYPE resides within code confines''' of outer struct ''same-name'' tagPL_YYSTYPE. This formation parallels nicely with APL's workspace '''[[System_Command_SI|State Indicator )SI]]''' intrinsic Interpreter design feature which is used for APL-programmer debugging purposes. 
* For ⎕ System Function and Primary APL Function calls, the above typedef is the normal or the expected - '''returned value-group''', the returned value-set structure. Further, since NARS by its very nature handles nested arrays, the above structure similarly manages nested data arrays well. In case it is not obvious to anyone reading this web page or examining NARS source code - NARS represents a highly evolved, data-fluid, APL Interpreter with a full, rich symbol-set programming environment.
 
'''LPPL_YYSTYPE''' is customarily used as a '''variable-type''', as per the following: 
LPPL_YYSTYPE lpYYRes = NULL, // initialize, lpYYRes will be Ptr to result of a ⎕ quad System Function or Primary APL Function call
and '''macro YYAlloc''' (def. file <macros.h>) call instantiated, then with specific values inserted: 
lpYYRes = YYAlloc (); // Allocate free memory, fill LPPL_YYSTYPE memory structure with default setup/values, e.g. <qf_ec.c>
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

<hr width=25%>

===TOKEN===

Full definition for typedef '''TOKEN''': found in file <'''tokens.h'''>:
<pre>
typedef struct tagTOKEN
{
TKFLAGS tkFlags; // 00: The flags part (numbers shown at left are beginning byte # in structure)
SO_ENUM tkSynObj; // 04: The Syntax Object for this token
TOKEN_DATA tkData; // 08: The data part (16 bytes=18 Hex - 08 Hex = 10 Hex)
int tkCharIndex; // 18: Index into the input line of this token
// 1C: Length (1C Hex = 16+12 decimal = byte #28)
} TOKEN, *LPTOKEN;
</pre>

Primary sample usage: Above typedef TOKEN is the first type-var found in '''[[Frequently_Used_TypeDef_Structures_and_Variables#LPPL_YYSTYPE|typedef LPPL_YYSTYPE]]''' above, ref. TOKEN use just below:
<pre>
TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)
</pre>
Linked or indirect referencing through typed variable-name example: (to fill in a result token):
<pre>
// Sample token type choices: TKT_VARNAMED, TKT_VARIMMED, TKT_LSTIMMED, TKT_LSTARRAY, TKT_LSTMULT, TKT_VARARRAY(primary), TKT_STRAND and TKT_STRING.
// Full list of token types found in file <tokens.h>. TKT_VARARRAY used just below:
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
</pre>

==tkToken Commonly Used Structures==
C Source Code Sample Short List of '''tkToken Structure Groupings''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References and '''Frequencies''' (per C:\NARS2000\trunk qf_*.c/pf_*.c files) as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure/Value
! Overall Found Freq
! Overall Found % Tot
|-
| qf_ec.c|| 237|| tkToken|| 820|| 100.0%
|-
| qf_a.c|| 67|| tkToken.tkCharIndex|| 134|| 16.3%
|-
| pf_cstile.c|| 182|| tkToken.tkData.tkBoolean|| 13|| 1.6%
|-
| qf_tc.c|| 162|| tkToken.tkData.tkChar|| 5|| 0.6%
|-
| qf_dl.c|| 179|| tkToken.tkData.tkFloat|| 9|| 1.1%
|-
| qf_a.c|| 66|| tkToken.tkData.tkGlbData|| 135|| 16.5%
|-
| qf_dr.c|| 98|| tkToken.tkData.tkInteger|| 25|| 3.0%
|-
| qf_dr.c|| 309|| tkToken.tkData.tkLongest|| 18|| 2.2%
|-
| qf_ec.c|| 275|| tkToken.tkData.tkSym|| 3|| 0.4%
|-
| qf_ec.c|| 268|| tkToken.tkData.tkVoid|| 1|| 0.1%
|-
| qf_a.c|| 64|| tkToken.tkFlags.ImmType|| 145|| 17.7%
|-
| qf_a.c|| 65|| tkToken.tkFlags.NoDisplay|| 140|| 17.1%
|-
| qf_a.c|| 63|| tkToken.tkFlags.TknType|| 148|| 18.0%
|-
| pf_index.c|| 774|| tkToken.tkSynObj|| 1|| 0.1%
|-
|}
One analogy to NARS tkToken structure groupings can be found in Particle Physics where Quarks, Leptons, Gluons and Gravitons comprise a particle class known as '''[http://physics.about.com/od/atomsparticles/a/particles.htm Fermions]'''. NARS tkToken structure groupings, just as is true for Fermions, allows for a wide range of C coded functionality groupings. tkToken is a convenient way of grouping several pieces of related information together with flexibility for handling '''potentially broadly different''' datatypes, shapes and even functionality. A nested matrix of mixed elements can be handled, as well accommodation for workspace state indicator stack value-sets - all within tkToken structures.

==tkToken Structures More Detailed Sample Uses Table==
C Source Code '''Sample Uses''' Unique (duplicates removed) List of '''tkToken Structure = Values''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References (per C:\NARS2000\trunk qf_*.c/pf_*.c files), sorted by source filename, as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Ref. Variable Name -> Structure Group = Value
|-
| qf_a.c|| 63|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| qf_a.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadA);
|-
| qf_a.c|| 67|| lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| qf_at.c|| 406|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
|-
| qf_av.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadAV);
|-
| qf_d.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadD);
|-
| qf_dl.c|| 176|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
|-
| qf_dl.c|| 177|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
|-
| qf_dl.c|| 179|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRht;
|-
| qf_dr.c|| 96|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_INT;
|-
| qf_dr.c|| 110|| lpYYRes->tkToken.tkData.tkInteger = DR_BOOL;
|-
| qf_dr.c|| 115|| lpYYRes->tkToken.tkData.tkInteger = DR_INT64;
|-
| qf_dr.c|| 120|| lpYYRes->tkToken.tkData.tkInteger = DR_FLOAT;
|-
| qf_dr.c|| 125|| lpYYRes->tkToken.tkData.tkInteger = DR_CHAR16;
|-
| qf_dr.c|| 130|| lpYYRes->tkToken.tkData.tkInteger = DR_APA;
|-
| qf_dr.c|| 135|| lpYYRes->tkToken.tkData.tkInteger = DR_HETERO;
|-
| qf_dr.c|| 140|| lpYYRes->tkToken.tkData.tkInteger = DR_NESTED;
|-
| qf_dr.c|| 145|| lpYYRes->tkToken.tkData.tkInteger = DR_RAT;
|-
| qf_dr.c|| 150|| lpYYRes->tkToken.tkData.tkInteger = DR_VFP;
|-
| qf_dr.c|| 307|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRes;
|-
| qf_dr.c|| 309|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRes;
|-
| qf_em.c|| 70|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRes;
|-
| qf_fx.c|| 353|| lpYYRes->tkToken.tkData.tkInteger = GetQuadIO () + SF_Fcns.uErrLine;
|-
| qf_mf.c|| 493|| lpYYRes->tkToken.tkData.tkInteger = aplIntegerRes;
|-
| qf_mf.c|| 506|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRes;
|-
| qf_mf.c|| 806|| lpYYRes->tkToken.tkFlags.NoDisplay = TRUE;
|-
| qf_nfns.c|| 275|| lpYYRes->tkToken.tkData.tkInteger = aplFileOff;
|-
| qf_nfns.c|| 592|| lpYYRes->tkToken.tkFlags.NoDisplay = (aplLongestRht NE 0);
|-
| qf_nfns.c|| 593|| lpYYRes->tkToken.tkData.tkInteger = TieNum;
|-
| qf_nfns.c|| 1083|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRht;
|-
| qf_nfns.c|| 1091|| lpYYRes->tkToken.tkData.tkInteger = aplLongestRht;
|-
| qf_nfns.c|| 3298|| lpYYRes->tkToken.tkData.tkInteger = aplFileSize;
|-
| qf_t.c|| 75|| lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
|-
| qf_tc.c|| 160|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_CHAR;
|-
| qf_tc.c|| 162|| lpYYRes->tkToken.tkData.tkChar = wc;
|-
| qf_ucs.c|| 206|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRht;
|-
| qf_wa.c|| 70|| lpYYRes->tkToken.tkData.tkInteger = msex.ullAvailPhys + msex.ullAvailPageFile;
|-
| pf_bar.c|| 323|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (*lphGlbRes);
|-
| pf_cslope.c|| 255|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_cslope.c|| 259|| lpYYRes2 = PrimFnDydCircleSlope_EM_YY (&lpYYRes->tkToken,
|-
| pf_cslope.c|| 416|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkData.tkSym->stFlags.ImmType;
|-
| pf_cslope.c|| 418|| lpYYRes->tkToken.tkData.tkLongest = lptkRhtArg->tkData.tkSym->stData.stLongest;
|-
| pf_cslope.c|| 425|| lpYYRes->tkToken = *lptkRhtArg;
|-
| pf_cstile.c|| 178|| lpYYRes->tkToken = tkZero;
|-
| pf_cstile.c|| 252|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_BOOL;
|-
| pf_cstile.c|| 374|| lpYYRes->tkToken = *CopyToken_EM (lptkRhtArg, FALSE);
|-
| pf_darrow.c|| 372|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeRht);
|-
| pf_domino.c|| 220|| lpYYRes->tkToken.tkData.tkBoolean = 1;
|-
| pf_domino.c|| 481|| lpYYRes->tkToken.tkFlags.TknType =
|-
| pf_domino.c|| 526|| lpYYRes->tkToken.tkData.tkGlbData =
|-
| pf_dshoe.c|| 161|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbZilde);
|-
| pf_dshoe.c|| 480|| hGlbGup = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_dtack.c|| 219|| lpYYRes->tkToken.tkData.tkBoolean = FALSE;
|-
| pf_dtack.c|| 224|| lpYYRes->tkToken.tkData.tkInteger = 0;
|-
| pf_dtack.c|| 229|| lpYYRes->tkToken.tkData.tkFloat = 0;
|-
| pf_dtack.c|| 234|| lpYYRes->tkToken.tkData.tkChar = L' ';
|-
| pf_dtack.c|| 248|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkFlags.ImmType;
|-
| pf_dtack.c|| 309|| lpYYRes->tkToken.tkData.tkGlbData = hSymGlbRes;
|-
| pf_dtackjot.c|| 375|| lpYYRes->tkToken.tkData.tkChar = aplCharRht;
|-
| pf_epsilon.c|| 2398|| hGlbGupLft = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 2429|| hGlbGupRht = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 3731|| bCmp = lpYYTmp->tkToken.tkData.tkBoolean;
|-
| pf_epsund.c|| 279|| lpYYRes->tkToken.tkData.tkBoolean =       // Filled in below
|-
| pf_epsund.c|| 288|| lpMemRes = &lpYYRes->tkToken.tkData.tkBoolean;
|-
| pf_equalund.c|| 532|| lpYYRes->tkToken.tkData.tkBoolean = (APLBOOL) ((BIT0 & aplIntegerRes) NE bNotEqual);
|-
| pf_index.c|| 117|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeNam);
|-
| pf_index.c|| 119|| lpYYRes->tkToken.tkData.tkLongest = aplLongestNam;
|-
| pf_index.c|| 120|| lpYYRes->tkToken.tkCharIndex = lptkLstArg->tkCharIndex;
|-
| pf_index.c|| 127|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbNam);
|-
| pf_index.c|| 591|| *((LPAPLBOOL) lpMemRes) |= lpYYItm->tkToken.tkData.tkBoolean << uBitIndex;
|-
| pf_index.c|| 604|| *((LPAPLINT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkInteger;
|-
| pf_index.c|| 610|| *((LPAPLFLOAT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkFloat;
|-
| pf_index.c|| 616|| *((LPAPLCHAR) lpMemRes)++ = lpYYItm->tkToken.tkData.tkChar;
|-
| pf_index.c|| 639|| lpSymTmp = MyGlobalLock (lpYYItm->tkToken.tkData.tkGlbData);
|-
| pf_index.c|| 645|| MyGlobalUnlock (lpYYItm->tkToken.tkData.tkGlbData); lpSymTmp = NULL;
|-
| pf_index.c|| 648|| DbgGlobalFree (lpYYItm->tkToken.tkData.tkGlbData); lpYYItm->tkToken.tkData.tkGlbData = NULL;
|-
| pf_index.c|| 774|| lpYYRes->tkToken.tkSynObj = soA;
|-
| pf_index.c|| 878|| lpYYRes->tkToken.tkFlags.ImmType = immTypeNam;
|-
| pf_index.c|| 2016|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTIMMED;
|-
| pf_index.c|| 2019|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTARRAY;
|-
| pf_index.c|| 2514|| lpMemRes[0] = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2546|| hGlbSubRht = lpYYSub->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2913|| lpYYRes2 = PrimFnDydRho_EM_YY (&lpYYRes1->tkToken,
|-
| pf_index.c|| 2924|| hGlbRes = lpYYRes2->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 3593|| hGlbSubLst2 = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 4536|| lpYYRes2 = ExecFuncStr_EM_YY (&lpYYRes1->tkToken,
|-
| pf_lshoe.c|| 212|| lpYYRes->tkToken.tkFlags.ImmType = ImmType;
|-
| pf_lshoe.c|| 214|| lpYYRes->tkToken.tkData.tkLongest = aplLongest;
|-
| pf_lshoe.c|| 316|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbRht);
|-
| pf_rshoe.c|| 263|| lpYYRes->tkToken.tkFlags.ImmType = immType;
|-
| pf_rshoe.c|| 1769|| lpYYRes2->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| pf_rshoe.c|| 1772|| lpYYRes2->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_rshoe.c|| 1773|| lpYYRes2->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| pf_rshoe.c|| 1776|| lpYYRes3 = PrimFnDydCircleSlope_EM_YY (&lpYYRes2->tkToken,
|-
| pf_rshoe.c|| 1996|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRht;
|-
| pf_rshoe.c|| 2396|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRes, aplTypeRht, lptkFunc);
|-
| pf_rshoe.c|| 3014|| lpYYRes->tkToken.tkFlags.ImmType = immTypeSubRht;
|-
| pf_rshoe.c|| 3016|| lpYYRes->tkToken.tkData.tkLongest = aplLongestSubRht;
|-
| pf_rshoe.c|| 3034|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRht, aplTypeRht, lptkFunc);
|-
| pf_rtack.c|| 188|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbArg);
|-
| pf_rtack.c|| 194|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplType);
|-
| pf_squad.c|| 228|| lpMemRht = &lpYYRht->tkToken.tkData.tkInteger;
|-
| pf_squad.c|| 232|| hGlbRht = lpYYRht->tkToken.tkData.tkGlbData;
|-
| pf_squad.c|| 278|| *lpMemRes++ = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_uarrow.c|| 232|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (lpSymGlb, aplTypeRht, lptkFunc);
|-
| pf_utackjot.c|| 379|| lpYYRes->tkToken.tkFlags.NoDisplay |= (exitType EQ EXITTYPE_NODISPLAY);
|-
|} 

==Variable Types==

==Variables==

Frequently Used TypeDef Structures and Variables

2015-08-18T14:13:27Z

Robert Wallick: /* tkToken Structures More Detailed Sample Uses Table */ corrected vertical bar as amp pound 124 semicolon or |

'''<big>NARS C Source Code Frequently Used TypeDef Structures and Variables:</big>'''

NARS has multiple frequently used TypeDefs, Structures, Type-Variables and Variables. Familiarity with these structures, including variables employed, is essential toward gaining increased understanding of how NARS C source code works, including insight into C program flow.

==TypeDefs==

===LPPL_YYSTYPE===

Full definition for typedef '''LPPL_YYTYPE''': found in file <'''pl_parse.h'''>. '''Partial''', extracted, compiler-directives-excluded/simplified definition:
<pre>
typedef struct tagPL_YYSTYPE // YYSTYPE for ParseLine
{
// N.B.: The first item in this struct *MUST* be the TOKEN
// because when we pass it as an argument to an LPPRIMFNS
// we might need it to be an LPPL_YYSTYPE (for a function strand)
// or an LPTOKEN (single function).
TOKEN tkToken; // 00: Token info (28 bytes)
UINT TknCount; // 1C: Count of adjacent tokens including this one
UINT YYInuse:1, // 20: 00000001: This entry is in use
YYIndirect:1, // 00000002: Arg is indirect
YYPerm:1, // 00000004: Item is permanent, don't free
YYStranding:1, // 00000008: Item is in the process of being stranded
:28; // FFFFFFF0: Available bits

struct tagPL_YYSTYPE
*lpYYFcnBase, // 24: Ptr to base function/operator
// Not valid outside the enclosing
// invocation of ParseLine
*lpYYStrandBase, // 28: Ptr to this token's strand base
*lpplYYArgCurry, // 2C: Ptr to left argument curry
*lpplYYIdxCurry, // 30: Ptr to axis curry
*lpplYYFcnCurry, // 34: ... function ...
*lpplYYOpRCurry; // 38: ... right operand ...
LPTOKEN lptkLftBrace, // 3C: Ptr to the AFO's left brace token
lptkRhtBrace; // 40: ... right ...
// 44: Length
} PL_YYSTYPE, *LPPL_YYSTYPE; // Data type of yacc stack; most frequently used is LPPL_YYSTYPE, long pointer to the above structure.
</pre>
* In the above code snippet note the '''nested struct''' formation. '''Inner struct tagPL_YYSTYPE resides within code confines''' of outer struct ''same-name'' tagPL_YYSTYPE. This formation parallels nicely with APL's workspace '''[[System_Command_SI|State Indicator )SI]]''' intrinsic Interpreter design feature which is used for APL-programmer debugging purposes. 
* For ⎕ System Function and Primary APL Function calls, the above typedef is the normal or the expected - '''returned value-group''', the returned value-set structure. Further, since NARS by its very nature handles nested arrays, the above structure similarly manages nested data arrays well. In case it is not obvious to anyone reading this web page or examining NARS source code - NARS represents a highly evolved, data-fluid, APL Interpreter with a full, rich symbol-set programming environment.
 
'''LPPL_YYSTYPE''' is customarily used as a '''variable-type''', as per the following: 
LPPL_YYSTYPE lpYYRes = NULL, // initialize, lpYYRes will be Ptr to result of a ⎕ quad System Function or Primary APL Function call
and '''macro YYAlloc''' (def. file <macros.h>) call instantiated, then with specific values inserted: 
lpYYRes = YYAlloc (); // Allocate free memory, fill LPPL_YYSTYPE memory structure with default setup/values, e.g. <qf_ec.c>
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

<hr width=25%>

===TOKEN===

Full definition for typedef '''TOKEN''': found in file <'''tokens.h'''>:
<pre>
typedef struct tagTOKEN
{
TKFLAGS tkFlags; // 00: The flags part (numbers shown at left are beginning byte # in structure)
SO_ENUM tkSynObj; // 04: The Syntax Object for this token
TOKEN_DATA tkData; // 08: The data part (16 bytes=18 Hex - 08 Hex = 10 Hex)
int tkCharIndex; // 18: Index into the input line of this token
// 1C: Length (1C Hex = 16+12 decimal = byte #28)
} TOKEN, *LPTOKEN;
</pre>

Primary sample usage: Above typedef TOKEN is the first type-var found in '''[[Frequently_Used_TypeDef_Structures_and_Variables#LPPL_YYSTYPE|typedef LPPL_YYSTYPE]]''' above, ref. TOKEN use just below:
<pre>
TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)
</pre>
Linked or indirect referencing through typed variable-name example: (to fill in a result token):
<pre>
// Sample token type choices: TKT_VARNAMED, TKT_VARIMMED, TKT_LSTIMMED, TKT_LSTARRAY, TKT_LSTMULT, TKT_VARARRAY(primary), TKT_STRAND and TKT_STRING.
// Full list of token types found in file <tokens.h>. TKT_VARARRAY used just below:
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
</pre>

==tkToken Commonly Used Structures==
C Source Code Sample Short List of '''tkToken Structure Groupings''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References and '''Frequencies''' (per C:\NARS2000\trunk qf_*.c/pf_*.c files) as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure/Value
! Overall Found Freq
! Overall Found % Tot
|-
| qf_ec.c|| 237|| tkToken|| 820|| 100.0%
|-
| qf_a.c|| 67|| tkToken.tkCharIndex|| 134|| 16.3%
|-
| pf_cstile.c|| 182|| tkToken.tkData.tkBoolean|| 13|| 1.6%
|-
| qf_tc.c|| 162|| tkToken.tkData.tkChar|| 5|| 0.6%
|-
| qf_dl.c|| 179|| tkToken.tkData.tkFloat|| 9|| 1.1%
|-
| qf_a.c|| 66|| tkToken.tkData.tkGlbData|| 135|| 16.5%
|-
| qf_dr.c|| 98|| tkToken.tkData.tkInteger|| 25|| 3.0%
|-
| qf_dr.c|| 309|| tkToken.tkData.tkLongest|| 18|| 2.2%
|-
| qf_ec.c|| 275|| tkToken.tkData.tkSym|| 3|| 0.4%
|-
| qf_ec.c|| 268|| tkToken.tkData.tkVoid|| 1|| 0.1%
|-
| qf_a.c|| 64|| tkToken.tkFlags.ImmType|| 145|| 17.7%
|-
| qf_a.c|| 65|| tkToken.tkFlags.NoDisplay|| 140|| 17.1%
|-
| qf_a.c|| 63|| tkToken.tkFlags.TknType|| 148|| 18.0%
|-
| pf_index.c|| 774|| tkToken.tkSynObj|| 1|| 0.1%
|-
|}
One analogy to NARS tkToken structure groupings can be found in Particle Physics where Quarks, Leptons, Gluons and Gravitons comprise a particle class known as '''[http://physics.about.com/od/atomsparticles/a/particles.htm Fermions]'''. NARS tkToken structure groupings, just as is true for Fermions, allows for a wide range of C coded functionality groupings. tkToken is a convenient way of grouping several pieces of related information together with flexibility for handling '''potentially broadly different''' datatypes, shapes and even functionality. A nested matrix of mixed elements can be handled, as well accommodation for workspace state indicator stack value-sets - all within tkToken structures.

==tkToken Structures More Detailed Sample Uses Table==
C Source Code '''Sample Uses''' Unique (duplicates removed) List of '''tkToken Structure = Values''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References (per C:\NARS2000\trunk qf_*.c/pf_*.c files), sorted by source filename, as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Ref. Variable Name -> Structure Group = Value
|-
| qf_a.c|| 63|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| qf_a.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadA);
|-
| qf_a.c|| 67|| lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| qf_at.c|| 406|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
|-
| qf_av.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadAV);
|-
| qf_d.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadD);
|-
| qf_dl.c|| 176|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
|-
| qf_dl.c|| 177|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
|-
| qf_dl.c|| 179|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRht;
|-
| qf_dr.c|| 96|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_INT;
|-
| qf_dr.c|| 110|| lpYYRes->tkToken.tkData.tkInteger = DR_BOOL;
|-
| qf_dr.c|| 115|| lpYYRes->tkToken.tkData.tkInteger = DR_INT64;
|-
| qf_dr.c|| 120|| lpYYRes->tkToken.tkData.tkInteger = DR_FLOAT;
|-
| qf_dr.c|| 125|| lpYYRes->tkToken.tkData.tkInteger = DR_CHAR16;
|-
| qf_dr.c|| 130|| lpYYRes->tkToken.tkData.tkInteger = DR_APA;
|-
| qf_dr.c|| 135|| lpYYRes->tkToken.tkData.tkInteger = DR_HETERO;
|-
| qf_dr.c|| 140|| lpYYRes->tkToken.tkData.tkInteger = DR_NESTED;
|-
| qf_dr.c|| 145|| lpYYRes->tkToken.tkData.tkInteger = DR_RAT;
|-
| qf_dr.c|| 150|| lpYYRes->tkToken.tkData.tkInteger = DR_VFP;
|-
| qf_dr.c|| 307|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRes;
|-
| qf_dr.c|| 309|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRes;
|-
| qf_em.c|| 70|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRes;
|-
| qf_fx.c|| 353|| lpYYRes->tkToken.tkData.tkInteger = GetQuadIO () + SF_Fcns.uErrLine;
|-
| qf_mf.c|| 493|| lpYYRes->tkToken.tkData.tkInteger = aplIntegerRes;
|-
| qf_mf.c|| 506|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRes;
|-
| qf_mf.c|| 806|| lpYYRes->tkToken.tkFlags.NoDisplay = TRUE;
|-
| qf_nfns.c|| 275|| lpYYRes->tkToken.tkData.tkInteger = aplFileOff;
|-
| qf_nfns.c|| 592|| lpYYRes->tkToken.tkFlags.NoDisplay = (aplLongestRht NE 0);
|-
| qf_nfns.c|| 593|| lpYYRes->tkToken.tkData.tkInteger = TieNum;
|-
| qf_nfns.c|| 1083|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRht;
|-
| qf_nfns.c|| 1091|| lpYYRes->tkToken.tkData.tkInteger = aplLongestRht;
|-
| qf_nfns.c|| 3298|| lpYYRes->tkToken.tkData.tkInteger = aplFileSize;
|-
| qf_t.c|| 75|| lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
|-
| qf_tc.c|| 160|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_CHAR;
|-
| qf_tc.c|| 162|| lpYYRes->tkToken.tkData.tkChar = wc;
|-
| qf_ucs.c|| 206|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRht;
|-
| qf_wa.c|| 70|| lpYYRes->tkToken.tkData.tkInteger = msex.ullAvailPhys + msex.ullAvailPageFile;
|-
| pf_bar.c|| 323|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (*lphGlbRes);
|-
| pf_cslope.c|| 255|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_cslope.c|| 259|| lpYYRes2 = PrimFnDydCircleSlope_EM_YY (&lpYYRes->tkToken,
|-
| pf_cslope.c|| 416|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkData.tkSym->stFlags.ImmType;
|-
| pf_cslope.c|| 418|| lpYYRes->tkToken.tkData.tkLongest = lptkRhtArg->tkData.tkSym->stData.stLongest;
|-
| pf_cslope.c|| 425|| lpYYRes->tkToken = *lptkRhtArg;
|-
| pf_cstile.c|| 178|| lpYYRes->tkToken = tkZero;
|-
| pf_cstile.c|| 252|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_BOOL;
|-
| pf_cstile.c|| 374|| lpYYRes->tkToken = *CopyToken_EM (lptkRhtArg, FALSE);
|-
| pf_darrow.c|| 372|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeRht);
|-
| pf_domino.c|| 220|| lpYYRes->tkToken.tkData.tkBoolean = 1;
|-
| pf_domino.c|| 481|| lpYYRes->tkToken.tkFlags.TknType =
|-
| pf_domino.c|| 526|| lpYYRes->tkToken.tkData.tkGlbData =
|-
| pf_dshoe.c|| 161|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbZilde);
|-
| pf_dshoe.c|| 480|| hGlbGup = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_dtack.c|| 219|| lpYYRes->tkToken.tkData.tkBoolean = FALSE;
|-
| pf_dtack.c|| 224|| lpYYRes->tkToken.tkData.tkInteger = 0;
|-
| pf_dtack.c|| 229|| lpYYRes->tkToken.tkData.tkFloat = 0;
|-
| pf_dtack.c|| 234|| lpYYRes->tkToken.tkData.tkChar = L' ';
|-
| pf_dtack.c|| 248|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkFlags.ImmType;
|-
| pf_dtack.c|| 309|| lpYYRes->tkToken.tkData.tkGlbData = hSymGlbRes;
|-
| pf_dtackjot.c|| 375|| lpYYRes->tkToken.tkData.tkChar = aplCharRht;
|-
| pf_epsilon.c|| 2398|| hGlbGupLft = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 2429|| hGlbGupRht = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 3731|| bCmp = lpYYTmp->tkToken.tkData.tkBoolean;
|-
| pf_epsund.c|| 279|| lpYYRes->tkToken.tkData.tkBoolean =
|-
| pf_epsund.c|| 288|| lpMemRes = &lpYYRes->tkToken.tkData.tkBoolean;
|-
| pf_equalund.c|| 532|| lpYYRes->tkToken.tkData.tkBoolean = (APLBOOL) ((BIT0 & aplIntegerRes) NE bNotEqual);
|-
| pf_index.c|| 117|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeNam);
|-
| pf_index.c|| 119|| lpYYRes->tkToken.tkData.tkLongest = aplLongestNam;
|-
| pf_index.c|| 120|| lpYYRes->tkToken.tkCharIndex = lptkLstArg->tkCharIndex;
|-
| pf_index.c|| 127|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbNam);
|-
| pf_index.c|| 591|| *((LPAPLBOOL) lpMemRes) |= lpYYItm->tkToken.tkData.tkBoolean << uBitIndex;
|-
| pf_index.c|| 604|| *((LPAPLINT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkInteger;
|-
| pf_index.c|| 610|| *((LPAPLFLOAT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkFloat;
|-
| pf_index.c|| 616|| *((LPAPLCHAR) lpMemRes)++ = lpYYItm->tkToken.tkData.tkChar;
|-
| pf_index.c|| 639|| lpSymTmp = MyGlobalLock (lpYYItm->tkToken.tkData.tkGlbData);
|-
| pf_index.c|| 645|| MyGlobalUnlock (lpYYItm->tkToken.tkData.tkGlbData); lpSymTmp = NULL;
|-
| pf_index.c|| 648|| DbgGlobalFree (lpYYItm->tkToken.tkData.tkGlbData); lpYYItm->tkToken.tkData.tkGlbData = NULL;
|-
| pf_index.c|| 774|| lpYYRes->tkToken.tkSynObj = soA;
|-
| pf_index.c|| 878|| lpYYRes->tkToken.tkFlags.ImmType = immTypeNam;
|-
| pf_index.c|| 2016|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTIMMED;
|-
| pf_index.c|| 2019|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTARRAY;
|-
| pf_index.c|| 2514|| lpMemRes[0] = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2546|| hGlbSubRht = lpYYSub->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2913|| lpYYRes2 = PrimFnDydRho_EM_YY (&lpYYRes1->tkToken,
|-
| pf_index.c|| 2924|| hGlbRes = lpYYRes2->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 3593|| hGlbSubLst2 = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 4536|| lpYYRes2 = ExecFuncStr_EM_YY (&lpYYRes1->tkToken,
|-
| pf_lshoe.c|| 212|| lpYYRes->tkToken.tkFlags.ImmType = ImmType;
|-
| pf_lshoe.c|| 214|| lpYYRes->tkToken.tkData.tkLongest = aplLongest;
|-
| pf_lshoe.c|| 316|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbRht);
|-
| pf_rshoe.c|| 263|| lpYYRes->tkToken.tkFlags.ImmType = immType;
|-
| pf_rshoe.c|| 1769|| lpYYRes2->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| pf_rshoe.c|| 1772|| lpYYRes2->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_rshoe.c|| 1773|| lpYYRes2->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| pf_rshoe.c|| 1776|| lpYYRes3 = PrimFnDydCircleSlope_EM_YY (&lpYYRes2->tkToken,
|-
| pf_rshoe.c|| 1996|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRht;
|-
| pf_rshoe.c|| 2396|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRes, aplTypeRht, lptkFunc);
|-
| pf_rshoe.c|| 3014|| lpYYRes->tkToken.tkFlags.ImmType = immTypeSubRht;
|-
| pf_rshoe.c|| 3016|| lpYYRes->tkToken.tkData.tkLongest = aplLongestSubRht;
|-
| pf_rshoe.c|| 3034|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRht, aplTypeRht, lptkFunc);
|-
| pf_rtack.c|| 188|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbArg);
|-
| pf_rtack.c|| 194|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplType);
|-
| pf_squad.c|| 228|| lpMemRht = &lpYYRht->tkToken.tkData.tkInteger;
|-
| pf_squad.c|| 232|| hGlbRht = lpYYRht->tkToken.tkData.tkGlbData;
|-
| pf_squad.c|| 278|| *lpMemRes++ = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_uarrow.c|| 232|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (lpSymGlb, aplTypeRht, lptkFunc);
|-
| pf_utackjot.c|| 379|| lpYYRes->tkToken.tkFlags.NoDisplay |= (exitType EQ EXITTYPE_NODISPLAY);
|-
|} 

==Variable Types==

==Variables==

Frequently Used TypeDef Structures and Variables

2015-08-18T13:55:55Z

Robert Wallick: /* tkToken Structures More Detailed Sample Uses Table */

'''<big>NARS C Source Code Frequently Used TypeDef Structures and Variables:</big>'''

NARS has multiple frequently used TypeDefs, Structures, Type-Variables and Variables. Familiarity with these structures, including variables employed, is essential toward gaining increased understanding of how NARS C source code works, including insight into C program flow.

==TypeDefs==

===LPPL_YYSTYPE===

Full definition for typedef '''LPPL_YYTYPE''': found in file <'''pl_parse.h'''>. '''Partial''', extracted, compiler-directives-excluded/simplified definition:
<pre>
typedef struct tagPL_YYSTYPE // YYSTYPE for ParseLine
{
// N.B.: The first item in this struct *MUST* be the TOKEN
// because when we pass it as an argument to an LPPRIMFNS
// we might need it to be an LPPL_YYSTYPE (for a function strand)
// or an LPTOKEN (single function).
TOKEN tkToken; // 00: Token info (28 bytes)
UINT TknCount; // 1C: Count of adjacent tokens including this one
UINT YYInuse:1, // 20: 00000001: This entry is in use
YYIndirect:1, // 00000002: Arg is indirect
YYPerm:1, // 00000004: Item is permanent, don't free
YYStranding:1, // 00000008: Item is in the process of being stranded
:28; // FFFFFFF0: Available bits

struct tagPL_YYSTYPE
*lpYYFcnBase, // 24: Ptr to base function/operator
// Not valid outside the enclosing
// invocation of ParseLine
*lpYYStrandBase, // 28: Ptr to this token's strand base
*lpplYYArgCurry, // 2C: Ptr to left argument curry
*lpplYYIdxCurry, // 30: Ptr to axis curry
*lpplYYFcnCurry, // 34: ... function ...
*lpplYYOpRCurry; // 38: ... right operand ...
LPTOKEN lptkLftBrace, // 3C: Ptr to the AFO's left brace token
lptkRhtBrace; // 40: ... right ...
// 44: Length
} PL_YYSTYPE, *LPPL_YYSTYPE; // Data type of yacc stack; most frequently used is LPPL_YYSTYPE, long pointer to the above structure.
</pre>
* In the above code snippet note the '''nested struct''' formation. '''Inner struct tagPL_YYSTYPE resides within code confines''' of outer struct ''same-name'' tagPL_YYSTYPE. This formation parallels nicely with APL's workspace '''[[System_Command_SI|State Indicator )SI]]''' intrinsic Interpreter design feature which is used for APL-programmer debugging purposes. 
* For ⎕ System Function and Primary APL Function calls, the above typedef is the normal or the expected - '''returned value-group''', the returned value-set structure. Further, since NARS by its very nature handles nested arrays, the above structure similarly manages nested data arrays well. In case it is not obvious to anyone reading this web page or examining NARS source code - NARS represents a highly evolved, data-fluid, APL Interpreter with a full, rich symbol-set programming environment.
 
'''LPPL_YYSTYPE''' is customarily used as a '''variable-type''', as per the following: 
LPPL_YYSTYPE lpYYRes = NULL, // initialize, lpYYRes will be Ptr to result of a ⎕ quad System Function or Primary APL Function call
and '''macro YYAlloc''' (def. file <macros.h>) call instantiated, then with specific values inserted: 
lpYYRes = YYAlloc (); // Allocate free memory, fill LPPL_YYSTYPE memory structure with default setup/values, e.g. <qf_ec.c>
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

<hr width=25%>

===TOKEN===

Full definition for typedef '''TOKEN''': found in file <'''tokens.h'''>:
<pre>
typedef struct tagTOKEN
{
TKFLAGS tkFlags; // 00: The flags part (numbers shown at left are beginning byte # in structure)
SO_ENUM tkSynObj; // 04: The Syntax Object for this token
TOKEN_DATA tkData; // 08: The data part (16 bytes=18 Hex - 08 Hex = 10 Hex)
int tkCharIndex; // 18: Index into the input line of this token
// 1C: Length (1C Hex = 16+12 decimal = byte #28)
} TOKEN, *LPTOKEN;
</pre>

Primary sample usage: Above typedef TOKEN is the first type-var found in '''[[Frequently_Used_TypeDef_Structures_and_Variables#LPPL_YYSTYPE|typedef LPPL_YYSTYPE]]''' above, ref. TOKEN use just below:
<pre>
TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)
</pre>
Linked or indirect referencing through typed variable-name example: (to fill in a result token):
<pre>
// Sample token type choices: TKT_VARNAMED, TKT_VARIMMED, TKT_LSTIMMED, TKT_LSTARRAY, TKT_LSTMULT, TKT_VARARRAY(primary), TKT_STRAND and TKT_STRING.
// Full list of token types found in file <tokens.h>. TKT_VARARRAY used just below:
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
</pre>

==tkToken Commonly Used Structures==
C Source Code Sample Short List of '''tkToken Structure Groupings''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References and '''Frequencies''' (per C:\NARS2000\trunk qf_*.c/pf_*.c files) as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure/Value
! Overall Found Freq
! Overall Found % Tot
|-
| qf_ec.c|| 237|| tkToken|| 820|| 100.0%
|-
| qf_a.c|| 67|| tkToken.tkCharIndex|| 134|| 16.3%
|-
| pf_cstile.c|| 182|| tkToken.tkData.tkBoolean|| 13|| 1.6%
|-
| qf_tc.c|| 162|| tkToken.tkData.tkChar|| 5|| 0.6%
|-
| qf_dl.c|| 179|| tkToken.tkData.tkFloat|| 9|| 1.1%
|-
| qf_a.c|| 66|| tkToken.tkData.tkGlbData|| 135|| 16.5%
|-
| qf_dr.c|| 98|| tkToken.tkData.tkInteger|| 25|| 3.0%
|-
| qf_dr.c|| 309|| tkToken.tkData.tkLongest|| 18|| 2.2%
|-
| qf_ec.c|| 275|| tkToken.tkData.tkSym|| 3|| 0.4%
|-
| qf_ec.c|| 268|| tkToken.tkData.tkVoid|| 1|| 0.1%
|-
| qf_a.c|| 64|| tkToken.tkFlags.ImmType|| 145|| 17.7%
|-
| qf_a.c|| 65|| tkToken.tkFlags.NoDisplay|| 140|| 17.1%
|-
| qf_a.c|| 63|| tkToken.tkFlags.TknType|| 148|| 18.0%
|-
| pf_index.c|| 774|| tkToken.tkSynObj|| 1|| 0.1%
|-
|}
One analogy to NARS tkToken structure groupings can be found in Particle Physics where Quarks, Leptons, Gluons and Gravitons comprise a particle class known as '''[http://physics.about.com/od/atomsparticles/a/particles.htm Fermions]'''. NARS tkToken structure groupings, just as is true for Fermions, allows for a wide range of C coded functionality groupings. tkToken is a convenient way of grouping several pieces of related information together with flexibility for handling '''potentially broadly different''' datatypes, shapes and even functionality. A nested matrix of mixed elements can be handled, as well accommodation for workspace state indicator stack value-sets - all within tkToken structures.

==tkToken Structures More Detailed Sample Uses Table==
C Source Code '''Sample Uses''' Unique (duplicates removed) List of '''tkToken Structure = Values''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References (per C:\NARS2000\trunk qf_*.c/pf_*.c files), sorted by source filename, as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Ref. Variable Name -> Structure Group = Value
|-
| qf_a.c|| 63|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| qf_a.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadA);
|-
| qf_a.c|| 67|| lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| qf_at.c|| 406|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
|-
| qf_av.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadAV);
|-
| qf_d.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadD);
|-
| qf_dl.c|| 176|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
|-
| qf_dl.c|| 177|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
|-
| qf_dl.c|| 179|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRht;
|-
| qf_dr.c|| 96|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_INT;
|-
| qf_dr.c|| 110|| lpYYRes->tkToken.tkData.tkInteger = DR_BOOL;
|-
| qf_dr.c|| 115|| lpYYRes->tkToken.tkData.tkInteger = DR_INT64;
|-
| qf_dr.c|| 120|| lpYYRes->tkToken.tkData.tkInteger = DR_FLOAT;
|-
| qf_dr.c|| 125|| lpYYRes->tkToken.tkData.tkInteger = DR_CHAR16;
|-
| qf_dr.c|| 130|| lpYYRes->tkToken.tkData.tkInteger = DR_APA;
|-
| qf_dr.c|| 135|| lpYYRes->tkToken.tkData.tkInteger = DR_HETERO;
|-
| qf_dr.c|| 140|| lpYYRes->tkToken.tkData.tkInteger = DR_NESTED;
|-
| qf_dr.c|| 145|| lpYYRes->tkToken.tkData.tkInteger = DR_RAT;
|-
| qf_dr.c|| 150|| lpYYRes->tkToken.tkData.tkInteger = DR_VFP;
|-
| qf_dr.c|| 307|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRes;
|-
| qf_dr.c|| 309|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRes;
|-
| qf_em.c|| 70|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRes;
|-
| qf_fx.c|| 353|| lpYYRes->tkToken.tkData.tkInteger = GetQuadIO () + SF_Fcns.uErrLine;
|-
| qf_mf.c|| 493|| lpYYRes->tkToken.tkData.tkInteger = aplIntegerRes;
|-
| qf_mf.c|| 506|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRes;
|-
| qf_mf.c|| 806|| lpYYRes->tkToken.tkFlags.NoDisplay = TRUE;
|-
| qf_nfns.c|| 275|| lpYYRes->tkToken.tkData.tkInteger = aplFileOff;
|-
| qf_nfns.c|| 592|| lpYYRes->tkToken.tkFlags.NoDisplay = (aplLongestRht NE 0);
|-
| qf_nfns.c|| 593|| lpYYRes->tkToken.tkData.tkInteger = TieNum;
|-
| qf_nfns.c|| 1083|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRht;
|-
| qf_nfns.c|| 1091|| lpYYRes->tkToken.tkData.tkInteger = aplLongestRht;
|-
| qf_nfns.c|| 3298|| lpYYRes->tkToken.tkData.tkInteger = aplFileSize;
|-
| qf_t.c|| 75|| lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
|-
| qf_tc.c|| 160|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_CHAR;
|-
| qf_tc.c|| 162|| lpYYRes->tkToken.tkData.tkChar = wc;
|-
| qf_ucs.c|| 206|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRht;
|-
| qf_wa.c|| 70|| lpYYRes->tkToken.tkData.tkInteger = msex.ullAvailPhys + msex.ullAvailPageFile;
|-
| pf_bar.c|| 323|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (*lphGlbRes);
|-
| pf_cslope.c|| 255|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_cslope.c|| 259|| lpYYRes2 = PrimFnDydCircleSlope_EM_YY (&lpYYRes->tkToken,
|-
| pf_cslope.c|| 416|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkData.tkSym->stFlags.ImmType;
|-
| pf_cslope.c|| 418|| lpYYRes->tkToken.tkData.tkLongest = lptkRhtArg->tkData.tkSym->stData.stLongest;
|-
| pf_cslope.c|| 425|| lpYYRes->tkToken = *lptkRhtArg;
|-
| pf_cstile.c|| 178|| lpYYRes->tkToken = tkZero;
|-
| pf_cstile.c|| 252|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_BOOL;
|-
| pf_cstile.c|| 374|| lpYYRes->tkToken = *CopyToken_EM (lptkRhtArg, FALSE);
|-
| pf_darrow.c|| 372|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeRht);
|-
| pf_domino.c|| 220|| lpYYRes->tkToken.tkData.tkBoolean = 1;
|-
| pf_domino.c|| 481|| lpYYRes->tkToken.tkFlags.TknType =
|-
| pf_domino.c|| 526|| lpYYRes->tkToken.tkData.tkGlbData =
|-
| pf_dshoe.c|| 161|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbZilde);
|-
| pf_dshoe.c|| 480|| hGlbGup = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_dtack.c|| 219|| lpYYRes->tkToken.tkData.tkBoolean = FALSE;
|-
| pf_dtack.c|| 224|| lpYYRes->tkToken.tkData.tkInteger = 0;
|-
| pf_dtack.c|| 229|| lpYYRes->tkToken.tkData.tkFloat = 0;
|-
| pf_dtack.c|| 234|| lpYYRes->tkToken.tkData.tkChar = L' ';
|-
| pf_dtack.c|| 248|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkFlags.ImmType;
|-
| pf_dtack.c|| 309|| lpYYRes->tkToken.tkData.tkGlbData = hSymGlbRes;
|-
| pf_dtackjot.c|| 375|| lpYYRes->tkToken.tkData.tkChar = aplCharRht;
|-
| pf_epsilon.c|| 2398|| hGlbGupLft = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 2429|| hGlbGupRht = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 3731|| bCmp = lpYYTmp->tkToken.tkData.tkBoolean;
|-
| pf_epsund.c|| 279|| lpYYRes->tkToken.tkData.tkBoolean =
|-
| pf_epsund.c|| 288|| lpMemRes = &lpYYRes->tkToken.tkData.tkBoolean;
|-
| pf_equalund.c|| 532|| lpYYRes->tkToken.tkData.tkBoolean = (APLBOOL) ((BIT0 & aplIntegerRes) NE bNotEqual);
|-
| pf_index.c|| 117|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeNam);
|-
| pf_index.c|| 119|| lpYYRes->tkToken.tkData.tkLongest = aplLongestNam;
|-
| pf_index.c|| 120|| lpYYRes->tkToken.tkCharIndex = lptkLstArg->tkCharIndex;
|-
| pf_index.c|| 127|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbNam);
|-
| pf_index.c|| 591|| *((LPAPLBOOL) lpMemRes) |= lpYYItm->tkToken.tkData.tkBoolean << uBitIndex;
|-
| pf_index.c|| 604|| *((LPAPLINT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkInteger;
|-
| pf_index.c|| 610|| *((LPAPLFLOAT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkFloat;
|-
| pf_index.c|| 616|| *((LPAPLCHAR) lpMemRes)++ = lpYYItm->tkToken.tkData.tkChar;
|-
| pf_index.c|| 639|| lpSymTmp = MyGlobalLock (lpYYItm->tkToken.tkData.tkGlbData);
|-
| pf_index.c|| 645|| MyGlobalUnlock (lpYYItm->tkToken.tkData.tkGlbData); lpSymTmp = NULL;
|-
| pf_index.c|| 648|| DbgGlobalFree (lpYYItm->tkToken.tkData.tkGlbData); lpYYItm->tkToken.tkData.tkGlbData = NULL;
|-
| pf_index.c|| 774|| lpYYRes->tkToken.tkSynObj = soA;
|-
| pf_index.c|| 878|| lpYYRes->tkToken.tkFlags.ImmType = immTypeNam;
|-
| pf_index.c|| 2016|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTIMMED;
|-
| pf_index.c|| 2019|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTARRAY;
|-
| pf_index.c|| 2514|| lpMemRes[0] = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2546|| hGlbSubRht = lpYYSub->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2913|| lpYYRes2 = PrimFnDydRho_EM_YY (&lpYYRes1->tkToken,
|-
| pf_index.c|| 2924|| hGlbRes = lpYYRes2->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 3593|| hGlbSubLst2 = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 4536|| lpYYRes2 = ExecFuncStr_EM_YY (&lpYYRes1->tkToken,
|-
| pf_lshoe.c|| 212|| lpYYRes->tkToken.tkFlags.ImmType = ImmType;
|-
| pf_lshoe.c|| 214|| lpYYRes->tkToken.tkData.tkLongest = aplLongest;
|-
| pf_lshoe.c|| 316|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbRht);
|-
| pf_rshoe.c|| 263|| lpYYRes->tkToken.tkFlags.ImmType = immType;
|-
| pf_rshoe.c|| 1769|| lpYYRes2->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| pf_rshoe.c|| 1772|| lpYYRes2->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_rshoe.c|| 1773|| lpYYRes2->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| pf_rshoe.c|| 1776|| lpYYRes3 = PrimFnDydCircleSlope_EM_YY (&lpYYRes2->tkToken,
|-
| pf_rshoe.c|| 1996|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRht;
|-
| pf_rshoe.c|| 2396|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRes, aplTypeRht, lptkFunc);
|-
| pf_rshoe.c|| 3014|| lpYYRes->tkToken.tkFlags.ImmType = immTypeSubRht;
|-
| pf_rshoe.c|| 3016|| lpYYRes->tkToken.tkData.tkLongest = aplLongestSubRht;
|-
| pf_rshoe.c|| 3034|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRht, aplTypeRht, lptkFunc);
|-
| pf_rtack.c|| 188|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbArg);
|-
| pf_rtack.c|| 194|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplType);
|-
| pf_squad.c|| 228|| lpMemRht = &lpYYRht->tkToken.tkData.tkInteger;
|-
| pf_squad.c|| 232|| hGlbRht = lpYYRht->tkToken.tkData.tkGlbData;
|-
| pf_squad.c|| 278|| *lpMemRes++ = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_uarrow.c|| 232|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (lpSymGlb, aplTypeRht, lptkFunc);
|-
| pf_utackjot.c|| 379|| lpYYRes->tkToken.tkFlags.NoDisplay |= (exitType EQ EXITTYPE_NODISPLAY);
|-
|} 

==Variable Types==

==Variables==

Frequently Used TypeDef Structures and Variables

2015-08-18T13:41:21Z

Robert Wallick: /* tkToken Commonly Used Structures */ analogy added

'''<big>NARS C Source Code Frequently Used TypeDef Structures and Variables:</big>'''

NARS has multiple frequently used TypeDefs, Structures, Type-Variables and Variables. Familiarity with these structures, including variables employed, is essential toward gaining increased understanding of how NARS C source code works, including insight into C program flow.

==TypeDefs==

===LPPL_YYSTYPE===

Full definition for typedef '''LPPL_YYTYPE''': found in file <'''pl_parse.h'''>. '''Partial''', extracted, compiler-directives-excluded/simplified definition:
<pre>
typedef struct tagPL_YYSTYPE // YYSTYPE for ParseLine
{
// N.B.: The first item in this struct *MUST* be the TOKEN
// because when we pass it as an argument to an LPPRIMFNS
// we might need it to be an LPPL_YYSTYPE (for a function strand)
// or an LPTOKEN (single function).
TOKEN tkToken; // 00: Token info (28 bytes)
UINT TknCount; // 1C: Count of adjacent tokens including this one
UINT YYInuse:1, // 20: 00000001: This entry is in use
YYIndirect:1, // 00000002: Arg is indirect
YYPerm:1, // 00000004: Item is permanent, don't free
YYStranding:1, // 00000008: Item is in the process of being stranded
:28; // FFFFFFF0: Available bits

struct tagPL_YYSTYPE
*lpYYFcnBase, // 24: Ptr to base function/operator
// Not valid outside the enclosing
// invocation of ParseLine
*lpYYStrandBase, // 28: Ptr to this token's strand base
*lpplYYArgCurry, // 2C: Ptr to left argument curry
*lpplYYIdxCurry, // 30: Ptr to axis curry
*lpplYYFcnCurry, // 34: ... function ...
*lpplYYOpRCurry; // 38: ... right operand ...
LPTOKEN lptkLftBrace, // 3C: Ptr to the AFO's left brace token
lptkRhtBrace; // 40: ... right ...
// 44: Length
} PL_YYSTYPE, *LPPL_YYSTYPE; // Data type of yacc stack; most frequently used is LPPL_YYSTYPE, long pointer to the above structure.
</pre>
* In the above code snippet note the '''nested struct''' formation. '''Inner struct tagPL_YYSTYPE resides within code confines''' of outer struct ''same-name'' tagPL_YYSTYPE. This formation parallels nicely with APL's workspace '''[[System_Command_SI|State Indicator )SI]]''' intrinsic Interpreter design feature which is used for APL-programmer debugging purposes. 
* For ⎕ System Function and Primary APL Function calls, the above typedef is the normal or the expected - '''returned value-group''', the returned value-set structure. Further, since NARS by its very nature handles nested arrays, the above structure similarly manages nested data arrays well. In case it is not obvious to anyone reading this web page or examining NARS source code - NARS represents a highly evolved, data-fluid, APL Interpreter with a full, rich symbol-set programming environment.
 
'''LPPL_YYSTYPE''' is customarily used as a '''variable-type''', as per the following: 
LPPL_YYSTYPE lpYYRes = NULL, // initialize, lpYYRes will be Ptr to result of a ⎕ quad System Function or Primary APL Function call
and '''macro YYAlloc''' (def. file <macros.h>) call instantiated, then with specific values inserted: 
lpYYRes = YYAlloc (); // Allocate free memory, fill LPPL_YYSTYPE memory structure with default setup/values, e.g. <qf_ec.c>
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

<hr width=25%>

===TOKEN===

Full definition for typedef '''TOKEN''': found in file <'''tokens.h'''>:
<pre>
typedef struct tagTOKEN
{
TKFLAGS tkFlags; // 00: The flags part (numbers shown at left are beginning byte # in structure)
SO_ENUM tkSynObj; // 04: The Syntax Object for this token
TOKEN_DATA tkData; // 08: The data part (16 bytes=18 Hex - 08 Hex = 10 Hex)
int tkCharIndex; // 18: Index into the input line of this token
// 1C: Length (1C Hex = 16+12 decimal = byte #28)
} TOKEN, *LPTOKEN;
</pre>

Primary sample usage: Above typedef TOKEN is the first type-var found in '''[[Frequently_Used_TypeDef_Structures_and_Variables#LPPL_YYSTYPE|typedef LPPL_YYSTYPE]]''' above, ref. TOKEN use just below:
<pre>
TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)
</pre>
Linked or indirect referencing through typed variable-name example: (to fill in a result token):
<pre>
// Sample token type choices: TKT_VARNAMED, TKT_VARIMMED, TKT_LSTIMMED, TKT_LSTARRAY, TKT_LSTMULT, TKT_VARARRAY(primary), TKT_STRAND and TKT_STRING.
// Full list of token types found in file <tokens.h>. TKT_VARARRAY used just below:
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
</pre>

==tkToken Commonly Used Structures==
C Source Code Sample Short List of '''tkToken Structure Groupings''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References and '''Frequencies''' (per C:\NARS2000\trunk qf_*.c/pf_*.c files) as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure/Value
! Overall Found Freq
! Overall Found % Tot
|-
| qf_ec.c|| 237|| tkToken|| 820|| 100.0%
|-
| qf_a.c|| 67|| tkToken.tkCharIndex|| 134|| 16.3%
|-
| pf_cstile.c|| 182|| tkToken.tkData.tkBoolean|| 13|| 1.6%
|-
| qf_tc.c|| 162|| tkToken.tkData.tkChar|| 5|| 0.6%
|-
| qf_dl.c|| 179|| tkToken.tkData.tkFloat|| 9|| 1.1%
|-
| qf_a.c|| 66|| tkToken.tkData.tkGlbData|| 135|| 16.5%
|-
| qf_dr.c|| 98|| tkToken.tkData.tkInteger|| 25|| 3.0%
|-
| qf_dr.c|| 309|| tkToken.tkData.tkLongest|| 18|| 2.2%
|-
| qf_ec.c|| 275|| tkToken.tkData.tkSym|| 3|| 0.4%
|-
| qf_ec.c|| 268|| tkToken.tkData.tkVoid|| 1|| 0.1%
|-
| qf_a.c|| 64|| tkToken.tkFlags.ImmType|| 145|| 17.7%
|-
| qf_a.c|| 65|| tkToken.tkFlags.NoDisplay|| 140|| 17.1%
|-
| qf_a.c|| 63|| tkToken.tkFlags.TknType|| 148|| 18.0%
|-
| pf_index.c|| 774|| tkToken.tkSynObj|| 1|| 0.1%
|-
|}
One analogy to NARS tkToken structure groupings can be found in Particle Physics where Quarks, Leptons, Gluons and Gravitons comprise a particle class known as '''[http://physics.about.com/od/atomsparticles/a/particles.htm Fermions]'''. NARS tkToken structure groupings, just as is true for Fermions, allows for a wide range of C coded functionality groupings. tkToken is a convenient way of grouping several pieces of related information together with flexibility for handling '''potentially broadly different''' datatypes, shapes and even functionality. A nested matrix of mixed elements can be handled, as well accommodation for workspace state indicator stack value-sets - all within tkToken structures.

==tkToken Structures More Detailed Sample Uses Table==
C Source Code '''Sample Uses''' Unique (duplicates removed) List of '''tkToken Structure = Values''' Found in files <qf_*.c and pf_*.c> Functions with FileName plus Line # Cross References (per C:\NARS2000\trunk qf_*.c/pf_*.c files), sorted by source filename, as of Mon 8/17/15: 
{| class="wikitable"
! FileName
! Line #
! Structure = Value
|-
| qf_a.c|| 63|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| qf_a.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadA);
|-
| qf_a.c|| 67|| lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| qf_at.c|| 406|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
|-
| qf_av.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadAV);
|-
| qf_d.c|| 66|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbQuadD);
|-
| qf_dl.c|| 176|| lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
|-
| qf_dl.c|| 177|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
|-
| qf_dl.c|| 179|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRht;
|-
| qf_dr.c|| 96|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_INT;
|-
| qf_dr.c|| 110|| lpYYRes->tkToken.tkData.tkInteger = DR_BOOL;
|-
| qf_dr.c|| 115|| lpYYRes->tkToken.tkData.tkInteger = DR_INT64;
|-
| qf_dr.c|| 120|| lpYYRes->tkToken.tkData.tkInteger = DR_FLOAT;
|-
| qf_dr.c|| 125|| lpYYRes->tkToken.tkData.tkInteger = DR_CHAR16;
|-
| qf_dr.c|| 130|| lpYYRes->tkToken.tkData.tkInteger = DR_APA;
|-
| qf_dr.c|| 135|| lpYYRes->tkToken.tkData.tkInteger = DR_HETERO;
|-
| qf_dr.c|| 140|| lpYYRes->tkToken.tkData.tkInteger = DR_NESTED;
|-
| qf_dr.c|| 145|| lpYYRes->tkToken.tkData.tkInteger = DR_RAT;
|-
| qf_dr.c|| 150|| lpYYRes->tkToken.tkData.tkInteger = DR_VFP;
|-
| qf_dr.c|| 307|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRes;
|-
| qf_dr.c|| 309|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRes;
|-
| qf_em.c|| 70|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRes;
|-
| qf_fx.c|| 353|| lpYYRes->tkToken.tkData.tkInteger = GetQuadIO () + SF_Fcns.uErrLine;
|-
| qf_mf.c|| 493|| lpYYRes->tkToken.tkData.tkInteger = aplIntegerRes;
|-
| qf_mf.c|| 506|| lpYYRes->tkToken.tkData.tkFloat = aplFloatRes;
|-
| qf_mf.c|| 806|| lpYYRes->tkToken.tkFlags.NoDisplay = TRUE;
|-
| qf_nfns.c|| 275|| lpYYRes->tkToken.tkData.tkInteger = aplFileOff;
|-
| qf_nfns.c|| 592|| lpYYRes->tkToken.tkFlags.NoDisplay = (aplLongestRht NE 0);
|-
| qf_nfns.c|| 593|| lpYYRes->tkToken.tkData.tkInteger = TieNum;
|-
| qf_nfns.c|| 1083|| lpYYRes->tkToken.tkData.tkGlbData = hGlbRht;
|-
| qf_nfns.c|| 1091|| lpYYRes->tkToken.tkData.tkInteger = aplLongestRht;
|-
| qf_nfns.c|| 3298|| lpYYRes->tkToken.tkData.tkInteger = aplFileSize;
|-
| qf_t.c|| 75|| lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
|-
| qf_tc.c|| 160|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_CHAR;
|-
| qf_tc.c|| 162|| lpYYRes->tkToken.tkData.tkChar = wc;
|-
| qf_ucs.c|| 206|| lpYYRes->tkToken.tkData.tkLongest = aplLongestRht;
|-
| qf_wa.c|| 70|| lpYYRes->tkToken.tkData.tkInteger = msex.ullAvailPhys + msex.ullAvailPageFile;
|-
| pf_bar.c|| 323|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (*lphGlbRes);
|-
| pf_cslope.c|| 255|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_cslope.c|| 259|| lpYYRes2 = PrimFnDydCircleSlope_EM_YY (&lpYYRes->tkToken,
|-
| pf_cslope.c|| 416|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkData.tkSym->stFlags.ImmType;
|-
| pf_cslope.c|| 418|| lpYYRes->tkToken.tkData.tkLongest = lptkRhtArg->tkData.tkSym->stData.stLongest;
|-
| pf_cslope.c|| 425|| lpYYRes->tkToken = *lptkRhtArg;
|-
| pf_cstile.c|| 178|| lpYYRes->tkToken = tkZero;
|-
| pf_cstile.c|| 252|| lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_BOOL;
|-
| pf_cstile.c|| 374|| lpYYRes->tkToken = *CopyToken_EM (lptkRhtArg, FALSE);
|-
| pf_darrow.c|| 372|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeRht);
|-
| pf_domino.c|| 220|| lpYYRes->tkToken.tkData.tkBoolean = 1;
|-
| pf_domino.c|| 481|| lpYYRes->tkToken.tkFlags.TknType =
|-
| pf_domino.c|| 526|| lpYYRes->tkToken.tkData.tkGlbData =
|-
| pf_dshoe.c|| 161|| lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbZilde);
|-
| pf_dshoe.c|| 480|| hGlbGup = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_dtack.c|| 219|| lpYYRes->tkToken.tkData.tkBoolean = FALSE;
|-
| pf_dtack.c|| 224|| lpYYRes->tkToken.tkData.tkInteger = 0;
|-
| pf_dtack.c|| 229|| lpYYRes->tkToken.tkData.tkFloat = 0;
|-
| pf_dtack.c|| 234|| lpYYRes->tkToken.tkData.tkChar = L' ';
|-
| pf_dtack.c|| 248|| lpYYRes->tkToken.tkFlags.ImmType = lptkRhtArg->tkFlags.ImmType;
|-
| pf_dtack.c|| 309|| lpYYRes->tkToken.tkData.tkGlbData = hSymGlbRes;
|-
| pf_dtackjot.c|| 375|| lpYYRes->tkToken.tkData.tkChar = aplCharRht;
|-
| pf_epsilon.c|| 2398|| hGlbGupLft = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 2429|| hGlbGupRht = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_epsilon.c|| 3731|| bCmp = lpYYTmp->tkToken.tkData.tkBoolean;
|-
| pf_epsund.c|| 279|| lpYYRes->tkToken.tkData.tkBoolean =
|-
| pf_epsund.c|| 288|| lpMemRes = &lpYYRes->tkToken.tkData.tkBoolean;
|-
| pf_equalund.c|| 532|| lpYYRes->tkToken.tkData.tkBoolean = (APLBOOL) ((BIT0 & aplIntegerRes) NE bNotEqual);
|-
| pf_index.c|| 117|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplTypeNam);
|-
| pf_index.c|| 119|| lpYYRes->tkToken.tkData.tkLongest = aplLongestNam;
|-
| pf_index.c|| 120|| lpYYRes->tkToken.tkCharIndex = lptkLstArg->tkCharIndex;
|-
| pf_index.c|| 127|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbNam);
|-
| pf_index.c|| 591|| *((LPAPLBOOL) lpMemRes) |= lpYYItm->tkToken.tkData.tkBoolean << uBitIndex;
|-
| pf_index.c|| 604|| *((LPAPLINT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkInteger;
|-
| pf_index.c|| 610|| *((LPAPLFLOAT) lpMemRes)++ = lpYYItm->tkToken.tkData.tkFloat;
|-
| pf_index.c|| 616|| *((LPAPLCHAR) lpMemRes)++ = lpYYItm->tkToken.tkData.tkChar;
|-
| pf_index.c|| 639|| lpSymTmp = MyGlobalLock (lpYYItm->tkToken.tkData.tkGlbData);
|-
| pf_index.c|| 645|| MyGlobalUnlock (lpYYItm->tkToken.tkData.tkGlbData); lpSymTmp = NULL;
|-
| pf_index.c|| 648|| DbgGlobalFree (lpYYItm->tkToken.tkData.tkGlbData); lpYYItm->tkToken.tkData.tkGlbData = NULL;
|-
| pf_index.c|| 774|| lpYYRes->tkToken.tkSynObj = soA;
|-
| pf_index.c|| 878|| lpYYRes->tkToken.tkFlags.ImmType = immTypeNam;
|-
| pf_index.c|| 2016|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTIMMED;
|-
| pf_index.c|| 2019|| lpYYRes->tkToken.tkFlags.TknType = TKT_LSTARRAY;
|-
| pf_index.c|| 2514|| lpMemRes[0] = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2546|| hGlbSubRht = lpYYSub->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 2913|| lpYYRes2 = PrimFnDydRho_EM_YY (&lpYYRes1->tkToken,
|-
| pf_index.c|| 2924|| hGlbRes = lpYYRes2->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 3593|| hGlbSubLst2 = lpYYItm->tkToken.tkData.tkGlbData;
|-
| pf_index.c|| 4536|| lpYYRes2 = ExecFuncStr_EM_YY (&lpYYRes1->tkToken,
|-
| pf_lshoe.c|| 212|| lpYYRes->tkToken.tkFlags.ImmType = ImmType;
|-
| pf_lshoe.c|| 214|| lpYYRes->tkToken.tkData.tkLongest = aplLongest;
|-
| pf_lshoe.c|| 316|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbRht);
|-
| pf_rshoe.c|| 263|| lpYYRes->tkToken.tkFlags.ImmType = immType;
|-
| pf_rshoe.c|| 1769|| lpYYRes2->tkToken.tkFlags.TknType = TKT_VARARRAY;
|-
| pf_rshoe.c|| 1772|| lpYYRes2->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbLft);
|-
| pf_rshoe.c|| 1773|| lpYYRes2->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
|-
| pf_rshoe.c|| 1776|| lpYYRes3 = PrimFnDydCircleSlope_EM_YY (&lpYYRes2->tkToken,
|-
| pf_rshoe.c|| 1996|| lpYYRes->tkToken.tkFlags.ImmType = immTypeRht;
|-
| pf_rshoe.c|| 2396|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRes, aplTypeRht, lptkFunc);
|-
| pf_rshoe.c|| 3014|| lpYYRes->tkToken.tkFlags.ImmType = immTypeSubRht;
|-
| pf_rshoe.c|| 3016|| lpYYRes->tkToken.tkData.tkLongest = aplLongestSubRht;
|-
| pf_rshoe.c|| 3034|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (hGlbRht, aplTypeRht, lptkFunc);
|-
| pf_rtack.c|| 188|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbDirAsGlb (hGlbArg);
|-
| pf_rtack.c|| 194|| lpYYRes->tkToken.tkFlags.ImmType = TranslateArrayTypeToImmType (aplType);
|-
| pf_squad.c|| 228|| lpMemRht = &lpYYRht->tkToken.tkData.tkInteger;
|-
| pf_squad.c|| 232|| hGlbRht = lpYYRht->tkToken.tkData.tkGlbData;
|-
| pf_squad.c|| 278|| *lpMemRes++ = lpYYRes->tkToken.tkData.tkGlbData;
|-
| pf_uarrow.c|| 232|| lpYYRes->tkToken.tkData.tkGlbData = CopySymGlbNumDir_PTB (lpSymGlb, aplTypeRht, lptkFunc);
|-
| pf_utackjot.c|| 379|| lpYYRes->tkToken.tkFlags.NoDisplay |= (exitType EQ EXITTYPE_NODISPLAY);
|-
|} 

==Variable Types==

==Variables==

Quad EC C Source Code Analysis

2015-08-18T00:35:33Z

Robert Wallick: /* Comparison Prelim Setups - Different Returned Outputs */ wording

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Prelim Setups - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structural setup for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structural setup for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc (); // Setup line # 1 for lpYYRes
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY; // Setup line # 2 for lpYYRes
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes); // Setup line # 3 for lpYYRes
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex; // Setup line # 4 for lpYYRes
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data. From a purely structural perspective, excluding 1)pre-setup work in ⎕EC, 2)comment lines and 3)post-op processing C code, only 4 lines of C code were needed (above) to '''setup''' (not calculate) return result variable lpYYRes for ⎕EC.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structural setup for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').

Quad EC C Source Code Analysis

2015-08-18T00:30:53Z

Robert Wallick: /* Comparison Prelim Setups - Different Returned Outputs */ wording

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Prelim Setups - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structural setup for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structural setup for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc (); // Setup line # 1 for lpYYRes
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY; // Setup line # 2 for lpYYRes
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes); // Setup line # 3 for lpYYRes
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex; // Setup line # 4 for lpYYRes
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data. Excluding pre-setup work in ⎕EC, comment lines and post-op processing C code, only 4 lines of C code were needed (above) to setup return result variable lpYYRes for ⎕EC.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structural setup for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').

Quad EC C Source Code Analysis

2015-08-18T00:22:52Z

Robert Wallick: /* Comparison Prelim Setups - Different Returned Outputs */ added cross ref link, wording

'''<h1>⎕EC - C Source Code Analysis:</h1>'''

File <qf_ec.c> (supporting APL System Function [[System_Function_EC|System Function ⎕EC - Execute Controlled]]) located in NARS trunk folder is a model example for '''returning a nested vector to APL''' from a System Function call. Remember per your technical knowledge of APL: '''[[System_Function_EC|⎕EC]]''' returns a 3-element nested vector to APL. 

==Executive Summary - Conceptual C Programmers Preliminary Overview/Preview==

Variable '''lpYYRes''' upon completion of ⎕EC contains the entire '''3-element nested vector result''' of the call to <'''qf_ec.c'''>, specifically, from monadic function '''SysFnMonEC_EM_YY'''. '''lpYYRes''' also contains a pointer to an object <'''hGlbRes'''> that is created by other code in the same file.

 That global memory handle <'''hGlbRes'''> points (via '''lpMemRes''' = MyGlobalLock (hGlbRes)) to a VARARRAY_HEADER followed by the actual data (a three-element vector). The header contains various fields such as Array Type (ARRAY_NESTED), the NELM (3), the Rank (1), the dimension (3), followed by the data. As it is a nested array that gets returned, the 3-elements of the data are all pointers to a '''SYMENTRY''' (for immediate values -- BOOL, INT, FLT, and CHAR) or a global memory handle for all other items, e.g. Global Numeric, APA, HETERO (mixed array-datatype e.g. integer, char/unicode string, float double, etc.), any non-immediate array, etc.

 In a sense, the internal structure of arrays in NARS C code are nested just as APL arrays themselves are nested. Nesting is ubiquitous in NARS/APL2, etc.. Think about C coding source layouts and program flow from the standpoint of "How would you design the internal structures for an APL interpreter?" The C source code would, wherever possible, parallel the APL code which APL users view and understand.

 ⎕EC is somewhat more complex than other APL system functions in that ⎕EC executes its right argument under '''controlled circumstances''' - this also holds true for the C code itself - complexity in the returned data structure, i.e. ⎕EC mirrors APL variable structuring.

 Subordinate execution of ⎕EC's right argument returns an <LPPL_YYSTYPE> variable-type pointer(ptr) just as it's umbrella overarching function ⎕EC does. Many APL prime functions such as rho, take, iota, etc. as coded in C - also return nested arguments while many APL System <apll>{quad}</apll> Functions merely return scalars.

 Variable name <'''lpYYRes2'''> in file <'''qf_ec.c'''>'s C source code indicates it is a secondary result (re the '''execution''' of ⎕EC's right argument).

 Independent of how actual execution of the APL user's argument proceeded, after executing that right arg, the Exit Type is converted into an integer Return Code (as that's the form of the first output item - the first element in ⎕EC's output vector, in ⎕EC's result vector). That first item is a simple numeric scalar, but since the result of ⎕EC is a three-element nested vector, <qf_ec.c>/'''SysFnMonEC_EM_YY''' must convert the Return Code into a '''LPSYMENTRY''' via <'''MakeSymEntry_EM'''>.

 In particular - (file <'''qf_ec.c'''> C source code extract just below):
// Save the return code in the FIRST ELEMENT of ⎕EC - C's index origin is zero hence ref. to lpMemRes[0]
lpMemRes[0] = MakeSymEntry_EM (IMMTYPE_INT, // Immediate type
&aplLongestRC, // Ptr to immediate value
lptkFunc); // Ptr to function token

Technically, ⎕EC's second output element is the value of ⎕ET, usually a 2-element vector of zeroes, at present.

 What happens next depends upon whether or not the APL user's right argument execution succeeded:

 If execution succeeded: '''[[System_Function_EC|⎕EC]]''' returns the '''value or string value''' of the executed result as the third element in its output vector.

 If execution failed: '''⎕EC''' returns the '''error message''' associated with that failure, a unicode string - as '''[[System_Function_EC|⎕EC]]''''s third output element.

==Comparison Prelim Setups - Different Returned Outputs==

1. '''[[System_Function_T|⎕T]]''' (file <'''qf_t.c'''> code extract) '''initial''' structural setup for returned solitary '''scalar number''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARIMMED;
lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_FLOAT;
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkFloat = aplFloatSec;
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

 2. '''[[System_Function_EC|⎕EC]]''' (file <'''qf_ec.c'''> code extract) '''initial''' structural setup for returned 3-element '''nested vector''':
<pre>
// Allocate a new YYRes
lpYYRes = YYAlloc ();
// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;
</pre>

Differences: Note '''TKT_VARIMMED for ⎕T''' vs. '''TKT_VARARRAY for ⎕EC'''. Also note ⎕EC's use of hGlbRes for nested returned data, re: lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
Nesting occurs in ⎕EC output through the use of '''TKT_VARARRAY''' as token flags token type and through use of nested memory pointer '''MakePtrTypeGlb (hGlbRes)''' in var lpYYRes via the token's global data.
See also '''[[Frequently_Used_TypeDef_Structures_and_Variables#tkToken Structures More Detailed Sample Uses Table|tkToken Sample Uses Table]]'''.

 3. '''[[System_Function_TS|⎕TS]]''' (file <'''qf_ts.c'''> code extract) '''more''' substantive structural setup for a returned plain-vanilla / homogeneous 7-element '''unmixed vector''':
<pre>
#define lpMemData ((LPAPLINT) lpMemRes) // The following seven vector elements returned are all integers
lpMemData[0] = SystemTime.wYear;
lpMemData[1] = SystemTime.wMonth;
lpMemData[2] = SystemTime.wDay;
lpMemData[3] = SystemTime.wHour;
lpMemData[4] = SystemTime.wMinute;
lpMemData[5] = SystemTime.wSecond;
lpMemData[6] = SystemTime.wMilliseconds;
#undef lpMemData

// Memory ptr no longer needed, allow unlocking/freeing hGlbRes(technically freed upon returning from ⎕TS), reset lpMemRes pointer to null
MyGlobalUnlock (hGlbRes); lpMemRes = NULL;

// Allocate a new YYRes
lpYYRes = YYAlloc ();

// Fill in the result token
lpYYRes->tkToken.tkFlags.TknType = TKT_VARARRAY;
// lpYYRes->tkToken.tkFlags.ImmType = IMMTYPE_ERROR; // Already zero from YYAlloc
// lpYYRes->tkToken.tkFlags.NoDisplay = FALSE; // Already zero from YYAlloc
lpYYRes->tkToken.tkData.tkGlbData = MakePtrTypeGlb (hGlbRes);
lpYYRes->tkToken.tkCharIndex = lptkFunc->tkCharIndex;

return lpYYRes;
</pre>
The above return information C coding for '''[[System_Function_TS|⎕TS]]''' is included because setup for ⎕TS's integers output vector is relatively straightforward, i.e. less complex than a nested vector('''[[System_Function_EC|⎕EC]]''') but not much more complex than a scalar ('''[[System_Function_T|⎕T]]''').