Variable Declaration Primitives

__lexicalblock( ....  block  ... );

Lexical scope.

Description

The __lexicalblock statement is used to implement lexical block scoping within function/macro bodies.

By default local variables are all function scoped unless lexical block scoping is enabled via the #pragma lexical_scoping.

#pragma scope(push, lexical)
void function() {
    int i;              // first variable, function scope
    {
        int i;          // second variable, lexically block scope
    }
}
#pragma scope(pop)

Returns

nothing

See Also

Scope

list arg_list( [int eval = FALSE],   [int start = 0], [int end = -1] )

Argument list.

Description

The arg_list() primitive retrieves a list of the values representing the arguments which were passed to the current macro; allows for arbitrary argument processing.

Parameters

Returns

The arg_list() primitive returns the arguments passed to the current macro as a list.

Examples

void
func()
{
    message("%s", arg_list());
}

In the example above, the list of arguments will be shown.  But in a call like

int val = 99;
func(val);

In this case, the message will show “val” and not 99.  To get the values replaced, use

message("%s", arg_list(1));
Return value

List of arguments passed to calling macro.

Portability

The start and end parameters are GriefEdit extensions.

See Also

put_parm, get_parm

array sym1, sym2 ...;

Declare a array symbol.

Description

The array statement is reserved for future use.

An array is a variable array of fixed sized arbitrary values.  Unlike a list, a array supports constant-time element access and updates.

Returns

nothing

Portability

n/a

See Also

Types, int, string, list, float, double

bool sym1, sym2 ...;

Declare a boolean symbol.

Description

The bool statement as an alias for int.

Returns

nothing

Portability

n/a

See Also

Types, int, string, list, float, double, array

const <type> sym1, sym2 ...;

Define a variable as being constant.

Description

The const qualifier explicitly declares a locally scoped data object as something that cannot be changed.  Its an immutable variable can only be set during initialization.

You cannot use const data objects in expressions requiring a modifiable lvalue.  If you try to give it a new value, it will return you an error.

For example, a const data object cannot appear on the lefthand side of an assignment statement.

Returns

nothing

Portability

An experimental GRIEF extension; functionality may change.

See Also

Types, global, extern, static, register

declare sym1, sym2 ...;

Declare a polymorphic symbol.

Description

The declare statement declares a polymorphic data type.

Returns

nothing

Portability

n/a

See Also

Types, int, string, list, float, double, array

double sym1, sym2 ...;

Declare a double float symbol.

Description

The double statement is an alias for the float type.

Returns

nothing

Portability

n/a

See Also

Types, int, string, list, float, array

extern <type> sym1, sym2, ..;

Declare an external variable.

Description

The extern storage class specifier extends the visibility of variables and functions, allowing objects and functions to be accessed across several source files.

An extern variable, function definition, or declaration makes the described variable or function usable by the succeeding part of the current source file.

This declaration does not replace the definition.  The declaration is used to describe the variable that is externally defined.  Essentially the extern keyword creates a place holder in the symbol table to avoid undefined symbol reference errors.

Variables

A variable must be defined once in one of the modules of the program; this sets aside storage.  If there is no definition, a runtime error shall result since the storage of the variable would not have been created,

There may be none or more variable declarations.  These can be declared extern in many modules, including the module where it was defined, and even many times in the same module.  All the declarations must match, which is normally by the use of a common header file shared between all source files.

Any extern declaration of the same identifier found within a block refers to that same object.  If no other declaration for the identifier exists at file scope, the identifier has external linkage.

Unlike C external linkage of variables occurs during macro execution, see Scope Rules.  If a declaration for an identifier already exists in one of the visible namespaces they reference to the same image.

When searching for a variable definition, GRIEF searches the symbol tables in the following order:

• static variable definition in the current function.
• buffer local variable.
• local variables of a current block.
• nested stack frames to the outermost function call dynamic scope.
• global variable.

Within the following example the variable x reference by the function foo is resolved against the global image of x, whereas b shall be resolved against the image within the caller bar.

static int x = 0;

void
foo()
{
    extern int b, x;

    b = 0;              // resolved by 'i' within bar()
    x = 0;              // global 'x'
}

void
bar()
{
    int b;
    foo();
}

Functions

The extern statement applied to a function prototype does nothing; as extern is the default linkage.  A function prototype is always a declaration and never a definition.

All functions across loaded macros which refer to the same external identifier refer to the same object, so care must be taken that the type and extent specified in the definition are compatible with those specified by each function which references the data.  This is generally achieved by the use of a common header file shared between all source files (e.g.  “grief.h”).

It is an error to include a declaration for the same function with the storage class specifier static before the declaration with no storage class specifier because of the incompatible declarations.  Including the extern storage class specifier on the original declaration is valid and the function has internal linkage.

Builtin macros do not have explicit prototypes as the Macro compiler has internal knowledge of all visible primitives.

Returns

nothing

Portability

n/a

See Also

int, string, list, float, declare, static, global

float sym1, sym2 ...;

Declare a float symbol.

Description

The float statement declares a simple type that stores 64-bit floating-point values that stores values in the approximate range;

1.7E308 to 1.7E+308

Returns

nothing

Portability

n/a

See Also

Types, int, string, list, double, array

int get_parm(   [int argument], declare  & symbol,     [string prompt],   [int length = MAXPROMPT],     [declare default],   [int one = FALSE] )

Retrieve the value of a macro parameter.

Description

The get_parm() primitive shall retrieve the value of the specified macro parameter argument optionally prompting the user if the referenced parameter was not given during the macro execution.  When prompted the question within prompt is presented using the optional default which the user can then edit.

This function can also be used to always prompt the user for a reply by invoking with the argument parameter being omitted and specified as NULL.

Generally the user must complete the input using an enter unless the prompt is in single character mode, whereby the first key is taken as the input.  The mode is either implied by the length parameter or an explicit one parameter, see below.

Navigation/actions Keys

The following keys bindings are active during parameter prompts.

(*) Emacs style key mappings.

Parameters

Returns

The get_parm() primitive returns greater than zero on success, otherwise zero if either the user aborted or an error was encountered.

Portability

Unlike BRIEF the default parameter is always the fifth, whereas with BRIEF the default value is either the fourth or fifth dependent on whether an integer length is stated since the default was only permitted to be a string.

The one option is a GriefEdit extension.

See Also

inq_prompt, _prompt_begin, _prompt_end

int getopt(     string  & value,       [[string shortopts], list longopts, string|list args, [string caller]] )

Get options.

Description

The getopt() primitive is a command-line parser similar to the system library function of the same name.  The getopt() function provides a superset of the functionality of getopt, accepting options in two forms, words (long-options) and characters (short-options).

The getopt() primitive is designed to be executed within a loop, with the first invocation suppling the available options shortopts and/or longopts, the arguments to be parsed args and the application/macro name caller.  Subsequent calls within the same execution loop only then request the next available option without additional arguments; the general form of getopt usage is as follows.

string value;
int ch;

if ((ch = getopt(value, shortopts, longopts, args)) > 0) {
    do {
    } while ((ch = getopt(value)) > 0);

Short Options

The short option string shortopts may contain the following elements

• individual characters
• characters followed by a colon to indicate an option argument is to follow.

For example, an option string “x” recognizes an option `-x’, and an option string “x:” recognizes an option and argument `-x argument’.

Long Options

The long option list longopts may contain a list of strings each defining a long option, of the form:

"[tag][,[#]value][[:=][scinfd]]"

Returns

Option value or index, starting at zero, otherwise one of the following negative error codes.  If the case of error codes -2 or less, value shall contain an error condition descripting the condition.

Plus the following argument syntax error conditions.

Portability

A GriefEdit extension.

Example

list longoptions = {
        "help,h",       // note duplicates result in first match
        "verbose,v",
        "verbose2,#2",
        "integer"       // extended format
        };
int ch;

if ((ch = getopt(value, "hv", longoptions, get_parm(1))) > 0) {
    do {
        switch (ch) {
        case 'h':       // -h (short) or --help (long) option
            break;

        case 'v':       // -v (short) or --verbose (long)
            break;

        case 2:         // --verbose2
            break;

        case 3:         // --integer=<value>
            i = atoi(value);
            break;

        case '?':       // error or unknown option
        case ':':       // or argument expected
            if (length(value)) {
                error("myfunction: %s", value);
            }
            break;

        default:
            break;
        }
    } while ((ch = getopt(value)) > 0);
}

See Also

arg_list, split_arguments

int getsubopt( string  value,   [list options],     [string|list args],   [string delim],   [string quotes] )

Parse suboption arguments from a string.

Description

The getsubopt() primitive shall parse suboption arguments in a flag argument.  Such options often result from the use of getopt.

Parameters

Return

Option index, otherwise one of the following negative error codes.  If the case of error codes -2 or less, value shall contain an error condition descripting the condition,

Portability

A GriefEdit extension.

Example

list suboptions = {
        "help,h",
        "verbose,v",
        "verbose2,#2",
        "integer:i"
        };

if ((ch = getsubopt(value, suboptions, get_parm(1))) >= 0) {
    do {
        switch (ch) {
        case 'h':
            break;
        case 'v':
            break;
        case 2:
            break;
        case 3:
            break;
        default:
            break;
        }
    } while ((ch = getsubopt(value)) >= 0);
}
if (ch < 0) {
    error(value);
}

global sym1, sym2, ..;

Declare a global variable.

Description

The global() primitive promotes a local declaration and making symbol global to all macros.

Global variables maintain their value across macro invocation and occupy permanent storage (See: Scope), whereas local variables are destroyed upon the macro they are contained within is terminated.

A variable must have been specified in a previous int, string, list, float or declare statement before it can be made into a global.

The global is a managed primitive and shall be automaticlly invoked on global variable declarations as follows:

// global declarations

int global_int1 = 1234;
static int global_int2;
const static int global_int3 = 125;

string global_string2 = "Hello world";
static string global_string2;

float global_float1 = "Hello world";
static float global_float2;

list global_list1;
static list global_list2;

void
mymacro()
{
}

Each macro object containing global declarations shall contain an internal _init macro, which is utilised by the Macro Compiler to initialise file level variables.

Returns

nothing

Portability

n/a

See Also

Types, extern, static, const, register

int inq_symbol( string  symbol )

Determine if the symbol exists.

Description

The inq_symbol() primitive determines whether the variable Iname exists at the current scope (See: Scope).  One main use of this primitive is to determine if a specific local buffer symbol has been defined.

Parameters

Example

An example usage

// required to resolve symbol at compile time
extern string my_buffer_var;

string
_set_buffer_var(string val)
{
    if (inq_symbol("my_buffer_var")) {
        my_buffer_var = mode;       // buffer-scope
    } else
    {   // otherwise we must create
        string my_buffer_var = mode;
        make_local_variable( my_buffer_var );
    }
}

string
_get_buffer_var()
{
    if (inq_symbol("my_buffer_var")) {
        return my_buffer_var;
    }
    return "";
}

Returns

The inq_symbol() primitive returns a positive value indicates that the symbol exists, otherwise 0 if not found within the current scope.

Portability

A GriefEdit extension.

See Also

make_local_variable

int sym1, sym2 ...;

Declare an integer symbol.

Description

The int statement declares an integral type that stores values in the range;

-2,147,483,648 to 2,147,483,647

You can declare and initialize a variable of the type int like this example:

'int' i = 1234;

Returns

nothing

Portability

n/a

See Also

Types, string, list, float, double, array

int is_array( declare  & symbol )

Determine whether an array type.

Description

The is_array() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of a array type.

Beware that the is_type collection of functions wont behave when given list elements, as these are not referenceable l-values.

Parameters

Returns

true if a array type, otherwise false.

Portability

n/a

See Also

array, typeof

int is_float( declare  & symbol )

Determine whether a float type.

Description

The is_float() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of a floating-point type.

Parameters

Returns

true if a float type, otherwise false.

Portability

A GriefEdit extension.

See Also

float, typeof

int is_integer( declare  & symbol )

Determine whether an integer type.

Description

The is_integer() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of an integer type.

Parameters

Returns

true if an integer type, otherwise false.

Portability

n/a

See Also

int, typeof

int is_list( declare  & symbol )

Determine whether a list type.

Description

The is_list() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of a list type.

Parameters

Returns

true if a list type, otherwise false.

Portability

n/a

See Also

list, typeof

int is_null( declare  & symbol )

Determine whether a NULL type.

Description

The is_null() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of a NULL type.

Beware that the is_type collection of functions wont behave when given list elements, as these are not referenceable l-values.

Parameters

Returns

true if a NULL type, otherwise false.

Portability

n/a

See Also

list, typeof

int is_string( declare  & symbol )

Determine whether a string type.

Description

The is_string() primitive determines the type of a polymorphic expression and tests whether the specified symbol has of a string type.

Beware that the is_type collection of functions wont behave when given list elements, as these are not referenceable l-values.

Parameters

Returns

true if a string type, otherwise false.

Portability

n/a

See Also

string, typeof

int is_type( declare  & symbol, int|string  type )

Determine whether an explicit type.

Description

The is_type() primitive determines the type of a polymorphic expression and tests whether the specified symbol is of the type type.

Beware that the is_type collection of functions wont behave when given list elements, as these are not referenceable l-values.

Parameters

Returns

true if the stated type, otherwise false.

Portability

n/a

See Also

array, typeof

void make_local_variable( declare  & sym,   ... )

Make a buffer local variable.

Description

The make_local_variable() primitive associates the specified variable with the current buffer, becoming a buffer local variable..

Unlike scoped variables that are destroyed when the block within which they are defines terminates, buffer local variables maintain their value across macro invocation and occupy permanent storage until the buffer is deleted (See: <scope>).

Parameters

Returns

The make_local_variable() primitive returns nothing directly.

On error conditions the following diagnostics message shall be echoed on the command prompt, with xxx representing the symbol name.

missing symbol.

'xxx' not found at current scope.

cannot promote reference 'xxx'.

system variable 'xxx'.

Portability

n/a

See Also

inq_symbol, <types>

int put_parm( int  argidx,   declare  val,   [int optional = TRUE] )

Assign an argument value.

Description

The put_parm() primitive assigns a value val to a parameter positioned at argidx that was passed to the current macro.

Parameters

Returns

The put_parm() primitive returns 1 or greater on sucesss, otherwise 0 or less on error.

On the detection of error conditions the following diagnostics messages shall be echoed on the command prompt where x is the associated argument number;

put_parm: argument index 'x' out of range

put_parm: argument 'x' incorrect type

put_parm: argument 'x' type conversion error

Example

Assign the value 100 to the first parameter.

if (put_parm(0, 100)) {
    message("assigned");
}

Portability

n/a

See Also

get_parm

void ref_parm( int  argument,   string  local_symbol,   [int optional = FALSE] )

Create a reference parameter.

Description

The ref_parm() primitive creates a local reference to one of the current macro arguments, this primitive is the underlying implementation of macro reference arguments.

int mymacro(int &iparm, string &sparm)

is equivalent to the following

int mymacro()
{
    ref_parm(0, "iparm");
    ref_parm(1, "sparm");

Parameters

Returns

nothing

Portability

A GriefEdit extension

See Also

get_parm, put_parm

register idx1, sym1, idx2, sym2 ...;

Define a variable as being a register.

Description

The register qualifier explicitly declares a locally scoped data object as something that should be cached against the given index.

Registers are function scoped, being unique to each macro and are is visible only within the function.

Returns

nothing

Portability

An experimental GRIEF extension; functionality may change.

See Also

Types, global, extern, static, const

static var1, var2, ..;

Define a function or module scope.

Description

The static statement can be used to change the storage scope of a variable or function.  It is one of the major mechanism to enforce information hiding. static denotes that a function or data element is only known within the scope of the current module.  This provides a form of object-hiding and can avoid name clashes with other macros (See: Scope).

In addition, if you use the static statement with a variable that is local to a function, it allows the last value of the variable to be preserved between successive calls to that function, including during recursions.

Variables

A static variable is initialized only once.  Globals are performed within the body of the _init function, whereas a function static variable that has an initializer is initialized the first time it comes into existence.

Function::*

A static function is hidden from usage outside their own macro file (or module), this can present a problem with functionality which involves the usage of callbacks (e.g. assign_to_key).  In this case, the :: (scope resolution) operator is used to qualify hidden names so that they can still be used.

Example

void
main()
{
    assign_to_key("<Alt-A>", "my_alt_a");
}

static void
my_alt_a()
{
    //function body
}

The static declaration of my_alt_a() referenced by the assign_to_key() within main() wont be visible when the “Alt-A” key is processed as it shall be out of scope.  The usage of “::my_alt_a” forces the my_alt_a reference to become fully qualified at the time of the key assignment.  The following examples have the equivalent result:

Implicit current module, where if a null module name is specified (e.g.  “::function”) then the symbol shall be bound to current module.

assign_to_key("<Alt-A>", "::my_alt_a");

or, explicit current module, where a named namespaces is specified (e.g.  “module::function”):

module("my_module"");
assign_to_key("<Alt-A>", "my_module::my_alt_a");

or

module("my_module"");
assign_to_key("<Alt-A>", inq_module() + "::my_alt_a");

Returns

nothing

Portability

Module static declarations are a GRIEF extension.

See Also

Types, global, extern, const, register

string sym1, sym2 ...;

Declare a string symbol.

Description

The string statement declares a containers which may contain zero or more characters.

Returns

nothing

Portability

n/a

See Also

Types, int, list, float, double, array

string typeof( declare  & symbol )

Determine the symbol type.

Description

The typeof() primitive determines the type of a polymorphic expression returning a string describing the underlying type.

Returns

The typeof() primitive returns one of following strings dependent on the type of the specified symbol.

• ”integer” - An integer type.
• ”string” - A string type.
• ”float” - A floating-point type.
• ”list” - A List.
• ”array” - An array (reserved for future use).
• ”NULL” - NULL.
• ”undef” - Undefined or omitted.
• ”unknown-type” - Unknown type.

Portability

n/a

See Also

is_integer, is_string, is_float, is_list, is_null

$Id: $