| Miscellaneous Primitives | |
| Macros | |
| __regress_op | Regression operations. |
| __regress_replacement | Replacment regression testing. |
| beep | Issue a beep sound. |
| color_index | Border color background color index. |
| date | Get current system date. |
| gmtime | Convert a time value to UTC time components. |
| grief_version | GRIEF version. |
| inq_clock | Retrieve the user identifier. |
| localtime | Convert a time value to local time components. |
| process_mouse | Process mouse event. |
| rand | Generate a random number. |
| set_msg_level | Set level of informational messages. |
| srand | Seed the random number generator. |
| time | Get the current system time. |
| version | Version information. |
int __regress_op( ... )
Regression operations.
The __regress_op() primitive is an INTERNAL function utilised using system regression testing, providing access to miscellanous system library functions.
n/a
Direct use of __regress_op() is not advised and is only documented for completeness.
Functionality may change or be removed without notice.
GriefEdit specific, functionality may change without notice.
<regress>
declare __regress_replacement( ... )
Replacment regression testing.
The __regress_replacement() primitive is an internal function utilised by the regress macro to assert replacement macro features.
n/a
Direct use of __regress_replacement() is not advised and is only documented for completeness.
Functionality may change or be removed without notice.
GriefEdit specific, functionality may change without notice.
<regress>, __regress_op
int beep( [int freq], [int duration] )
Issue a beep sound.
The beep() primitive sends a bell or beep to the screen causing an audible sound.
The function is synchronous; it performs an alertable wait and does not return control to its caller until the sound finishes.
freq and duration are system dependent values.
| freq | The frequency of the sound, in hertz. This parameter must be in the range 37 through 32,767. |
| duration | The duration of the sound, in milliseconds. |
The beep() primitive returns 0 on success, otherwise -1 on error.
A GriefEdit extension.
int color_index( [int index] )
Border color background color index.
The color_index() primitive sets the current value of the color index. The index controls the color that shall be assigned as the borderless background color to the next window created. On assignment the color index shall be automatically incremented and contained within the range 0 .. 16.
When borders are disabled, this color shall be used as the background of the associated window allowing one to distinguish between individual views.
| index | Optional integer index between the ranges of 0 and 16, if omitted the current index is returned without effecting any change effectively behaving like a inq_color_index function. |
Returns the previous value of the color index.
A GriefEdit extension.
int date( [int &year], [int &month], [int &day], [string &monname], [string &dayname] )
Get current system date.
The date() primitive retrieves the current date in local time.
The following numeric components are returned.
| year | Year, in the range [1900-2099]. |
| month | Month of the year in the range [1-12]. |
| day | Day of the month, in the range [1-31]. |
in addition if supplied the following string values are populated
| monname | Name of the month (e.g. “January”). |
| dayname | Name of the day (e.g. “Monday”). |
The date function returns the current value of time in seconds since the Epoch which the components represent.
Displays the current date
int year, month, days;
string dayname;
date(year, month, day, NULL, dayname);
message("%s, %d/%d/%d", dayname, year, month, day);
int gmtime( [int time = NULL], [int &year], [int &mon], [int &mday], [string &monname], [string &dayname], [int &hour], [int &min], [int &sec] )
Convert a time value to UTC time components.
The gmtime() primitive converts the time in seconds since the Epoch (1970/1/1) into its components, expressed as Coordinated Universal Time (UTC). If time is omitted the current time is broken-down into components.
The gmtime function returns the value of time in seconds since the Epoch which the components represent.
A GriefEdit extension
int grief_version()
GRIEF version.
The grief_version() primitive retrieves the current GRIEF version.
none
The grief_version primitive returns the current version multiplied by 100 plus the minor; for example 101 represents version 1.1.
A GriefEdit extension.
int inq_clock()
Retrieve the user identifier.
The inq_clock() primitive retrieves an approximation of the current CPU time used by the current edit session.
This primitive is an interface to the system clock() function, yet normalises the returned value to microseconds; to determine the number of seconds used, divide by the system constant CLOCKS_PER_SEC.
Note loops every 72 minutes.
none
The inq_clock returns the time in microseconds since start of the current GriefEdit instance.
If the processor time used is not available or its value cannot be represented, the function returns the value -1.
n/a
int localtime( [int time = NULL], [int &year], [int &mon], [int &mday], [string &monname], [string &dayname], [int &hour], [int &min], [int &sec] )
Convert a time value to local time components.
The localtime() primitive converts the time in seconds since the Epoch (1970/1/1) into its components, expressed as local time also known as wall-clock. If time is omitted the current time is broken-down into components.
The localtime function returns the value of time in seconds since the Epoch which the components represent.
A GriefEdit extension.
void process_mouse( [int b1], [int b2], [int b3], int x, int y )
Process mouse event.
The process_mouse() primitive allows an external mouse event to be processed; some mice types are handled internally whereas others require macro support.
| b1, b2, b3 | Button states, zero for up otherwise non-zero for down. |
| x, y | Screen coordinates. |
nothing
n/a
int rand( [int upper] )
Generate a random number.
The rand() primitive computes a sequence of pseudo-random integers in the range 0 to RAND_MAX.
rand will by default produce a sequence of numbers that can be duplicated by calling srand() with 1 as the seed.
The srand primitive can be use to set/reset to random seed plus modify the generator table depth. This implementation uses a non-linear additive feedback random number generator employing a default table of size 31 long integers to return successive pseudo-random numbers in the range from 0 to (2**31)-1.
The period of this random number generator is very large, approximately 16*((2**31)-1).
| upper | Optional integer stating the upper range of the returned random number, if omitted 2^32. |
The rand primitive returns a random number in the range 0..2^31 or 0..upper if a positive upper value is stated.
int set_msg_level( int level )
Set level of informational messages.
The set_msg_level() primitive sets the message level for the duration of the current command.
The message level control what type of messages are to be made visible on the status line; it allows macros to suppress messages from macros.
By default the message level is a value of 1 whenever a command is invoked from the keyboard or a registered macro, and set to zero when the command completes.
The specified level is a value in the range 0-3 with the following effects:
| 0 | All messages are enabled; the default value. |
| 1 | Normal messages are not displayed, error messages still display. |
| 2 | Error messages are suppressed. |
| 3 | Suppress all messages, both message and error. |
| level | Integer value specifying the new message level. |
The set_msg_level() primitive returns the previous message level.
n/a
int srand( [int seed = time()], [int depth] )
Seed the random number generator.
The srand() primitive initialises the random number generator based on the given seeds.
The seed is used to prime the generator running at the specified depth.
By default, the package runs with 128 bytes of state information and generates far better random numbers than a linear congruential generator. If the amount of state information is less than 32 bytes, a simple linear congruential R.N.G. is used.
| seed | Basic initial primer, if omitted defaults to the current value of time. |
| depth | Optional integer depth controlling how sophisticated the random number generator shall be. Current “optimal” values for the amount of state information are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to the nearest known amount. Using less than 8 bytes will cause an error. |
The srand() primitive returns 0 on success, otherwise -1 on error.
int time( [int &hour], [int &min], [int &sec], [int &msec] )
Get the current system time.
The time() primitive retrieves the current time in local time.
The following numeric components are returned
| hours | Hour of the day, in the range [0-23]. |
| mins | Minutes of the hour, in the range [0-59]. |
| secs | Seconds of the minute, is the range [0-60]. |
| msecs | Milliseconds, in the range [0-9999] |
The time() primitive returns the value of time in seconds since the Epoch (1970/1/1).
Displays the current date
int hour, min, sec, msec;
time(hour, min, sec, msec);
message ("time, %d:%d:%d.%d", hour, min, sec, msec);
The msec parameter is a GriefEdit extension; the BRIEF version returned only hundredths of seconds.
int version( [int major | string machtype], [int min], [int edit], [int release], [string machtype], [string compile], [int cmversion], [string features], [string build] )
Version information.
The version() primitive retrieves the version information associated with the current GRIEF installation.
If the first argument is omitted, displays the current version and build information on the command prompt, for example:
GRIEF v3.2.0 compiled Aug 20 2014 20:05:04
The first parameter may be either an integer or string variable, which shall be populated with the major version or the machine type representatively.
All additional parameters are either integer or string variable references which are populated with their associated value.
| major | Integer major version number. |
| min | Integer minor version number. |
| edit | Integer sub version number. |
| release | Integer build-number. |
| machtype | Machine type labels, value include “DOS”, “OS/2”, “UNIX” and “VMS”; for additional host information see uname. |
| compiled | GRIEF engine compilation timestamp. |
| cmversion | Macro compiler language version. |
| features | String of comma separated built-in features (reserved for future use). |
| build | Populated with the host build label. |
The version() primitive returns the current version multiplied by 100, plus the minor; for example 301 represents version 3.1.
All the arguments are extensions.
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Regression operations.
int __regress_op( ... )
Replacment regression testing.
declare __regress_replacement( ... )
Issue a beep sound.
int beep( [int freq], [int duration] )
Border color background color index.
int color_index( [int index] )
Get current system date.
int date( [int &year], [int &month], [int &day], [string &monname], [string &dayname] )
Convert a time value to UTC time components.
int gmtime( [int time = NULL], [int &year], [int &mon], [int &mday], [string &monname], [string &dayname], [int &hour], [int &min], [int &sec] )
GRIEF version.
int grief_version()
Retrieve the user identifier.
int inq_clock()
Convert a time value to local time components.
int localtime( [int time = NULL], [int &year], [int &mon], [int &mday], [string &monname], [string &dayname], [int &hour], [int &min], [int &sec] )
Process mouse event.
void process_mouse( [int b1], [int b2], [int b3], int x, int y )
Generate a random number.
int rand( [int upper] )
Set level of informational messages.
int set_msg_level( int level )
Seed the random number generator.
int srand( [int seed = time()], [int depth] )
Get the current system time.
int time( [int &hour], [int &min], [int &sec], [int &msec] )
Version information.
int version( [int major | string machtype], [int min], [int edit], [int release], [string machtype], [string compile], [int cmversion], [string features], [string build] )
Control cursor display.
int cursor( int state )
Set window border status.
int borders( [int borders] )
Create and load a buffer.
int create_buffer( string bufname, [string filename], [int sysflag = FALSE], [int editflags = 0], [string encoding = ""] )
Suspend execution for an interval of time.
void sleep( [int seconds = 1], [int milliseconds = 0] )
Convert window coordinates.
int translate_pos( int x, int y, [int &winnum], [int &line], [int &col] )
Get the message level.
int inq_msg_level()
Issue an error message on the command line.
int error( string format, ... )
Display a message on the command line.
int message( string format, ... )
Retrieve system information.
int uname( [string &sysname], [string &nodename], [string &version], [string &release], [string &machine] )