Macro Language Primitives

__breaksw;

Switch break statement.

Description

The __breaksw statement is used to implement the break statement within switch statements.

Returns

nothing

See Also

Jump Statements, switch, while, do, for

void autoload( string  filename, string  function,   ... )

Register location of one or more macros.

Description

The autoload() primitive informs the macro loader about the existence of global macros.  The primitive registers the specified macro function against the macro object image filename, permitting an arbitrary number of macro names after the initial function; as such one or more function references may be associated.

Whenever the macro engine encounters an undefined macro reference, it searches the internal autoload list for a definition.  If available, the associated macro object shall be loaded as normal, with the loader searching the GRPATH definition for the underlying object image.

If during an autoload driven load the referenced function was not resolved the following diagnostic shall be generated.

load_macro: macro 'xxx' not resolved during autoload.

A function reference may only be associated with one macro object, with any secondary references ignored generating the following diagnostic message.

autoload: 'xxx' already defined.

Example

The macros modeline and mode are registers against the macro object modeline.

autoload("modeline", "modeline", "mode");

Parameters

Returns

nothing

Portability

n/a

See Also

require

int bless( [int ref], [string classname] )

Associate an object with a class/module.

Description

The bless primitive is reserved for future use.

This primitive informs the dictionary referenced by ref that it is now an object in the classname package.  If classname is omitted, the current module is used.  Because a bless is often the last thing in a constructor, it returns the reference for convenience.

The bless primitive enables Perl style objects.

Parameters

n/a

Returns

The bless statement returns the dictionary identifier.

Portability

A GriefEdit extension.

See Also

module

break;

break statement.

Description

The break statement is used to terminate switch, while, do and for loops.

Returns

nothing

See Also

Jump Statements, switch, while, do, for

int call_registered_macro( int  type )

Invoke registered macro callbacks.

Description

The call_registered_macro() primitive invokes all of functions which have register against the particular event type type.

See register_macro for the particulars on the different registered event types.

Parameters

Returns

The call_registered_macro returns nothing.

Portability

The set of available events differ between systems.

See Also

register_macro

'case' expr:

Switch case statement.

Description

The switch and case statements help control complex conditional and branching operations.

The body of a switch statement may have an arbitrary number of unique case labels.

If condition evaluates to the value that is equal to the value of one of case expressions, then control is transferred to the statement that is labelled with that expression.

If condition evaluates to the value that does not match any of the case labels, and the default label is present, control is transferred to the statement labelled as the default label.

Parameters

Returns

nothing

See Also

Selection Statements, switch

catch statement;

Catch statement.

Description

The catch statement is reserved for future use, shall implement try, catch and finally constructs.

Parameters

none

Returns

nothing

Portability

A GriefEdit extension.

See Also

try, finally, throw

continue;

Loop continuation.

Description

The continue statement forces transfer of control to the controlling expression of the smallest enclosing do, for, or <while >loop.

A continue statement may only appear within a loop body, and causes a jump to the inner-most loop-continuation statement (the end of the loop body).

In a while loop, the jump is effectively back to the while.

In a do loop, the jump is effectively down to the while

In a for statement, the jump is effectively to the closing brace of the compound-statement that is the subject of the for loop.  The third expression in the for statement, which is often an increment or decrement operation, is then executed before control is returned to the loop’s conditional expression.

Parameters

none

Returns

nothing.

Portability

n/a

See Also

Jump Statements, while, for, foreach

int create_dictionary( string  ~name,   int  ~tablesize, int  ~tablefactor )

Create a dictionary.

Description

The create_dictionary() primitive creates a new dictionary resource.

A dictionary is a collections of associations.  Dictionaries consist of pairs of keys and their corresponding values, both arbitrary data values.  Dictionaries are also known as associative arrays or hash tables.

Parameters

Returns

The create_dictionary() primitive returns the identifier associated with the new dictionary.

Portability

A GriefEdit extension.

See Also

delete_dictionary, set_property, get_property

int delete_dictionary( int  obj_id )

Destroy a dictionary.

Description

The delete_dictionary() primitive destroys the specified dictionary obj_id.

Parameters

Returns

The delete_dictionary() primitive returns 0 on success, otherwise -1 on error.

Portability

A GriefEdit extension.

See Also

create_dictionary

void delete_macro( string  macro )

Delete a macro from memory.

Description

The delete_macro macro deletes a macro file, which contains one or more macros, from memory; the underlying macro object retains unchanged.

Any keyboard references and variables, both global and buffer will be retained.  If any of the macros within the deleted macro object are referenced at a later time, the normal macro load logical is applied which may in turn reload the object.

Parameters

Returns

nothing

Portability

Not implemented.

See Also

load_macro

int dict_clear( int  obj_id )

Clear a dictionary.

Description

The dict_clear() primitive removes all items of the specified dictionary obj_id.

Parameters

Returns

The dict_clear() primitive returns 0 on success, otherwise -1 on error.

Portability

A GriefEdit extension.

See Also

delete_dictionary, dict_delete, dict_each, dict_keys, dict_values

int dict_delete( int  obj_id, string  key )

Remove a dictionary item.

Description

The dict_delete() primitive removes the item associated with the item key from the specified dictionary obj_id.

Parameters

Returns

The dict_delete() primitive returns 0 on success, otherwise -1 on error.

Portability

A GriefEdit extension.

See Also

delete_dictionary, dict_clear, dict_each, dict_keys, dict_values

int dict_each( int  obj_id,     [string key],   [declare value] )

Iterator a dictionary.

Description

The dict_each() primitive iterates thru a dictionary.

Returns the element index started at one and populates key and value with the entry details, so one may iterate over all elements within the dictionary.

There is no guarantee of order, entries are returned in an apparently random order; driven by the underlying hashing value.

When the dictionary is entirely read, a zero or FALSE value is returned.

You must not modify the dictionary whilst iterating over it.  There is a single iterator for each dictionary, shared by dict_each, dict_keys and dict_values primitives, as such care should be taken not to intermix their usage.

The following prints out your environment like the printenv program, only in a different order:

int index;
while ((index = dict_each(dict, key, value)) >= 0) {
    insertf("%d:%s=%s\n", index, key, value);
}

Parameters

Returns

The primitive returns the positive element index on success, otherwise zero at the end of the dictionary.

Portability

A GriefEdit extension.

See Also

create_dictionary, dict_keys, dict_values

int dict_exists(   int  obj_id, string  key )

Dictionary item existence check.

Description

The dict_exists() primitive determines the existence of an item within the specified dictionary obj_id.

Parameters

Returns

The dict_exists() primitive returns TRUE on success otherwise FALSE.

Portability

A GriefEdit extension.

See Also

create_dictionary, dict_each, dict_keys, dict_values

int dict_keys( int  obj_id,     [string key] )

Iterator dictionary keys.

Description

The dict_keys() primitive iterates thru a dictionary.

Returns the element index started at one and populates key with the entry details, so one may iterate over all elements within the dictionary.

There is no guarantee of order, entries are returned in an apparently random order; driven by the underlying hashing value.

When the dictionary is entirely read, a zero or FALSE value is returned.

You must not modify the dictionary whilst iterating over it.  There is a single iterator for each dictionary, shared by dict_each, dict_keys and dict_values primitives, as such care should be taken not to intermix their usage.

The following prints out your environment like the printenv program, only in a different order:

int index;
while ((index = dict_keys(dict, key)) >= 0) {
    insertf("%d:%s\n", index, key);
}

Parameters

Returns

The primitive returns the positive element index on success, otherwise zero at the end of the dictionary.

Portability

A GriefEdit extension.

See Also

create_dictionary, dict_each, dict_values

list dict_list( int  obj_id,   [int keys = TRUE] )

Retrieve dictionary items.

Description

The dict_list() primitive retrieves the keys or values contained within the specified dictionary obj_id.

Parameters

Returns

The dict_list() primitive returns a list of values containing all the keys or values within the specified dictionary, otherwise a null list.

Portability

A GriefEdit extension.

See Also

create_dictionary

string dict_name( int  obj_id )

Retrieve a dictionary name.

Description

The dict_name() primitive retrieves the name associated with the specified dictionary obj_id.

Parameters

Returns

The dict_name() primitive returns the name of the dictionary otherwise an empty string.

Portability

A GriefEdit extension.

See Also

create_dictionary

int dict_values( int  obj_id,     [declare value] )

Iterator dictionary values.

Description

The dict_values() primitive iterates thru a dictionary.

Returns the element index started at one and populates value with the entry details, so one may iterate over all elements within the dictionary.

There is no guarantee of order, entries are returned in an apparently random order; driven by the underlying hashing value.

When the dictionary is entirely read, a zero or FALSE value is returned.

You must not modify the dictionary whilst iterating over it.  There is a single iterator for each dictionary, shared by dict_each, dict_keys and dict_values primitives, as such care should be taken not to intermix their usage.

The following prints out your environment like the printenv program, only in a different order:

int index;
while ((index = dict_each(dict, value)) >= 0) {
    insertf("%d=%s\n", index, value);
}

Parameters

Returns

The primitive returns the positive element index on success, otherwise zero at the end of the dictionary.

Portability

A GriefEdit extension.

See Also

create_dictionary, dict_each, dict_keys

do statement; while ( condition );

do statement.

Description

The do statement implements the do-while loop construct.

do {
    statements;
} while (condition);

Executes statements one or more times until condition is non-zero.  The condition is tested after each iteration of the loop.

Portability

n/a

See Also

Iteration Statements, while, break, continue, for, if

if ( expr ) true-body else false-body

else statement.

Description

The else statement implements the secondary condition in the if-then-else construct.

See Also

Selection Statements

declare execute_macro( [string cmd], ... )

Invokes a command by name.

Description

The execute_macro() primitive invokes the specified command cmd, which if omitted the user shall be prompted as follows:

Command:

When an invoked command is undefined, GRIEF shall attempt to load the associated macro file sourced from the directories listed in the GRPATH.  If the macro file is successfully loaded and the command is found, the macro is then executed.

Parameters

Returns

The execute_macro() primitive returns the result of the executed command, otherwise upon an error -2 shall be returned..

Portability

n/a

See Also

load_macro

void exit( [string y_or_w] )

Exit current process level.

Description

The exit() primitive signals to leave the current process loop, which if the top level loop causes GriefEdit to terminate to the operating system.

Upon leaving the top level prior to exiting when modified buffers are present the user shall be prompted as to whether or not the buffers should be saved, as follows;

1 buffer has not been saved. Exit [ynw]?

The user may have all modified buffers saved prior to terminating by replying with either “W” or “w”, otherwise terminate without saving any buffers using “Y” or “y”.  Alternatively the user may reject the exit signal altogether with a reply of “N” or “n”.

Parameters

Returns

nothing

Portability

n/a

See Also

abort, process

finally statement;

Finally statement.

Description

The finally statement is reserved for future use, shall implement try, catch and finally constructs.

Parameters

none

Returns

nothing

Portability

A GriefEdit extension.

See Also

try, catch, throw

int first_time()

Determine a macros initialisation status.

Description

The first_time() primitive returns true if this is the first invocation of the calling macro since loading.

Each macro maintains a first_time status, which during the first execution of the macro is true and all subsequent calls shall be *false.  This primitive is generally used to perform run-time subsystem initialisation, for example.

if (first_time()) {
    initialise();
}

The loading of macro resets the first_time flag, is effect deleting the macro and reloading will look like it was never loaded.

Parameters

none

Returns

The first_time() primitive returns true (non-zero) if the first invocation of the associated macro, zero otherwise.

Portability

n/a

See Also

static

for ( [initialise]; [condition]; [increment] ) statements;

for statement.

Description

The for statement implements the for loop construct.

for (initialise; condition; increment)
{
    statements;
}

Repeatedly performing statements while the condition is true (non-zero).

When the for function starts, initialise is evaluated once.  It evaluates condition and if the result is non-zero, it evaluates the statements.  Finally, increment is evaluated, and control returns to the condition evaluation.  The process is repeated from here until the condition is evaluated zero.

Portability

n/a

See Also

Iteration Statements, break, continue, while, do

void foreach( <body>, <expr>, <key>, <value>, <index>, <increment> )

Container iterator.

Description

The foreach statement is reserved for future use.

Parameters

n/a

Returns

The foreach statement returns the element index retrieved, otherwise -1 upon an end-of-source condition or error.

Portability

n/a

See Also

list_each, dict_each

int fstype( [string path] )

File system type.

Description

The fstype() primitive retrieves the underlying file-system type.

Parameters

Returns

The fstype() primitive returns a system dependent file-system identifier, otherwise -1 on error or not supported.

Portability

A GriefEdit extension.

See Also

stat

declare get_property( int  obj_id, string  key )

Retrieve a dictionary item.

Description

The get_property() primitive retrieves the value of an item from the specified dictionary obj_id.

This primitive is generally not required within the GRIEF Macro Language.  When the user accesses an object member, the compiler converts the construct into calls to this macro.

The following are equivalent;

        get_property(object, "member");
and:
        object.member;

Parameters

Returns

The get_property() primitive returns the item value otherwise NULL.

Portability

A GriefEdit extension.

See Also

create_dictionary, set_property, dict_exists, dict_each

if ( expr ) true-body

if statement.

Description

The if statement implements the if-then-else construct.  The else is optional.  Evaluates the condition expr; if the condition is non-zero, executes the if_statements; otherwise, it executes the else_statements.

if (condition)
    { if_statements }
[else]
    { else_statements }

See Also

Selection Statements, else, while

int inq_btn2_action()

Retrieve the second button action.

Description

The inq_btn2_action() primitive is reserved for future BRIEF compatibility.

The inq_btn2_action() primitive retrieves the current action status of the second mouse button.  The function can be used to assign a mouse action handler into a newly pushed keyboard, which shall be automatically removed upon the keyboard destruction.

Parameters

none

Returns

Returns the current action button status.

Portability

n/a

string inq_called()

Get the name of the calling macro.

Description

The inq_called() primitive returns the callers name, allowing macros to differentiate between being called directly from the command prompt, or from another macro.

This primitive is provided to support replacement macros and to allow macros to determine whether user prompts get_parm are suitable and message output may be required.

Returns

The inq_calling() primitive returns a string containing the name of the macro which called the current macro, otherwise an empty string where invoked from the keyboard.

The set_calling_name can be used to modify the value returned in-turn controlling the behaviour of the macros which are then invoked.

See Also

set_calling_name, replacement

int inq_macro( string  name,   [int mode = 0] )

Determine whether a macro or primitive exists.

Description

The inq_macro() primitive tests whether the specified macro name exists within a stated namespace(s) defined by mode.

Parameters

Tests

The following test behaviours are available given by mode;

Returns

The inq_macro() primitive returns a mode specified value, otherwise -1 if the stated mode was invalid.

Portability

The autoload visibility under mode 0x01 and mode 0x03 are GriefEdit extensions.

See Also

load_macro

string inq_macro_history( [int index = 0] )

Retrieve macro execution history.

Description

The inq_macro_history() primitive retrieves the name of the previously executed macro as a result of a keyboard binding.

If index is specified, it specifies the history index starting at an offset of zero, otherwise the most recent (i.e. index 0) is returns.

The home and end macros are good examples of its usage, which modify their behaviour based upon previous operations.

Parameters

Returns

The inq_macro_history() primitive returns the name of the macro invoked, otherwise an empty string if the item does not exist.

Portability

A GriefEdit extension, matching similar CRiSPEdit functionality of the same name.

See Also

set_macro_history, inq_command

string inq_module( [int test = 1] )

Retrieve the current module.

Description

The inq_module() primitive retrieves the module name assigned with the calling macro.  When loaded macros are automaticly assigned with a unique module name or can be specificly assigned using the module primitive.

Module names are used to implement name spaces for static macro functions or to provide a way of creating a macro package split amongst source files.

Example

The following example setups a static scoped callback function

void
main(void)
{
        register_callback( inq_module() + "::callback" );
}

static void
callback(void)
{
}

Returns

The inq_module() primitive returns the name of the current module.

Portability

A GriefEdit extension.

See Also

module, static, <scope>

int inq_msg_level()

Get the message level.

Description

The inq_msg_level() primitive retrieves the current message level.

Parameters

none

Returns

The inq_msg_level() primitive returns the message level.

Portability

n/a

See Also

set_msg_level

list list_of_dictionaries(   [bool nonempty = false], [bool named = false] )

List of created dictionaries.

Description

The list_of_dictionaries() primitive retrieves a list of dictionary identifiers created by the create_dictionary primitive.

Parameters

Returns

The list_of_dictionaries() primitive retrieves a list of dictionaries.

Portability

A GriefEdit extension.

See Also

create_dictionary

int load_macro( string  filename,   [int reload = 1] )

Load a macro object.

Description

The load_macro() primitive loads the specified macro object filename, resolving all external references in the file.

If filename does not contain a path specification, then all directories contained within the GRPATH environment variable are searched.

If reload is either omitted or non-zero, the macro shall be reloaded regardless of whether the object image has already been loaded using load_macro or a autoload reference.  Otherwise if zero the image shall not be reloaded if a image with the same name was loaded previously.

Once a successful load the macro objects main entry point is executed.

Parameters

Returns

The load_macro() primitive returns 1 if macro file was successfully loaded; return 2 if reload is non-zero an a loaded image already exists; otherwise 0 on failure.

Portability

Unlike BRIEF, macros in source form (.m files) can be loaded with this macro.

The reload option is an GriefEdit extension.

See Also

autoload, inq_macro, main

declare macro( list  declaration )

Define a macro body.

Description

The macro internal primitive is the mechanism by which macros are imported during the loading of a macro object.

Parameters

Returns

Result of any main and/or associated internal _init execution.

Portability

n/a

See Also

replacement

int module( string  modulename )

Assign a module identifier.

Description

GRIEF provides a mechanism for alternative namespaces, being an abstract container providing context for the items, to protect modules from accessing on each other’s variables.

The purpose of this functionality is to provide data hiding within a set of common macro files (objects), by allowing separate function and variables namespaces.  Each namespace creates a container for a set of symbols, providing a level of indirection to specific identifiers, thus making it possible to distinguish between identifiers with the same exact name, in effect reducing naming conflicts in unrelated objects (See: Scope).

The module statement declares the object as being in the given namespace.  The scope of the module declaration is from the declaration itself and effects all current and future declarations within the associated object.

The intended usage of the module() primitive is the within the main function in all of the related objects.

The namespace specification should be a string containing a valid sequence of identifier symbols of the form

[A-Za-z_][A-Za-z_0-9]*

Namespaces are in conjunction with static scoping of members ((see static )).  If you are writing a set of macros some of which are internal and some for external use, then you can use the static declaration specifier to restrict the visibility of a member variable or function.

However as static functions are 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.

Multiple objects can contained within the same namespace.  The module primitive allows you to refer to static functions defined in another macro file explicitly, using the “::” naming modifier, and also allows static macro functions to be accessed in callbacks.  Upon a module being associated, it is possible to refer use the syntax “<module-name>::<function>” to refer to a function in callbacks.

Example

void
main()
{
        module("my_module");
        assign_to_key("<Alt-D>", "my_module::doit");

        // which to has the identical behaviour as
        assign_to_key("<Alt-D>", "::doit");

        // and
        assign_to_key("<Alt-D>", inq_module() + "::doit");
}

static void
doit()
{
        :
        :
}

Returns

The module primitive returns 0 on success, otherwise 1 if module already existed or -1 if called outside the context of any macro file.

Portability

A GriefEdit extension.

See Also

inq_module, <scope>, static, assign_to_key

void nothing()

Noop.

Description

The nothing() primitive is a no operation, noop for short, This primitive it acts as a place holder when a dummy function is required, effectively does nothing at all.

Parameters

none

Returns

nothing

Portability

n/a

See Also

error

int register_macro( int  type,   string  macro,   [int local = FALSE] )

Register a callback procedure.

Description

The registered_macro() primitive registers a function to be invoked upon the trigger of the event type type.  Multiple macros may be associated against any particular event type, in which case upon execution they are called in FIFO order.

The argument macro is the name of a macro to be invoked upon the event being triggered.  If local is specified and is non-zero, then the macro is only registered against the current buffer, otherwise the event may be triggered even when the current buffer is not selected.

Registered macros may be invoked using call_registered_macro and removed by using the unregister_macro primitive.

Parameters

Returns

The registered_macro() primitive returns 1 if the macro was successfully registered, 0 if already registered, otherwise -1 on error.

Portability

The set of available events differ between systems.

See Also

int reload_buffer( [int bufnum], [string encoding] )

Reload the buffer content.

Description

The reload_buffer() primitive is reserved for future use.

Parameters

Returns

n/a

Portability

n/a

See Also

edit_file

replacement <macro-definition>

Overload an existing macro definition.

Description

The replacement macro modifier is used to explicity declare overloaded interfaces, which is a macro that supersedes (or complements) either another macro or directly executable function of the same name.

Replacement macros are used to intercept calls to other macros or functions and are usually to enhance existing the functionality of thoses commands without rewriting them completely.

For example the following macro replaces edit_file;

edit_file()
{
    edit_file();
    beep();
}

Any reference to edit_file() in the replacement macro refers to the function which is replaces; hence in this example edit_file(), then calls the orginal edit_file() and then beeps() on its return.

During a compile when a macro which overloads an built-in macro is encountered, the compiler shall generate a warning message.  To suppress the warning the keyword replacement should be stated prior to the function name, as follows:

replacement
edit_file()
{
        edit_file();
        beep();
}

Note that the only behaviour effected by the replacement keyword is the warning suppression and defining a function the same as built-in shall always result in an implicit function overloading.  As such the two examples are functionality equivalent.

Returns

n/a

Portability

n/a

See Also

macro, static, extern, global

int require( string  filename )

Enforce the use of an external module.

Description

The require() primitive enforces that the specified macro object filename be loaded if it has not already been loaded.

This primitive is similar to using load_macro with a reload option of zero, but is provided as a more convenient and explicit form.

The best practice of this primitive, use require within the main function of any given macro object.

void main(void)
{
    require("utils");   // our external dependency
}

Returns

Returns 0 if already loaded; 1 if the macro as loaded.  Otherwise -1 if the macro file could not be loaded.

Portability

n/a

See Also

load_macro, autoload

int reregister_macro( int  type,   string  macro,   [int local = FALSE] )

Register a unique callback procedure.

Description

The reregistered_macro() primitive registers a unique function to be invoked upon the trigger of the event type type.  Similar to register_macro yet only permits a single instance of the given function tp be registered.

This primitive allows macros to unconditionally register handlers without need to know whether a previous instance has been installed, unlike register_macro which shall permit multiple instances to exist.

See register_macro for the particulars on the different registered event types.

Parameters

Returns

The reregistered_macro() primitive returns 1 if the macro was uniquely registered, 0 if already registered, otherwise -1 on error.

Portability

The set of available events differ between systems.

See Also

register_macro

int restore_position( [int what = 1] )

Restore a previously saved position.

Description

The restore_position() primitive restores a previously saved position from the position stack.  The argument what is an optional integer expression which controls the state that is restored.

When states what, specifies the information which is restored.  If omitted what is equivalent to one;

Parameters

Returns

The restore_position() primitive returns 1 on success, otherwise zero or less on error.

Portability

n/a

See Also

save_position

return [<expression>];

Return from a macro.

Description

The return() primitive terminate the current macro and returns the given value expression.  If specified expression may be an integer, string or list expression which matches the return type of the associated macro.

If return or returns is not called, the return value for a macro is indeterminate.

Parameters

Returns

nothing

See Also

returns, exit, *

returns ( expression );

Return an expression from a macro.

Description

The returns() primitive sets the return value of the current macro to expression, which may be an integer, string or list expression which matches the return type of the associated macro.

This primitive is similar to the return statement, except it does not cause the current macro to terminate.  It simply sets GRIEF’s internal accumulator with the value of the expression; as such any following may overwrite the value.

Parameters

Returns

nothing

See Also

Jump Statements, return, exit

void save_position()

Saves current cursor/buffer state.

Description

The save_position() primitive pushes the current buffer, window and cursor position into the position stack, allowing them to be restored later using restore_position.

As these states are maintained by a stack in LIFO (Last In First Out) order each invocation of save_position should have a corresponding invocation of restore_position, otherwise saved positions shall accumulate consuming system resources.

Parameters

none

Returns

nothing

Portability

n/a

See Also

restore_position

int set_btn2_action( [int action] )

Set the second button action.

Description

The set_btn2_action() primitive is reserved for future BRIEF compatibility.

The set_btn2_action() primitive sets or toggles the default action for the second mouse button.  If action is zero, the Quick-Edit action will be the default.  If action is non-zero, the Quick-Menu action will be the default.  If action is omitted, the current setting shall be toggled.

Parameters

Returns

Returns the previous action button status.

Portability

n/a

void set_calling_name( string  name  =  NULL )

Set the name of the calling macro.

Description

The set_calling_name() primitive sets the calling name of the current macro, which is the name that would be returned by inq_name() within any macros called.  If omitted then the name is cleared and returned to the original name.

set_calling_name is used to modify the value returned in-turn controlling the behaviour of the macros which are then invoked.

Another common use is within replacement macros, to forward the original callers name onto the next macro.

set_calling_name(inq_called());

Returns

Nothing

See Also

inq_called, replacement

string set_macro_history(   [int index = 0], [string value] )

Set the macro execution history.

Description

The set_macro_history() primitive replaces an entry within the macro execution history.

index specifies the history index starting at an offset of zero.  value is new replace name.

Parameters

Returns

The set_macro_history() primitive returns the previous value name of entry replaced, otherwise an empty string if the item does not exist.

Portability

A GriefEdit extension, matching similar CRiSPEdit functionality of the same name.

See Also

inq_macro_history

int set_property(   int  obj_id, string  key,   [declare value] )

Set a dictionary item.

Description

The set_property() primitive sets the value of an item within the specified dictionary obj_id.

This primitive is generally not required within the GRIEF Macro Language.  When the user accesses an object member, the compiler converts the construct into calls to this macro.

The following are equivalent;

        set_property(object, "member", value);
and:
        object.member = value;

Parameters

Returns

The set_property() primitive returns TRUE on success otherwise FALSE.

Portability

A GriefEdit extension.

See Also

create_dictionary, get_property, dict_exists, dict_each

switch( expr ) statement

Switch statement.

Description

The switch and case statements help control complex conditional and branching operations.  The switch statement transfers control to a statement within its body.  The body of a switch statement may have an arbitrary number of unique case labels, for example.

switch (value) {
case 1:
    w = "one";
    break;
case 2:
    w = "two";
    break;
default:
    w = "others";
    break;
}

If condition evaluates to the value that is equal to the value of one of case expressions, then control is transferred to the statement that is labelled with that expression.

If condition evaluates to the value that does not match any of the case labels, and the default label is present, control is transferred to the statement labelled as the default label.

The break statement, when encountered in statement exits the switch statement.

Parameters

Returns

nothing

Portability

n/a

See Also

Selection Statements, case, break

throw expr;

Throw an exception.

Description

The throw statement is reserved for future use.

Exceptions are used to indicate that an error has occurred while running the program.  Exception objects that describe an error are created and then thrown with the throw primitive.  The runtime then searches for the most compatible exception handler.

Parameters

Returns

nothing

Portability

A GriefEdit extension.

See Also

try, catch, finally

try statement; catch statement; finally statement;

Try statement.

Description

The try statement is reserved for future use, which shall implement try, catch and finally exception constructs.

Exceptions are used to indicate that an error has occurred while running the program.  Exception objects that describe an error are created and then thrown with the throw primitive.  The runtime then searches for the most compatible exception handler.

try {
    statement;

} catch type {
    statement;

} finally {
    statement;

}

Parameters

none

Returns

nothing

Portability

A GriefEdit extension.

See Also

catch, finally, throw

int unregister_macro( int  type,   string  macro,   [int local = FALSE] )

Remove a registered macro.

Description

The unregistered_macro() primitive removes a previously registered macro.

If a particular macro has been registered multiple times than for each successful registration a corresponding unregister must occur to remove all instances; unregister_macro may be called in a loop until all instances are removed.

Parameters

Returns

The unregistered_macro() primitive returns 1 if macro was registered and has now been unregistered, otherwise 0.

Portability

The set of available events differ between systems.

See Also

register_macro

while ( [condition] ) statements;

while statement.

Description

The while statement implements the while loop construct.

while (condition)
{
    statements;
}

Repeatedly performs statements while the condition is true (non-zero).  In each iteration of the loop, it first tests the condition, and if it is true it executes statement.  This cycle is continued until condition is false (zero).

Portability

n/a

See Also

Iteration Statements, break, continue, for, do

$Id: $