Frequently Used TypeDef Structures and Variables

From NARS2000
Revision as of 22:46, 17 August 2015 by Robert Wallick (talk | contribs) (→‎tkToken Commonly Used Structures: added freq #'s, % Tots)
Jump to navigationJump to search

NARS C Source Code Frequently Used TypeDef Structures and Variables:

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:

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.
  • 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 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;

TOKEN

Full definition for typedef TOKEN: found in file <tokens.h>:

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;

Primary sample usage: Above typedef TOKEN is the first type-var found in typedef LPPL_YYSTYPE above, ref. TOKEN use just below:

    TOKEN tkToken; // (var name = tkToken, extensively used in System and APL Function calls)

Linked or indirect referencing through typed variable-name example: (to fill in a result token):

    // 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;

tkToken Commonly Used Structures

C Source Code Sample Short List of tkToken Structures/Values 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:

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%


Variable Types

Variables