General Primitives

Summary

General Primitives
Macros
__breaksw	Switch break statement.
__lexicalblock	Lexical scope.
__regress_op	Regression operations.
__regress_replacement	Replacment regression testing.
abort	Abnormal process.
above	Greater than comparison.
above_eq	Greater than or equal comparison.
abs	Absolute value.
access	Test file accessibility.
acos	Arc cosine.
arg_list	Argument list.
asin	Arc sine.
assign_to_key	Assign command to key or key sequence.
atan	Arctangent.
atan2	Arctangent division.
atoi	Convert string to a decimal number.
attach_buffer	Attach a buffer to a window.
attach_syntax	Attach a syntax to a buffer.
autoload	Register location of one or more macros.
backspace	Delete character to the left of the cursor.
basename	Return the last component of a pathname.
beep	Issue a beep sound.
beginning_of_line	Goto beginning of line.
below	Less than comparison.
below_eq	Less than or equal comparison.
bless	Associate an object with a class/module.
bookmark_list	Retrieve existing bookmark list.
borders	Set window border status.
break	break statement.
call_registered_macro	Invoke registered macro callbacks.
car	Retrieve the first list element.
cd	Change directory.
cdr	Retrieve all secondary list elements.
ceil	Round up to integral value.
cftime	Format time and date.
change_window	Selects a new window.
change_window_pos	Modify window coordinates/size.
characterat	Retrieve the character value within a string.
chdir	Change directory.
chmod	Change mode.
chown	Change owner.
close_window	Close specified the window.
color	Set the basic colors.
color_index	Border color background color index.
command_list	Retrieve list of built-in and active macros.
compare	Comparison.
compare_files	Binary file compare.
compress	Compress repeated instances of white-space characters.
connect	Attach a process to a process.
const	Define a variable as being constant.
continue	Loop continuation.
copy	Copy marked area to scrap.
copy_keyboard	Copy a keyboard.
copy_screen	Copy the current screen.
cos	Cosine.
cosh	Hyperbolic cosine.
create_buffer	Create and load a buffer.
create_char_map	Create a display character-map.
create_dictionary	Create a dictionary.
create_edge	Create an edge, splitting the window.
create_menu_window	Create the menu window.
create_nested_buffer	Create or reference a buffer.
create_syntax	Syntax table creation.
create_tiled_window	Creates a tiled window.
create_window	Create a popup window.
cursor	Control cursor display.
cut	Cut marked area to scrap.
cvt_to_object	Convert string to object.
date	Get current system date.
debug	Control runtime debug and tracing.
debug_support	Internal debugger functionality.
declare	Declare a polymorphic symbol.
define_keywords	Add keywords to a syntax dictionary.
delete_block	Deleted selected region.
delete_bookmark	Delete a bookmark.
delete_buffer	Delete a buffer.
delete_char	Delete character.
delete_dictionary	Destroy a dictionary.
delete_edge	Delete an edge, combining a split window.
delete_line	Delete current line.
delete_macro	Delete a macro from memory.
delete_nth	Remove one or more elements from a list.
delete_to_eol	Delete to end-of-line.
delete_window	Delete a window.
detach_syntax	Detach a syntax from a buffer.
dialog_create	Build a dialog resource.
dialog_delete	Delete a dialog resource.
dialog_exit	Exit a dialog resource.
dialog_run	Execute a dialog resource.
dict_clear	Clear a dictionary.
dict_delete	Remove a dictionary item.
dict_each	Iterator a dictionary.
dict_exists	Dictionary item existence check.
dict_keys	Iterator dictionary keys.
dict_list	Retrieve dictionary items.
dict_name	Retrieve a dictionary name.
dict_values	Iterator dictionary values.
diff_strings	Compare to strings.
dirname	Report the parent directory name of a file pathname.
disconnect	Disconnect a buffer from a process.
display_mode	Set/retrieve display control flags.
display_windows	Control window display.
distance_to_indent	Calculate distance to next indent.
distance_to_tab	Calculate distance to next tab.
do	do statement.
double	Declare a double float symbol.
down	Move position down one line.
dprintf	Formatted diagnostics output.
drop_anchor	Start marking a selection.
drop_bookmark	Create or update a bookmark.
echo_line	Set echo line flags.
edit_file	Edit a file.
edit_file2	Extended file edit.
ega	Terminal line display.
end_anchor	Set the end of the anchor.
end_of_buffer	Move cursor to end of current buffer.
end_of_line	Goto end of line.
end_of_window	Goto end of the current window.
error	Issue an error message on the command line.
execute_macro	Invokes a command by name.
exist	Check file existence.
exit	Exit current process level.
exp	Exponential function.
expandpath	Expand the path.
extern	Declare an external variable.
fabs	Floating-point absolute value.
fclose	Close a stream.
feof	Test end-of-file indicator on a stream.
ferror	Test error indicator on a stream.
fflush	Flush a stream.
file_canon	Canonicalize a path.
file_glob	Return names of files that match patterns.
file_match	File match utility.
file_pattern	Directory file pattern.
filename_match	Perform file pattern matching.
filename_realpath	Return a resolved pathname.
find_file	Read next directory entry.
find_file2	Extended read next directory entry.
find_line_flags	Locate next line with specific flags.
find_macro	Determine path of a macro object.
find_marker	Locate next marker.
fioctl	File miscellaneous control.
first_time	Determine a macros initialisation status.
firstof	Leftmost character search.
flock	File lock operations.
floor	Round down to integral value.
fmktemp	Make a unique filename.
fmod	Floating-point remainder.
fopen	Open a stream.
for	for statement.
format	Formatted printing.
fread	Read from a stream.
frexp	Extract mantissa and exponent.
fseek	Reposition a file-position indicator in a stream.
fstat	Stream status information.
fstype	File system type.
ftell	Report the file-position indicator of a stream.
ftest	Test file type.
ftruncate	Truncate the specified file.
fwrite	Write to a stream.
get_color	Retrieve screen colors.
get_color_pair	Retrieve the specific color.
get_mouse_pos	Retrieve last mouse action.
get_nth	Retrieve a list element.
get_parm	Retrieve the value of a macro parameter.
get_property	Retrieve a dictionary item.
get_region	Retrieve marked region content.
get_term_characters	Retrieve terminal special characters.
get_term_feature	Get value of a terminal feature.
get_term_features	Retrieve terminate features.
get_term_keyboard	Retrieve the terminal keyboard definitions.
getenv	Retrieve an environment variable.
geteuid	Retrieve the effective user identifier.
getopt	Get options.
getpid	Retrieve the process identifier.
getsubopt	Parse suboption arguments from a string.
getuid	Retrieve the user identifier.
getwd	Get current working directory.
glob	Generate pathnames matching a pattern.
global	Declare a global variable.
gmtime	Convert a time value to UTC time components.
goto_bookmark	Seek a bookmark.
goto_line	Move to a particular line.
goto_old_line	Move to line before buffer modification.
grief_version	GRIEF version.
hilite_create	Create a hilite resource.
hilite_delete	Delete a hilite resource.
hilite_destroy	Destroy hilite resources.
if	if statement.
index	Search string for a leftmost sub-string or character.
input_mode	Effect of certain system keys.
inq_assignment	Get key assignment for function.
inq_attribute	Retrieve the current attributes.
inq_backup	Get the backup creation mode.
inq_backup_option	Get backup options.
inq_borders	Retrieve the border status.
inq_brief_level	Retrieve the editor nesting level.
inq_btn2_action	Retrieve the second button action.
inq_buffer	Retrieve a buffer identifier.
inq_buffer_flags	Retrieve buffer flags.
inq_buffer_title	Retrieve a buffer title.
inq_buffer_type	Retrieve buffer type.
inq_byte_pos	Get current position in buffer stream.
inq_called	Get the name of the calling macro.
inq_char_map	Retrieve the character-map.
inq_char_timeout	Get the escape delay.
inq_clock	Retrieve the user identifier.
inq_cmd_line	Retrieve the command line message.
inq_color	Retrieve the basic colors.
inq_command	Retrieve name of last keyboard command.
inq_ctrl_state	Retrieve the state of a window control.
inq_debug	Retrieve the current debug setting.
inq_dialog	Retrieve the current dialog resource.
inq_display_mode	Inquire display control flags.
inq_echo_format	Retrieve the echo-line format.
inq_echo_line	Retrieve the echo-line flags.
inq_encoding	Retrieve a buffers character encoding.
inq_feature	Retrieve an editor feature.
inq_file_change	Determine state of underlying file.
inq_file_magic	Retrieve the file type detection rules.
inq_font	Inquire the current window fonts.
inq_hilite	Retrieve a hilite definition.
inq_home	Retrieve the user home directory.
inq_hostname	Retrieve the local host name.
inq_idle_default	Retrieve idle interval.
inq_idle_time	Retrieve keyboard idle time.
inq_indent	Get current indentation settings.
inq_kbd_char	Peek at the keyboard.
inq_kbd_flags	Get keyboard key flags.
inq_kbd_name	Retrieve the assigned keyboard name.
inq_keyboard	Retrieve the keyboard identifier.
inq_keystroke_macro	Retrieve the current keystroke macro.
inq_keystroke_status	Determine keystroke macro status.
inq_line_col	Retrieve the echo_line content.
inq_line_flags	Retrieve a lines associated flags.
inq_line_length	Determine the longest line length.
inq_lines	Retrieve the line count.
inq_local_keyboard	Retrieve local keyboard identifier.
inq_macro	Determine whether a macro or primitive exists.
inq_macro_history	Retrieve macro execution history.
inq_margins	Retrieve buffer formatting margins.
inq_mark_size	Retrieve size of marked region.
inq_marked	Determine the current marked region.
inq_marked_size	Size the marked region.
inq_message	Retrieve the prompt line.
inq_mode	Returns the overstrike mode.
inq_modified	Determine a buffers modification status.
inq_module	Retrieve the current module.
inq_mouse_action	Retrieve the keyboard mouse handler.
inq_mouse_type	Retrieve the button type.
inq_msg_level	Get the message level.
inq_names	Retrieve associated buffer names.
inq_position	Retrieve current buffer position.
inq_process_position	Get position of process buffer.
inq_profile	Retrieve profile directory.
inq_prompt	Retrieve the prompt status.
inq_remember_buffer	Determine the keystroke buffer name.
inq_ruler	Retrieves the ruler specification.
inq_scrap	Obtain the scrap buffer identifier.
inq_screen_size	Determine screen dimensions.
inq_symbol	Determine if the symbol exists.
inq_syntax	Retrieve the syntax identifier.
inq_system	Determine if buffer is a system buffer.
inq_tab	Derive the tab increment.
inq_tabs	Retrieves the buffer tab specification.
inq_terminator	Retrieve a buffers line terminator.
inq_time	Retrieve the last modification time.
inq_tmpdir	Get the temporary-file directory.
inq_top_left	Retrieve window view port coordinates.
inq_username	Retrieve the user name.
inq_vfs_mounts	Retrieve list of mounts.
inq_views	Determine window count.
inq_window	Retrieve the current window.
inq_window_buf	Retrieve the associated buffer.
inq_window_color	Retrieve the window attribute.
inq_window_flags	Retrieve window flags.
inq_window_info	Retrieve the current window information.
inq_window_infox	Retrieve information about a window.
inq_window_priority	Retrieve the windows display priority.
inq_window_size	Retrieve the window size.
insert	Insert string into current buffer.
insert_buffer	Insert format text into a buffer.
insert_mode	Set the buffer insert/overstrike mode.
insert_process	Send string to a attached process.
insertf	Insert a formatted string.
int	Declare an integer symbol.
int_to_key	Convert an keycode to mnemonic key string.
is_array	Determine whether an array type.
is_float	Determine whether a float type.
is_integer	Determine whether an integer type.
is_list	Determine whether a list type.
is_null	Determine whether a NULL type.
is_string	Determine whether a string type.
is_type	Determine whether an explicit type.
isalnum	Alphanumeric character predicate.
isalpha	Alpha character predicate.
isascii	ASCII character predicate.
isblank	Blank character predicate.
isclose	Test for floating point equality.
iscntrl	Control character predicate.
iscsym	A symbol character predicate.
isdigit	Numeric character predicate.
isfinite	Test for finite value.
isgold	Alphanumeric character predicate.
isgraph	Graphic character predicate.
isinf	Test for infinity.
islower	Lowercase character predicate.
isnan	Test for a NaN.
isprint	A printable character predicate.
ispunct	Punctuation character predicate.
isspace	Space character predicate.
isupper	Uppercase character predicate.
isword	Word character predicate.
isxdigit	Hexadecimal character predicate.
itoa	Convert an integer into a string.
key_list	Retrieve keyboard bindings.
key_to_int	Convert key name to a code.
keyboard_flush	Flush the keyboard buffer.
keyboard_pop	Pop a keyboard from the keyboard stack.
keyboard_push	Push a keyboard onto the keyboard stack.
keyboard_typeables	Assign self_insert to all typeable keys.
lastof	Rightmost character search.
ldexp	Multiply by a power of two.
left	Move position left one charcter.
length_of_list	Determine list element count.
link	Link a file.
list	Declare a list symbol.
list_each	Iterator though the list elements.
list_extract	Extract list elements.
list_of_dictionaries	List of created dictionaries.
list_reset	Reset the list iterator.
load_keystroke_macro	Load a recorded macro from a file.
load_macro	Load a macro object.
localtime	Convert a time value to local time components.
log	Natural logarithm.
log10	Base 10 logarithm function.
lower	Convert string or character to lowercase.
lstat	Get symbolic link status.
ltrim	Chomp characters from the front of a string.
macro	Define a macro body.
macro_list	Retrieve list of current macros.
make_list	Build an evaluated list.
make_local_variable	Make a buffer local variable.
mark	Toggle the anchor status.
mark_line	Create a line marker.
message	Display a message on the command line.
mkdir	Create a directory.
mktemp	Make a temporary filename.
mode_string	Conversion stat mode to a string representation.
modf	Decompose a floating-point number.
module	Assign a module identifier.
move_abs	Move to an absolute location in the buffer.
move_edge	Modify a window.
move_rel	Move to a relative location in the buffer.
next_buffer	Identifier of the next buffer.
next_char	Move to the next character.
next_window	Obtain the next window identifier.
nothing	Noop.
nth	Extract the indexed list item.
output_file	Change the output file-name.
page_down	Move position down a page.
page_up	Move position up a page.
parse_filename	Parse a file into its components.
paste	Insert scrap buffer at cursor location.
pause	Pause keystroke definition.
pause_on_error	Set the error display mode.
pause_on_message	Set the message display mode.
perror	Print error.
playback	Replay a keystroke macro.
pop	Pop the last element.
pow	Raise to power.
prev_char	Move to the previous character.
previous_buffer	Identifier of the previous buffer.
print	Print formatted string to stdout.
printf	Print formatted string to stdout.
process	Invoke a Grief engine.
process_mouse	Process mouse event.
profile	Profiling support.
push	Add an element onto a list.
push_back	Push back a character into the keyboard.
put_nth	Modify a list element.
put_parm	Assign an argument value.
putenv	Set an environment variable.
quote_list	Build an unevaluated list.
quote_regexp	Quote regexp special characters.
raise_anchor	Raise the last dropped mark.
rand	Generate a random number.
re_comp	Compile a regular expression.
re_delete	Delete a compiled expression.
re_result	Retrieve search captures.
re_search	Search for a string.
re_syntax	Set the regular expression mode.
re_translate	Search and replace.
read	Read characters from the buffer.
read_char	Read next key from the keyboard.
read_file	Read into the current buffer.
readlink	Read the contents of a symbolic link.
realpath	Resolve a pathname.
redraw	Redraw screen.
ref_parm	Create a reference parameter.
refresh	Update the display.
register	Define a variable as being a register.
register_macro	Register a callback procedure.
reload_buffer	Reload the buffer content.
remember	Start remembering keystrokes.
remove	Remove a file.
rename	Rename a file.
replacement	Overload an existing macro definition.
require	Enforce the use of an external module.
reregister_macro	Register a unique callback procedure.
restore_position	Restore a previously saved position.
return	Return from a macro.
returns	Return an expression from a macro.
right	Move position right one character.
rindex	Search string for a rightmost sub-string or character.
rmdir	Remove directory.
rtrim	Chomp characters from the end of a string.
save_keystroke_macro	Save the current keystroke macro.
save_position	Saves current cursor/buffer state.
screen_dump	Dump an image of the screen.
search_back	Backwards buffer search.
search_case	Set the search pattern case mode.
search_fwd	Buffer search.
search_list	Search list contents.
search_string	Searches for a pattern in a string.
searchpath	Searches for a given file in a specified path.
self_insert	Insert a character as if it was typed.
send_signal	Send signal to a process buffer.
set_attribute	Set the color attributes.
set_backup	Set backup creation mode.
set_backup_option	Set backup options.
set_binary_size	Set binary chunk size.
set_btn2_action	Set the second button action.
set_buffer	Set the current buffer.
set_buffer_cmap	Set a buffers character-map.
set_buffer_flags	Set buffer flags.
set_buffer_title	Set a buffers title.
set_buffer_type	Set the buffer storage type.
set_calling_name	Set the name of the calling macro.
set_char_timeout	Set the escape delay.
set_color	Set screen colors.
set_color_pair	Set a specific color.
set_ctrl_state	Set the state of a window control.
set_echo_format	Set the echo line format.
set_encoding	Set a buffers character encoding.
set_feature	Config an editor feature.
set_file_magic	Define the file type detection rules.
set_font	Set the current window fonts.
set_idle_default	Set idle interval.
set_indent	Set the buffers default indentation.
set_kbd_name	Set the keyboard name.
set_line_flags	Associate line flags.
set_macro_history	Set the macro execution history.
set_margins	Set buffer formatting margins.
set_mouse_action	Set keyboard mouse handler.
set_mouse_type	Sets the mouse type.
set_msg_level	Set level of informational messages.
set_process_position	Set process insertion position.
set_property	Set a dictionary item.
set_ruler	Configure the buffer ruler.
set_scrap_info	Set the scrap buffer details.
set_syntax_flags	Set syntax flags.
set_tab	Derive the buffer tab stops.
set_term_characters	Set terminal special characters.
set_term_feature	Set a terminal attribute.
set_term_features	Define terminal attributes.
set_term_keyboard	Define terminal keyboard definitions.
set_terminator	Set a buffers line terminator.
set_top_left	Manages window view port coordinates.
set_window	Set the active window.
set_window_cmap	Set a windows character-map.
set_window_flags	Set window flags.
set_window_priority	Set the window display priority.
set_wm_name	Set the window and/or icon name.
shell	Spawn a sub-shell process.
shift	Shift the first list element.
sin	Sine function.
sinh	Hyperbolic sine function.
sleep	Suspend execution for an interval of time.
sort_buffer	Sort buffer content.
sort_list	Sort list.
spell_buffer	Spell the specified buffer.
spell_control	Spell control.
spell_dictionary	Spell dictionary modifications.
spell_distance	Edit distance.
spell_string	Spell the specified word or line.
spell_suggest	Suggest spelling of the the specified word.
splice	Splice a list, removing and/or adding elements.
split	Split a string into tokens.
split_arguments	Argument split.
sprintf	Formatted printing to a string.
sqrt	Square root function.
srand	Seed the random number generator.
sscanf	Read formatted data from string.
stat	Obtain file information.
static	Define a function or module scope.
strcasecmp	String case insensitive compare.
strcasestr	Locate first occurrence of a case insensitive.
strcmp	String compare.
strerror	String error.
strfilecmp	Filename comparison.
strftime	Format time and date.
string	Declare a string symbol.
string_count	Count occurrences of characters in a string.
strlen	String length.
strnlen	String length limited to an explicit maximum.
strpbrk	Search a string for any of a set of characters.
strpop	Pop the leading character(s).
strrstr	Locate last occurrence of a sub-string.
strsignal	Return string describing signal.
strstr	Locate first occurrence of a sub-string.
strtod	String to double.
strtof	String to float.
strtol	Convert a string into its numeric value.
strverscmp	Version string compare.
substr	Extract a sub-string.
suspend	Suspend current process.
swap_anchor	Swaps the mark with the current position.
switch	Switch statement.
symlink	Create a symbolic link.
syntax_build	Build a syntax hiliting engine.
syntax_column_ruler	Column syntax coloriser.
syntax_rule	Define a syntax hilite rule.
syntax_token	Define a syntax token.
tabs	Set buffer tab stops.
tagdb_close	Tag database close.
tagdb_open	Tag database open.
tagdb_search	Tag database search.
tan	Tangent function.
tanh	Hyperbolic tangent function.
throw	Throw an exception.
time	Get the current system time.
tokenize	Tokenize a string into token elements.
top_of_buffer	Move cursor to start of current buffer.
top_of_window	Goto top of the current window.
transfer	Buffer to buffer transfer.
translate	Buffer search and replace.
translate_pos	Convert window coordinates.
trim	Chomp characters from a string.
typeof	Determine the symbol type.
umask	Set and get the file mode creation mask.
uname	Retrieve system information.
undo	Undo previous edit operations.
unlink	Unlink a file.
unregister_macro	Remove a registered macro.
unshift	Shift the first list element.
up	Move position up one line.
upper	Convert string or character to uppercase.
use_local_keyboard	Associate a keyboard with a buffer.
use_tab_char	Configure use of hard/soft tabs.
version	Version information.
vfs_mount	Mount a virtual file-system.
vfs_unmount	Unmount a virtual file-system.
view_screen	View the content of underlying screen.
wait	Wait for attached process to terminate.
wait_for	Wait for process output.
watch	Watch a symbol.
while	while statement.
widget_get	Retrieve a widget attribute.
widget_set	Set a widget attribute.
window_color	Set the window attribute.
write_block	Write selected region.
write_buffer	Write to buffer content.
Functions
!	Not operator.
!=	Non-equality operator.
%	Modulus operator.
%=	Modulus assignment operator.
&	Bitwise AND operator.
&&	Logical AND operator.
&=	Bitwise AND assignment operator.
*	Multiplication operator.
*=	Multiplication assignment operator.
+	Addition operator.
++	Prefix Increment.
+=	Addition assignment operator.
-	Subtraction operator.
--	Prefix Decrement.
-=	Subtraction.
/	Division operator.
/=	Division assignment operator.
<	Less than comparison.
<<	Left-shift operator.
<<=	Left-shift assignment operator.
<=	Less than or equal comparison.
<=>	Comparison operator.
=	Assignment operator.
==	Equality operator.
>	Greater than comparison.
>=	Greater than or equal comparison.
>>	Right-shift operator.
>>=	Right-shift assignment operator.
^	Bitwise exclusive OR operator.
^=	Bitwise exclusive OR assignment operator.
post++	Postfix Increment.
post--	Postfix Decrement.
\|	Bitwise OR operator.
\|=	Bitwise OR assignment operator.
\|\|	Logical OR operator.
~	Bitwise complement.

Macros

__breaksw

__breaksw;

Switch break statement.

Description

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

Note:

The __breaksw() primitive is internal to the macro language. It is generated by the GRIEF macro compiler when a break statement is encountered within a switch statement; it not intended for direct use.

Returns

nothing

__lexicalblock

__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)

Note:

The __lexicalblock() primitive is internal to the macro language. It is generated by the GRIEF macro compiler when nested variable declarations are encountered within block statements. it not intended for direct use.

Returns

nothing

__regress_op

int __regress_op( ... )

Regression operations.

Description

The __regress_op() primitive is an INTERNAL function utilised using system regression testing, providing access to miscellanous system library functions.

Returns

n/a

Warning:

Direct use of __regress_op() is not advised and is only documented for completeness.

Functionality may change or be removed without notice.

Portability

GriefEdit specific, functionality may change without notice.

__regress_replacement

declare __regress_replacement( ... )

Replacment regression testing.

Description

The __regress_replacement() primitive is an internal function utilised by the regress macro to assert replacement macro features.

Returns

n/a

Warning:

Direct use of __regress_replacement() is not advised and is only documented for completeness.

Functionality may change or be removed without notice.

Portability

GriefEdit specific, functionality may change without notice.

abort

void abort()

Abnormal process.

Description

The abort() primitive immediately exits GriefEdit.

Parameters

none

Returns

nothing

Portability

n/a

above

int above( declare expr1,
declare expr2 )

Greater than comparison.

Description

The above() primitive is the functional form of the > operator.

The function yields the comparison of the two arguments expr1 and expr2 which both must be of equivalent types, either numeric or string; which are arithmetic and lexicographically comparisons respectively.

Parameters

expr1	Left expression, numeric or string.
expr2	Right expression, numeric or string.

Returns

The above() primitive yields the value 1 if expr1 is greater then expr2, and 0 if the relation is false.

Limitations

Lists can not be compared.

above_eq

int above_eq( declare expr1,
declare expr2 )

Greater than or equal comparison.

Description

The above_eq() primitive is the functional form of the >= operator.

Parameters

expr1	Left expression, numeric or string.
expr2	Right expression, numeric or string.

Returns

The above_eq() primitive yields the value 1 if expr1 is greater then or equals expr2, and 0 if the relation is false.

abs

int abs( int val )

Absolute value.

Description

The abs() primitive computes the absolute value of an integer.

Returns

Returns the absolute value.

access

int access( string path,
int mode )

Test file accessibility.

Description

The access() primitive is used to check the accessibility of a file. The file parameter is the name of a directory or file which is to be tested and mode are a set of access bits which are used to check the effective access.

When the value of mode is zero, only the existence of the file is verified. The meaning of mode is operating system dependent yet most operating systems support the following definitions:

F_OK	Check if file exists (0).
X_OK	Check to see if file is executable (1).
W_OK	Check if file is writable (2).
R_OK	Check if file is readable (3).

Returns

On successful return this primitive returns >= 0; -1 is returned on an error, and the global variable errno is set to the reason for the failure.

Portability

A GriefEdit extension.

acos

float acos( float x )

Arc cosine.

Description

The acos() primitive shall compute the principal value of the arc cosine of the argument x. The value of x should be in the range [-1,1].

Returns

The acos() primitive on successful completion shall return the arc cosine of xl, in the range [0,pi] radians.

Portability

Result on error are system dependent.

arg_list

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

eval	Optional boolean flag, if true each argument shall be evaluated (e.g. variables are referenced) with the result being retrieved, otherwise the raw value (e.g. variable name) shall be retrieved.
start	Optional integer starting the index of the first argument to be including within the list. If omitted defaults to 1, being the first argument.
end	Optional integer starting the index of the last argument to be including within the list. If omitted defaults to -1, being the last argument.

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.

asin

float asin( float x )

Arc sine.

Description

The asin() primitive shall compute the principal value of the arc sine of the argument x. The value of x should be in the range [-1,1].

Returns

Upon successful completion shall return the arc sine of x, in the range [-pi/2,pi/2] radians.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

assign_to_key

int assign_to_key( [string key],
[string macro] )

Assign command to key or key sequence.

Description

The assign_to_key primitive assigns a key or key sequence to a function.

The key is defined by the string parameter key, which if omitted shall be prompted. key may be specified as either an internal key code, or may be specified by a portable abbreviation, see below.

A key is “unassigned” by assigning the function nothing to the key.

If key evaluates to more than one keystroke, this shall define a multikey sequence, that is more than one key must be pressed to execute the macro. In this case, an internal key code is assigned for the key. This internal key code is returned as the value of this macro. Multikey sequences do not time out between key presses unlike the other internal keys when there is an ambiguity.

Parameters

key	String identifying the particular keystroke that is being assigned.
macro	String containing the command which shall be invoked, which may contain literal integer and/or string arguments to be passed upon the macro upon execution.

Key Sequences

Generally keys are defined using their associated mnemonic possiblity prefixed with one or modifiers enclosed within a set of “<>” brackets, examples.

<F1>
<Ctrl-F1>
<Alt-Ctrl-Up>.

The following are the set of supported modifiers

Shift - Key Shift, for example a to Z.
Ctrl - Control Key.
Alt - Alt Key.
Meta - Alias for Alt.
Keypad - Keypad key variate.

In the case of simple ASCII keys their character value can be used, for example “a”.

In addition to a mnemonic “<xxx>” or ASCII “x” syntax additional alternative forms and special characters are supported.

#xxx	Substitutes the # lead sequence of digits with the represent value. For example #123 result in the key code 123.
^x	The ^ characters treats the following character as a control code, For example ^a, is control-a.
\	The \ character escapes the next character, removing any special meaning.

When it is required to state any of the special characters “<, >, %, # or ^” these can be referenced using their escaped form, example “\\<”.

The following table details the supported key sequence encoding and suitable modifiers; all names are matched case insensitive.

For examples review current supplied macro code.

Key	Description	Keypad	Shift	Ctrl	Alt	Meta
ASCII	ASCII key		x	x	x	x
F1..F12	Function keys		x	x	x	x
PgDn	Page Down
PgUp	Page Up
Left	Cursor Left	x	x	x	x
Right	Cursor Right	x	x	x	x
Up	Cursor Up	x	x	x	x
Down	Cursor Down	x	x	x	x
Tab
Back-Tab	Shifted Tab
Backspace
Back
Del	Delete
Enter	Enter/Return Key	x
Esc	Escape key
Space	Space ( )
Home	Cursor Home	x
End	Cursor End	x
Ins	Insert	x
Plus	Plus (+)	x
Minus	Minus (-)	x
Star	Multiply (*)	x
Divide	Div (/)	x
Equals	Equal (=)	x
Cancel	Cancel Key
Command	Command Key
Copy	Copy Key
Cut	Cut Key
Exit	Exit Key
Help	Help Key
Menu	Menu Key
Next	Next Key
Open	Open key
Paste	Paste key
Prev	Prev Key
Prtsc	Print-Screen Key
Redo	Redo Key
Replace	Replace
Save	Save
Scroll	Scroll
Search	Search
Undo	Undo
Keypad-#	Keypad 0..9		x	x	x	x
Grey-#	Aliases for keypad
Button#	Button number #
Button#-Up
Button#-Double
Button#-Motion
Button#-Down
Private#	Private keys
Mouse	Special Mouse Event
Wheel-Up	Mousewheel up movement
wheel-Down	Mousewheel down

Returns

The assign_to_key returns the key value assigned to sequence, otherwise -1 if the key sequence is invalid or the operation aborted.

Portability

n/a

atan

float atan( float x )

Arctangent.

Description

The atan() primitive calculates the arctangent of x.

Returns

Returns a value in the range -pi/2 to pi/2 radians.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

Description

The atan2() primitive calculate the arctangent (inverse tangent) of the operand division y/x.

Returns

The atan2() primitive returns a value in the range -pi to pi radians. If both arguments of atan2() are zero, the function sets errno to EDOM, and returns 0. If the correct value would cause underflow, zero is returned and the value ERANGE is stored in errno.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

atoi

int atoi( string str,
[int svalue = TRUE] )

Convert string to a decimal number.

Description

The atoi() primitive converts the initial portion of the string str into its numeric value. This behaviour is equivalent to using strtol as follows.

val = strtol(str, NULL, 10);

Optionally atoi if svalue is specified and zero then the ascii value of the first character in string is returned. This behaviour is equivalent to using characterat as follows.

val = characterat(str, 1);

Parameters

str	String object.
svalue	Optional flag, when stated as FALSE only the value of the leading character is returned.

Returns

The atoi function returns integer value of argument string treated as an ascii number or the ascii value of the first character in string if svalue is zero.

Portability

A GriefEdit extension.

attach_buffer

void attach_buffer( int bufnum )

Attach a buffer to a window.

Description

The attach_buffer() primitive attaches the specified buffer to the current window, so that the window becomes a view port into the buffer content.

This interface is generally used in combination with set_buffer, set_window and/or buffer/window creation. Care should be taken to always have both the current buffer attached to the current window at end of any macros returning control backup, otherwise results are undefined.

For example, create a buffer and window and then associate the two.

int buf = create_buffer("buffer);
int win = create_window(20, 10, 60, 2);
attach_buffer(buf);

When the specified buffer is attached to the current window, the top title of the window is changed to reflect the buffer or file-name associated with the buffer.

Parameters

bufnum

Buffer identifier to be attached.

Notes

A few events automatically affect the attached buffer.

An explicit attach_buffer() is performed during create_tiled_window calls.
Deleting an attached buffer, results in all associated windows being reassigned the top buffer.

Returns

nothing

Portability

n/a

attach_syntax

int attach_syntax( int|string syntable )

Attach a syntax to a buffer.

Description

The attach_syntax() primitive associates the current buffer with the syntax table specified by the name table.

Until another syntax table is associated with the buffer, the syntax table syntable shall be used in all operations that require a syntax; these include parenthesis matching and spell-checks.

Parameters

syntable

Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The attach_syntax() primitive returns the syntax identifier associated with the attached syntax table, otherwise -1 if table did not exist.

On invalid table reference errors the following diagnostics message(s) shall be echoed on the command prompt.

syntax: table 'xxx' undefined.

syntax: no current table.

Portability

A GriefEdit extension.

autoload

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

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

filename	String that contains the name of the compiled macro file.
function	String containing the name of the macro function.
...	Additional macro function names.

Returns

nothing

Portability

n/a

backspace

void backspace( [int num = 1] )

Delete character to the left of the cursor.

Description

The backspace() primitive moves the cursor and deletes the character to the left of the cursor in the current buffer.

The actions of backspace are dependent on the current insert mode.

Insert Mode

If insert mode backspaces moves the cursor and deletes the previous character, all characters to the right move one character to the left.

If the cursor is at the beginning of the line then the current line is appended to the end of the previous line.

Overtype Mode

If overstrike mode backspaces moves the cursor and deletes the previous character, replacing it with a space.

If the previous character is a tab, it moves over virtual spaces between the current position and the tab character when moving back.

If the cursor is at the beginning of the line then the cursor is moved to end of the previous line.

Parameters

num	Optional integer, if stated specifies the number of characters the cursor to be moved backwards, if omitted only a single character position is moved.

Returns

The backspace() primitive returns non-zero if successful impling the cursor moved, otherwise zero.

Portability

The num option is a GriefEdit extension.

basename

int basename( string pathname,
[string suffix] )

Return the last component of a pathname.

Description

The basename() primitive returns a string containing the final component of a pathname contained in the string path argument, deleting trailing path separators.

To accomplish this, basename first checks to see if name consists of nothing. but slash (/) or backslash (\) characters. If so, basename replaces name with a single slash and the process is complete. If not, basename removes any trailing slashes. If slashes still remain, basename strips off all leading characters up to and including the final slash.

If you specify suffix and the remaining portion of name contains a suffix which matches suffix, basename removes that suffix.

Returns

The basename() primitive returns a string containing the final component of the specified pathname after processing following the above rules.

beep

int beep( [int freq],
[int duration] )

Issue a beep sound.

Description

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.

Parameters

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.

Returns

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

Portability

A GriefEdit extension.

beginning_of_line

int beginning_of_line()

Goto beginning of line.

Description

The beginning_of_line() primitive moves the buffer cursor to the first character of the current line.

Parameters

none

Returns

The beginning_of_line() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

below

int below( declare expr1,
declare expr2 )

Less than comparison.

Description

The below() primitive is the functional form of the < operator.

Parameters

expr1	Left expression, numeric or string.
expr2	Right expression, numeric or string.

Returns

The below() primitive yields the value 1 if expr1 is less than expr2, and 0 if the relation is false.

Limitations

Lists can not be compared.

below_eq

int below_eq( declare expr1,
declare expr2 )

Less than or equal comparison.

Description

The below_eq() primitive is the functional form of the <= operator.

Parameters

expr1	Left expression, numeric or string.
expr2	Right expression, numeric or string.

Returns

The below_eq() primitive yields the value 1 if expr1 is less then or equals expr2, and 0 if the relation is false.

Limitations

Lists can not be compared.

bless

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.

Note:

Consider always blessing objects in classname’s that are mixed case, using a leading upper-case; Namespaces with all lowercase names are considered reserved for GRIEF pragmata.

Parameters

n/a

Returns

The bless statement returns the dictionary identifier.

Portability

A GriefEdit extension.

bookmark_list

list bookmark_list()

Retrieve existing bookmark list.

Description

The bookmark_list() primitive creates a list containing all currently defined bookmarks. For each definition the list shall contain a 4 integer record representing the bookmark as follows:

{ bookid, bufnum, line, column }

bookid - Bookmark identifier.
bufnum - buffer number.
line - buffer line number.
column - buffer column number.

If no bookmarks exist then a NULL list shall be returned.

Parameters

none

Returns

The bookmark_list() primitive returns a list containing the bookmark definitions otherwise NULL if no bookmarks exist.

Portability

n/a

borders

int borders( [int borders] )

Set window border status.

Description

The borders() primitive either sets or toggles the tiled window border status.

Disabling borders can improve display performance on slow systems, yet shall disable scroll bars, title bars and may make working with multiple windows difficult.

Parameters

borders

An optional integer stated on (1) or off (0). If omitted, the current value is toggled. A value of -1, acts the same as inq_borders() only returning the current status without effecting any change.

Returns

An integer boolean value representing the previous border state.

Portability

n/a

break

break;

break statement.

Description

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

Returns

nothing

call_registered_macro

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

type	Event type to be invoked.

Returns

The call_registered_macro returns nothing.

Portability

The set of available events differ between systems.

car

declare car( list lst )

Retrieve the first list element.

Description

The car() primitive retrieves a copy of the first element (also known as an atom) in the list lst; effectively removing all elements after the first.

car is non-destructive. It does not remove any elements from the source list only returning a copy of what is the first element, as such the source list is unchanged.

Note:

As lists may contain any data type, it is advised to assigned the result to a polymorphic variable, so that its type can be ascertained.

Example

TODO

Returns

The car() primitive returns value of the first element from the source.

Like cdr, the car primitive is built on their Lisp counter parts, which are also non-destructive; that is, neither modify or change lists to which they are applied.

Portability

n/a

cd

int cd( [string dir] )

Change directory.

Description

The cd() primitive changes the current directory on the specified drive to the specified path. Unlike chdir shell expansion shall occur when the path contains special characters, expanding home references ~, wild cards and environment variables.

cd(newdir);

Under DOS/WIN32, if no drive is specified in path then the current drive is assumed. The path can be either relative to the current directory on the specified drive or it can be an absolute path name

If dir is omitted, the current directory shall be echoed on the command prompt without effecting any change.

cd();

Returns

The cd() primitive returns 1 if successful otherwise zero on error. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

cdr

list cdr( list lst )

Retrieve all secondary list elements.

Description

The cdr() primitive retrieves a copy of everything but the first element (also known as an atom) in the list lst; effectively removing the first element.

cdr is non-destructive. It does not remove any elements from the source list only returning a copy of what are the second and subsequent elements, as such the source list is unchanged.

Note:

The primitives car and cdr can be utilised to manipulate all elements on a list. However, it is more efficient to use nth, pop, splice to extract individual elements, since internally it avoids having to copy sub-lists.

Example

TODO

Returns

The cdr() primitive returns a list containing the second and subsequent elements from the source.

Like car, the cdr primitive is built on their Lisp counter parts, which also non-destructive; that is, neither modify or change lists to which they are applied.

Portability

n/a

ceil

float ceil( float x )

Round up to integral value.

Description

The ceil() primitive computes the smallest integer that is greater than or equal to x.

Returns

Returns the calculated value as a double, float, or long double value.

If there is an overflow, the function sets errno to ERANGE and returns HUGE_VAL.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

cftime

string cftime( string format,
int time )

Format time and date.

Description

The cftime() primitive is an alternative interface to strftime.

Returns

The cftime function returns a string containing the formatted time and date.

Portability

Provided for CRiSP ™ compatility, see strftime.

change_window

void change_window( [int direction],
[string message] )

Selects a new window.

Description

The change_window() primitive selects an adjoining window as the current located in the specified direction identified as follows,

0	Above/up.
1	Right.
2	Below/down.
3	Left.

If direction is omitted the user is prompted; the user indicates the change direction by use of the arrow keys.

Change direction [<^V>]

If the selected edge has no other window associated, then the user is informed as follows:

No window available

Parameters

direction	Optional integer direction stating the edge on which the change operation occurs resizing the associated window (as above), if omitted the user is prompted.
message	Optional message string to be used as the prompt, if omitted the default of “Change direction” is used.

Returns

The change_window() primitive returns 1 on success, 0 if the edge does exist, otherwise -1 if the user aborted.

Portability

n/a

change_window_pos

int change_window_pos( [int topx],
[int topy],
[int width],
[int height],
[int winnum] )

Modify window coordinates/size.

Description

The change_window_pos() primitive modifies the coordinates and/or the size of the specified window, if omitted the current window.

Note, care must be taken not position a window outside the physical window otherwise unexpected results including application crashes may result.

Parameters

topx	Optional integer, if stated sets the x coordinate of the top left corner of the window, otherwise the current coordinate is taken.
topy	Optional integer, if stated sets the y coordinate of the top left corner of the window, otherwise the current coordinate is taken.
width	Optional integer, if stated sets the new advised width in columns; the resulting width shall not be permitted to be smaller then the required width to display the current window title and/or message content.
height	Optional integer, if stated sets the new advised height in lines.
winnum	Optional window identifier, if omitted the current window shall be referenced.

Returns

Returns non-zero if the windows coordinates were modified, otherwise zero if an error occurred.

To determine the resulting window coordinates and size the inq_window_info primitive should be used, since boundary logic may have resized the window in order to obey the limits of the physical display.

Portability

The winnum is a GriefEdit extension.

characterat

int characterat( string str,
int index )

Retrieve the character value within a string.

Description

The characterat function returns the character value within the string str located at the specified position index starting at offset one.

Parameters

str	String object to be searched.
index	Character index, starting from on offset of 1 being the first character.

Return

Character value as an integer, otherwise -1.

Portability

A GriefEdit extension.

chdir

int chdir( string path )

Change directory.

Description

The chdir() primitive changes the current directory on the specified drive to the specified path.

Unlike cd no shell expansion shall occur.

Returns

The chdir() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

chmod

int chmod( string path,
int mode )

Change mode.

Description

The chmod() primitive changes the permissions for a file specified by path to be the settings in the mode given by permission.

The access permissions for the file or directory are specified as a combination of bits which are operating system specific.

Returns

The chmod() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

chown

int chown( string path,
int owner,
int group )

Change owner.

Description

The chown() primitive is reserved for future use.

Returns

The chown() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

close_window

void close_window( [int winum] )

Close specified the window.

Description

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

The close_window() primitive closes the specified window winum. The adjoining windows are enlarged to take up the space along the best fit border.

The best fit border is the one that has a set of windows exactly matching the border of the window being closed. If there is more than one, the left is eliminated first, then right, bottom and top. The top left window becomes current.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

none

Portability

Not implemented.

color

int color( [int background],
[int normal],
[int selected],
[int message],
[int error],
[int hilite],
[int hilite_fg],
... )

Set the basic colors.

Description

The color() primitive configures the standard color attributes. color is only intended for use with the basic color set and is provided only for backward compatibility.

If background is omitted, all colors shall be prompted. Colors are numeric values in the range 0..15 or their symbolic name as follows:

Basic Colors

Value	Name	Value	Name
0	Black	8	Dark-grey
1	Blue	9	Bright-blue
2	Green	10	Bright-green
3	Cyan	11	Bright-cyan
4	Red	12	Bright-red
5	Magenta	13	Bright-magent
6	Brown	14	Yellow
7	White	15	bright-white

Additional colors maybe modified, yet would advice only the use of symbolic color names and not color values to avoid issues when dealing with terminals which support greater then 16 colors.

The alternative interfaces of set_color and set_color_pair are the preferred interfaces for new macros.

Parameters

background	The background color.
normal	The normal text color.
selected	Highlighting color for the selected window title.
message	The color for normal messages.
error	The color for error messages.
hilite	Color of marked areas. The value either states both the foreground and background of the marked areas as high nibble is background and the low is foreground. Unless hilite_fg is stated in which case only the foreground.
hilite_fg	Foreground color of marked areas.

Returns

The color() primitive returns 1 on success, otherwise 0 if one or more of the colors is invalid.

Example

Set the background color to blue and the foreground color to white, and active window title to bright cyan.

color(1, 7, 11);

Portability

Colors definitions beyond frame are system dependent.

color_index

int color_index( [int index] )

Border color background color index.

Description

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.

Parameters

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

Returns the previous value of the color index.

Portability

A GriefEdit extension.

command_list

list command_list( [int nomacros = FALSE],
[string pattern] )

Retrieve list of built-in and active macros.

Description

The command_list() primitive returns a sorted list of all built-in primitives and the optionally all currently defined macros.

If nomacros is non-zero only built-in primitives are retrieved. otherwise the list includes all macros and command primitives.

The optional pattern is a regular expression similar to that accepted by the command line shells (See: file_match), providing an inclusion filter.

Parameters

nomacros	Optional boolean value, if stated as true then only built-ins primitives are retrieved, filtering any run-time loaded macros.
pattern	Optional string value containing the macro-name pattern to be applied against each name, only returning the matching. A macro-name expression is a shell style regular expression (See: file_match) (e.g. * for wildcard, ? for wild-character, and [..] to select a range of characters).

Returns

The command_list() primitive returns a list of strings each containing the name of a primitive or macro.

Portability

n/a

compare

int compare( expr1,
expr2 )

Comparison.

Description

The compare() primitive is the functional form of the <=> operator.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The compare() primitive yields the value -1 if the first expression is less then the second, 0 if the equals, and 1 the greater than; which are arithmetic and lexicographically comparisons respectively.

Limitations

Lists can not be compared.

compare_files

int compare_files( [int flags],
string file1,
string file2 )

Binary file compare.

Description

The compare_files performs simple comparison byte-for-byte of the on disk images of the two file file1 and file2.

The flags are intended for future options, supporting simple line processing.

It can be used to quickly determine if two files are identical (byte for byte). Note that if either file is an active buffer, no unsaved changes shall be included.

In contrast, the <diff_buffers> primitive is used to compare files and mark up the differences.

Returns

Returns 1 if the files are identical, 0 if they differ. -1 if the first file cannot be read, -2 if the second file cannot be read.

Portability

A GriefEdit extension.

compress

string compress(
    string str,
    [int trim = FALSE],
    [string chars = " \\t\\r\\n"],
    [int replacement = ' ']
)

Compress repeated instances of white-space characters.

Description

The compress() primitive takes a string and removes all multiple white space characters, by converting consecutive white-space characters into a single white-space character.

The default is to compress all tabs, spaces and newline characters. If trimchars is specified, then all characters within the trimchar string are compressed.

If trim is specified then compress() acts the same as

trim(compress(str,trimchars),trimchars)

Parameters

str	String object to be compressed.
trim	Optional flag, when TRUE invokes trim on the compressed result.
chars	Optional string defining the set to characters be to compressed and optionally trimmed.
replacement	Optional replacement character, if given as a non-positive (<= 0) value when the first character with the consecutive set shall be used.

Returns

Returns a copy of string with all spaces, tabs and newlines mapped to single spaces.

Portability

The chars and replacement options are a GriefEdit extensions.

By default BRIEF preserved the first character in every group of compressed characters, whereas GriefEdit replaces them with a single space; unless replacement is stated as a non-positive number (e.g. -1).

connect

int connect( int mode,
string shell = NULL,
string cwd = NULL )

Attach a process to a process.

Description

The connect() primitive creates a sub-process and attaches it to the current buffer. The buffer behaviour is similar to that of a virtual terminal with the sub-process standard input and output streams redirected to the buffer. The virtual terminal implementation is system dependent yet most utilise pseudo-devices otherwise pipes.

All text inserted into the buffer is automatically forwarded to the underlying sub-process, insertion methods include self_insert, insert and paste. In addition the primitive insert_process allows for explicit text to be forwarded without echo.

Likewise output from the underlying sub-process is sent to the buffer. All output from the sub-process is automatically inserted into the buffer, at the process insertion position; see inq_process_position and set_process_position.

The mode argument specifies the control flags the behaviour of the connection, if omitted defaults to PF_ECHO.

By default, the process created is a shell process, and the shell is got from the SHELL environment variable. If shell is specified, then it is taken as the pathname of a shell to execute.

Once attached connect() may be called to change the mode flag.

Modes

Control flags

Constant	Value	Description
PF_ECHO	0x0001	Reserved for macro use, denotes all typed key strokes are redirected to the process using a REG_TYPE signal handler (See: register_macro).
PF_NOINSERT	0x0002	Reserved for macro compatibility, disables automatic insertion of sub-process output into the associated buffer; not implemented.
PF_NONINTERACTIVE	0x0004	Non-interactive mode command shell.
PF_LOCALECHO	0x1000	Local echo mode, characters written to the buffer using either insert or self_insert shall be automatically sent to the process.
PF_OVERWRITE	0x4000	Overwrite process input (CR/LF conversion). Indicates whether output from a process overwrites text in the buffer or inserts and shifts text over as it does so. Needed for effectively allow type-ahead to not be destroyed but allow escape sequences to cause data in the buffer to be overwritten when running termcap oriented programs.
PF_WAITING	0x8000	Waiting for text. Normally when a buffer is created, the output from the subprocess is inserted directly into the buffer. Setting this bit causes the output from the process to be held onto, until the calling macro issues a wait or wait_for.

Parameters

mode	Optional integer control flags.
shell	Optional string containing the SHELL specification is be utilised, if omitted the environment value of SHELL is used.
cwd	Optional string containing current working directory.

Returns

The connect() primitive returns the positive IP identifier associated identifier with the created connection, 0 if the buffer is already connected, otherwise -1 on error.

Portability

n/a

const

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.

continue

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

copy

int copy( [int append = FALSE],
[int keep = FALSE] )

Copy marked area to scrap.

Description

The copy() primitive copies the content of the currently marked region to the scrap buffer, and releases the marked region on completion.

Parameters

append	Optional integer, if non-zero the copied region shall be appended to the scrap instead of replacing the scrap content.
keep	Optional integer, if non-zero the marked region is retained otherwise the anchor is released.

Returns

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

Portability

n/a

copy_keyboard

int copy_keyboard( int kbdid,
[string cmd ...] )

Copy a keyboard.

Description

The copy_keyboard() primitive copies the key bindings associated with the keyboard identifier kbdid. The keyboard is either copied in its entirety or optionally the subset of key bindings associated with the specified list of commands cmd.

The primary use of this primitive is to obtain an explicit subset of a full keyboard for a specific use; for example a keyboard to be used by an popup for a special editing window. Another way of thinking, it a macro can inherit a keyboard, modify and then utilise locally without knowledge of the callers keyboard bindings.

Parameters

kbdbid	Keyboard identifier.
...	Optional list of command names whose key assignments should be duplicated in the current keyboard. If no commands are given, then this just creates a duplicate keyboard.

Returns

The copy_keyboard() primitive returns the Keyboard identifier of the new keyboard. On error 0 is returned if the commands given are not found.

Portability

n/a

copy_screen

void copy_screen()

Copy the current screen.

Description

The copy_screen() primitive exports an image of the current editor windows to the current buffer.

Parameters

none

Returns

nothing

Portability

A GriefEdit extension; this primitive is subject for removal, and has been removed from recent CrispEdit™ releases.

cos

float cos( float x )

Cosine.

Description

The cos() primitive calculates the cosine of x. The value x is expressed in radians.

Returns

Returns the calculated value.

If x is outside prescribed limits, the value is not calculated. Instead, the function returns 0 and sets the errno to ERANGE.

If the correct value would cause an underflow, zero is returned and the value ERANGE is stored in errno.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

cosh

float cosh( float x )

Hyperbolic cosine.

Description

The cosh() primitive calculates the hyperbolic cosine of x. The value x is expressed in radians.

Returns

Returns the calculated value.

If the result overflows, the function returns +HUGE_VAL and sets errno to ERANGE.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

create_buffer

int create_buffer( string bufname,
[string filename],
[int sysflag = FALSE],
[int editflags = 0],
[string encoding = ""] )

Create and load a buffer.

Description

The create_buffer() primitive creates a buffer containing the content of an optional underlying file filename, with the filename being ae full or relative path name of a file which should be read into the buffer. If this parameter is omitted, then an initially empty buffer will be created.

The buffer name bufname should be unique, and if the buffer already exists a unique name shall be derived by prefixing its name with “ [x]”; x being the next available unique sequence.

The optional arguments sysflag, editflags and encoding control a variety of the buffer features.

Callbacks

Upon buffer loads firstly the _extension callback is executed and either an extension specific callback of the form _ext or _default shall be executed.

In addition any related register_macro callbacks are executed.

Example

The following creates the buffer named “Read-Me” and populates it with the content of the file “readme.txt”.

int buf;

if ((buf = create_buffer("Read-Me", "readme.txt")) >= 0) {
    attach_buffer(newbuf);
    return buf;
}
message("error loading buffer ...");
return -1;

Parameters

bufname	String containing the unique buffer name. The name is used as the buffer title, which is usually the same as the underlying filename yet it need not be; for example an abbreviated form. The buffer names does not affect the file that shall be loaded into the buffer.
filename	Optional string containing the file that the buffer should contain, if omitted an empty buffer is created.
sysflag	Optional integer boolean flag stating whether or not the buffer is a system buffer, FALSE for non-system otherwise TRUE for system; if omitted the buffer is assumed to be a non-system. See inq_system is more details on system buffers.
editflags	Optional buffer creation flags. These flags control the file mode, see the edit_file primitive for additional information describing this field.
encoding	Optional buffer encoding hint.

Returns

The create_buffer() primitive returns the buffer identifier associated with the newly created buffer, otherwise -1 if the buffer was not created.

Note the buffer does not become the current buffer until the set_buffer primitive is used against the returned buffer identifier.

Portability

n/a

create_char_map

int create_char_map( [int mapid|string name],
[int start = 0],
[list chars],
[list flags],
[string name] )

Create a display character-map.

Description

The create_char_map() primitive either creates or updates an existing character-map. Character-map’s determine the mapping between the buffer encoding, special purpose characters and their display representation.

A map represents each of the 256 possible byte values which may be contained within any given 8-byte encoded buffer. In addition to the 256 base characters a number of special markers for End-Of-Line, Tabs and End-Of-File may also be defined.

The identifier mapid or the alias name either references an existing map or if omitted a new map shall be generated. On creation a character-map is derived from the system “normal” map.

Upon the existing or created map the specified chars list is then applied starting at the character start, updating each character in sequence until the end of the list is encountered. Optionally the pairs of integer values contained within the flags list are then applied in the same manor. If specified, the character-maps alias is changed to name.

Character-map Names

By default two system predefined character-map’s are available known by the names “normal” and “binary”, these are in addition to the number managed by the view’s package; care should be taken not to overwrite these resources prior to understanding the impact.

Special Characters

The follow special character indexes have importance when displaying buffer content and can be controlled using create_char_map for example.

create_char_map("literal", CMAP_EOF, quote_list("[EOF]"));

Constant	Value	Description
CMAP_TABSTART	-	Beginning of a Tab
CMAP_TABVIRTUAL	-	Tab body
CMAP_TABEND	-	Tab end
CMAP_EOL	-	End-of-line marker
CMAP_EOF	-	End-of-file marker

By default, all specials are simple spaces as such invisible.

Note, for CRiSP ™ compatibility the char list may reference 257 characters with the 257th entry being equivalent to CMAP_EOL.

Character Flags

The flags argument should be given as a set of one or more integer pairs:

{ <character>, <flag> }

The character flags available include, with one

Constant	Value	Description
CMAP_DEFAULT	0	Default
CMAP_TAB	1	Horizontal tab
CMAP_BACKSPACE	2	Backspace
CMAP_ESCAPE	3	ESCAPE character

Normal Character Map

The “normal” or default character-map is built using the rules below.

control-characters - ^[A-Z] in ASCII, otherwise use of UNICODE 0x2400-0x241F C0 character range.
DEL - ^? otherwise UNICODE 0x2421.
printable - all characters below 0x80 are themselves, otherwise characters above if 8bit and not 0xff or UNICODE.
non-printable - hexadecimal representation of the form 0x##.

Parameters

mapid, name	Character-map reference, being either an integer map identifier or the associated map name as a string. If omitted a unique identifier shall be allocated.
start	Optional integer, stating the first character index.
chars	Character definition list, being a list of integer and/or string values for each character in the sequence starting at the offset start.
flags	Character flag list, being one or more pairs of integer values. Within each pair, The first element is the integer character position, and the second is the integer flag value from the set “Character Flags”.
name	Optional string, being the unique name by which the character-map may be referenced.

Returns

The create_char_map() primitive returns the identifier of the resolved or created character-map otherwise -1 if the specified character map does not exist.

Example

The following enables an ASCII representation for control characters 0 to 31.

int map =
    create_char_map(0, NULL,
            quote_list(
            "<NUL>", "<SOH>", "<STX>", "<ETX>",
            "<EOT>", "<ENQ>", "<ACK>", "<BEL>",
            "<BS>",  "<HT>",  "<NL>",  "<VT>",
            "<FF>",  "<CR>",  "<SO>",  "<SI>",
            "<DLE>", "<DC1>", "<DC2>", "<DC3>",
            "<DC4>", "<NAK>", "<SYN>", "<ETB>",
            "<CAN>", "<EM>",  "<SUB>", "<ESC>",
            "<FS>",  "<GS>",  "<RS>",  "<US>"),
        quote_list('\t', CMAP_TAB));
set_buffer_cmap(map);

Portability

n/a

create_dictionary

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

name	Optional string containing the unique dictionary name, if omitted the dictionary shall be unnamed.
size	Optional position integer specifying the size of the underlying table.
factor	Optional position integer specifying the table fill factor.

Returns

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

Portability

A GriefEdit extension.

create_edge

int create_edge( [int direction] )

Create an edge, splitting the window.

Description

The create_edge() primitive creates a new edge, splitting the current window in half resulting in a new window.

The window local in the specified direction is split identified as follows,

0	Above/up.
1	Right.
2	Below/down.
3	Left.

If direction is omitted the user is prompted for the split direction; the user indicates the split direction by use of the arrow keys.

Select new side [<^v>]

The selected window edge should have suitable screen space to permit the split operation otherwise the request is ignored and the user is informed as follows:

Window would be too small.

Parameters

direction

Optional integer direction stating the edge on which the split operation occurs creating the new window (as above), if omitted the user is prompted.

Returns

The create_edge() primitive returns 1 on success, 0 if the window was too small too split, otherwise -1 if the user aborted.

Portability

n/a

create_menu_window

int create_menu_window( [int create] )

Create the menu window.

Description

The create_menu_window() primitive retrieves and optionally creates the menu if not already created. The menu resource is a singleton being the top line of display.

Parameters

create

Optional integer flag, if specified as non-zero and the menu resource has as yet to be created, it shall be built.

Returns

Returns the unique identifier of the menu window resource, otherwise -1 if the menu has yet to be created.

Portability

A GriefEdit extension.

create_nested_buffer

int create_nested_buffer( string bufname,
[string filename],
[int sysflag],
[int editflags],
[string encoding] )

Create or reference a buffer.

Description

The create_nested_buffer() primitive is similar to the create_buffer primitive yet if the buffer already exists its reference counter is incremented.

For each nested buffer increment delete_buffer must be called, with the buffer only being removed upon the reference count being zero.

This primitive but is provided for convenience when temporary access to a buffer is required, see the ff macro for a working example.

Parameters

bufname	String containing the unique buffer name. The name is used as the buffer title, which is usually the same as the underlying filename yet it need not be; for example an abbreviated form. The buffer names does not affect the file that shall be loaded into the buffer.
filename	Optional string containing the file that the buffer should contain, if omitted an empty buffer is created.
sysflag	Optional integer boolean flag stating whether or not the buffer is a system buffer, FALSE for non-system otherwise TRUE for system; if omitted the buffer is assumed to be a non-system. See inq_system is more details on system buffers.
editflags	Optional buffer creation flags. These flags control the file mode, see the edit_file primitive for additional information describing this field.
encoding	Optional buffer encoding hint.

Returns

The create_nested_buffer() primitive returns the buffer identifier associated with the newly created buffer, otherwise -1 if the buffer was not created.

Portability

n/a

create_syntax

int create_syntax( string table )

Syntax table creation.

Description

The create_syntax primitive creates a new syntax table with the name specified by table. If the table already exists, the existing table shall be reinitialised.

Parameters

table

Unique syntaxtable name.

Returns

The create_syntax primitive returns the syntax identifier associated with the syntax table, otherwise -1 if the syntax could not be created.

Portability

A GriefEdit extension.

create_tiled_window

int create_tiled_window( int lx,
int by,
int rx,
int ty,
[int bufnum] )

Creates a tiled window.

Description

The create_tiled_window() primitive creates a tiled window. The stated coordinates (lx, by, rx and ty) represent the total window arena irrespective of the borders status, with (0, 0) being the top left hand corner of the screen.

Care should be taken not to overlay tiled windows and that all of the visible display has been assigned to window.

Generally tiled windows are created by the end user splitting the editor windows. This primitive in primary utilised during state restoration to recover the state of the previous edit session.

The created window shall not be visible until the display has been enabled using display_windows.

Parameters

lx	Coordinate of the left edge.
by	Coordinate of the bottom edge.
rx	Coordinate of the right edge.
ty	Coordinate of the top edge.
bufnum	Optional buffer identifier to be attached to the newly create window, see attach_buffer.

Returns

Returns the unique identifier of the new window.

Portability

n/a

create_window

int create_window( int lx,
int by,
int rx,
int ty,
[string message] )

Create a popup window.

Description

The create_window() primitive creates a popup window resource which shall become the current window. The window should be suitability sized based on the current screen size, which can be determined using inq_screen_size.

Popup windows stack upon any underlying tiled or other popup which are located in the same position, the order may be controlled using set_window_priority,

On completion at buffer needs to be associated with the newly created window using attach_buffer.

Parameters

lx	Coordinate of the left edge.
by	Coordinate of the bottom edge.
rx	Coordinate of the right edge.
ty	Coordinate of the top edge.
message	Optional string containing the message which shall be displayed on the bottom frame.

Returns

Returns the unique identifier of the new window.

Portability

Unlike BRIEF the number of windows which may be active at any one time is only limit by system resources.

cursor

int cursor( int state )

Control cursor display.

Description

The cursor() primitive controls whether the cursor is visible, by default the cursor is enabled.

The cursor visibility is set to state with a non-zero value enabling and a zero value disabling, if omitted then the current value is toggled.

Parameters

state

Optional boolean cursor status, if omitted the current status is toggled.

Returns

The cursor() primitive returns 0 on success, otherwise non-zero.

Portability

A GriefEdit extension.

cut

int cut( [int append = FALSE],
[int syscopy = FALSE] )

Cut marked area to scrap.

Description

The cut() primitive moves the content of the currently marked region to the scrap buffer, and releases the marked region on completion.

Parameters

append	Optional integer, if non-zero the copied region shall be appended to the scrap instead of replacing the scrap content.
keep	Optional integer, if non-zero the marked region is retained otherwise the anchor is released.

Returns

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

Portability

n/a

cvt_to_object

declare cvt_to_object( string value,
[int &length] )

Convert string to object.

Description

The cvt_to_object() primitive converts the initial portion of the string specified string value into an underlying int, float or string object.

Firstly, the input string is divided into three parts

An initial, possibly empty, sequence of white-space characters.
Either:
a) A subject sequence interpreted as string of characters enclosed by either single(‘) or double(“) quotes.
b) A subject sequence interpreted as a integer constant represented in some radix determined by the value of base.
c) A subject sequence interpreted as a floating-point constant or representing infinity or NaN.
A final string of one or more unrecognised characters, including the terminating null byte of the input string.

Then they shall attempt to convert the subject sequence to either a string, integer-constant or float-point constant, and return the result.

Integer Values

If the value of base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, or hexadecimal constant, any of which may be preceded by a + or - sign.

A decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits.

An octal constant consists of the prefix 0 optionally followed by a sequence of the digits 0 to 7 only.

A binary constant consists of the prefix 0b or 0B followed by a sequence of the decimal digits 0 or 1.

A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the decimal digits and letters a (or A ) to f (or F ) with values 10 to 15 respectively.

Floating Point Values

A floating-point number should have the form “SI.FESX” containing at least a fractional value or exponent, where

S is the sign; may be “+”, “-”, or omitted.
I is the integer part of the mantissa.
F is the fractional part of the mantissa prefixed with a dot.
X is the exponent.

Either I or F may be omitted, or both. The decimal point isn’t necessary unless F is present.

A character sequence INF or INFINITY, ignoring case, shall be interpreted as an infinity; if representable.

A character sequence NAN shall be interpreted as a quiet NaN, ignoring case, shall be interpreted as an Quiet Not-A-Number; if representable.

Example

int
parsetoken(string line)
{
    declare x;
    int len;

    x = cvt_to_object(line, len);
    switch (typeof(x)) {
    case "integer":   // integer constant.
        break;
    case "float":     // floating point constant.
        break;
    case "string":    // string constant.
        break;
    default:
        // error condition
        break;
    }
    return len;
}

Parameters

value	String value to be parsed.
length	Optional integer variable reference, if specified shall be populated with the number of characters consumed within the source string, including all consumed leading characters, for example white-space. Upon a parse error the populated length shall be 0.

Returns

The cvt_to_object() primitive returns the value of the parsed object converted to the most suitable type, either as an int, float or string type.

Otherwise if the string cannot be parsed NULL is returned.

Portability

n/a

date

int date( [int &year],
[int &month],
[int &day],
[string &monname],
[string &dayname] )

Get current system date.

Description

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”).

Returns

The date function returns the current value of time in seconds since the Epoch which the components represent.

Example

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

debug

int debug( [int flags|string flags|NULL],
[int echo = TRUE] )

Control runtime debug and tracing.

Description

The debug() primitive enables and disables run-time tracing of macros and system acts to the diagnostics log. The new debug flags shall be set to flags.

If flags is omitted, then the current trace mode is toggled from off to DB_TRACE(1) and from on to off.

Otherwise by specifying flags the associated events which shall be traced during subsequent macro operations. Flags can either be one or more DB_XXX constants OR’ed together or string containing a comma seperated list of flag names, see the table below. If the given flag value is either 0 or an empty string, all trace operations are disabled.

The echo flags controls whether the user is informed of the debug state change. When omitted or a non-zero any changes are echoed on the command prompt, informing the user of the new debug status, otherwise the macro is silent.

Flags

The following debug flags are available, enabling tracing of both general and specific macro operations:

Constant	Name	Description
DB_TRACE	trace	General trace.
DB_REGEXP	regexp	Regular expression compilation and execution.
DB_UNDO	undo	Undo/red trace.
DB_FLUSH	flush	Flush output, shall cause the trace log to be flushed on each write; use should be avoided unless catching crash conditions due to associated high cost.
DB_TIME	time	Time stamp which trace log.
DB_TERMINAL	terminal	Terminal interface.
DB_VFS	vfs	Virtual file-system.
DB_NOTRAP	notrap	Disable SIGBUS/SIGSEGV trap handling.
DB_MEMORY	memory	Target specific debug memory service
DB_REFS	refs	Variable references.
DB_PROMPT	prompt	Command prompting.
DB_PURIFY	purify	Running under a memory analysis tool;
DB_HISTORY	history	Command history.

Command lines Options;

The following command option also effect the generation of diagnostics trace.

-d,--log	Enable trace (DB_TRACE)
-f,--flush	Enable log flushing (DB_FLUSH).
--nosig	Disable signal traps (DB_NOSIG).
-P,--dflags=x	Debug/profiling flags x, being a comma separated list of flag names, as defined above.
--rtc	Enable real-time memory checks, if available.
--native	Enable native memory allocator, if suitable.

Diagnostic Log

The default name of the diagnostics log is system dependent

.grief.log	Unix and Unix systems, including Linux.
grief.log	WIN32 and DOS based systems.

Environment Variables

GRIEF_LOG

If the GRIEF_LOG variable exists within the environment then it overrides the default trace log name.

Returns

The debug() primitive returns the value of the debug flags prior to any changes, allowing the caller to restore later.

Example

Enable debug, invoke our macro for testing and then restore the previous flags.

int odebug = debug(1, FALSE);
myfunction();
debug(odebug, FALSE):

Portability

The echo option is a GriefEdit extensions.

debug_support

void debug_support( int what,
declare object,
declare arg )

Internal debugger functionality.

Description

The debug_support() primitive supports GRIEF debug functions.

The primitive is a switcher to the actual sub-functions based upon what, the arguments object and arg are what specific.

Returns

nothing

declare

declare sym1, sym2 ...;

Declare a polymorphic symbol.

Description

The declare statement declares a polymorphic data type.

Returns

nothing

Portability

n/a

define_keywords

void define_keywords( [int|string] keywords,
string words|list words,
[int length],
[int flags],
[int|string syntable] )

Add keywords to a syntax dictionary.

Description

The define_keywords() primitive adds a set of keywords to the specified dictionary, which shall be color syntax highlighted in the associated color with the table specified by table.

Description

keywords	Keyword table identifier, see table below.
words	List of words, otherwise a string that is the concatenation of keywords each being of absolute length characters, optionally comma separated (See: <length>).
length	Length of the keywords. If positive the keyword string is assumed to contain non delimited words of all of same length. Otherwise if given as a negative value, the keyword string is assumed to contain comma separated values of variable length words.
flags	Optional control flags.

SYNF_IGNORECASE	Ignore case.
SYNK_NATCHCASE	Match case.
SYNF_PATTERN	Pattern match (glob style).

syntableOptional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Keyword Tables

Constant	Name	Attribute
SYNK_PRIMARY	primary	ATTR_KEYWORD
SYNK_FUNCTION	function	ATTR_KEYWORD_FUNCTION
SYNK_EXTENSION	extension	ATTR_KEYWORD_EXTENSION
SYNK_TYPE	type	ATTR_KEYWORD_TYPE
SYNK_STORAGECLASS	storageclass	ATTR_KEYWORD_STORAGECLASS
SYNK_DEFINITION	definition	ATTR_KEYWORD_DEFINTION
SYNK_CONDITIONAL	conditional	ATTR_KEYWORD_CONDITIONAL
SYNK_REPEAT	repeat	ATTR_KEYWORD_REPEAT
SYNK_EXCEPTION	exception	ATTR_KEYWORD_EXCEPTION
SYNK_DEBUG	debug	ATTR_KEYWORD_DEBUG
SYNK_LABEL	label	ATTR_KEYWORD_LABE
SYNK_STRUCTURE	structure	ATTR_KEYWORD_STRUCTURE
SYNK_TYPEDEF	typedef	ATTR_KEYWORD_TYPEDEF
SYNK_CONSTANT	constant	ATTR_CONSTANT
SYNK_OPERATOR	operator	ATTR_OPERATOR
SYNK_BOOLEAN	boolean	ATTR_BOOLEAN
SYNK_PREPROCESSOR	preprocessor	ATTR_PREPROCESSOR_KEYWORD
SYNK_PREPROCESSOR_INCLUDE	ppinclude	ATTR_PREPROCESSOR_INCLUDE
SYNK_PREPROCESSOR_DEFINE	ppdefine	ATTR_PREPROCESSOR_DEFINE
SYNK_PREPROCESSOR_CONDITIONAL	ppconditional	ATTR_PREPROCESSOR_CONDITIONAL
SYNK_TODO	todo	ATTR_TODO
SYNK_MARKUP	markup	ATTR_COMMENT_STANDOUT

Returns

nothing

Portability

A GriefEdit extension.

delete_block

int delete_block()

Deleted selected region.

Description

The delete_block() primitive deleted the current marked block, leaving the cursor position on the last line of the marked region.

The characters included in the mark depend on the its type, and once deleted the mark is removed.

On completion the following is echoed on the command prompt.

Block deleted.

In the event of no active region the following is echoed.

No marked block.

Parameters

none

Returns

The delete_block() primitive returns one if the block was delete, otherwise zero.

delete_bookmark

void delete_bookmark( int bookid )

Delete a bookmark.

Description

The delete_bookmark() primitive deletes the bookmark bookid.

Upon successful completion, the REG_BOOKMARK event shall be triggered (See: register_macro).

Parameters

bookid

Bookmark identifier.

Returns

nothing

Portability

n/a

delete_buffer

void delete_buffer( int bufnum )

Delete a buffer.

Description

The delete_buffer() primitive deletes the specified buffer, the buffer contents and all associated resources are released.

Any changes made to the buffer since it was last written shall be lost, as such if required the content should be written using write_buffer.

In the case of a process buffer, the underlying sub-process is shutdown.

Once deleted, the associated buffer handle is invalid.

Parameters

bufnum

Non-optional buffer number.

Returns

nothing

Portability

n/a

delete_char

void delete_char( [int num] )

Delete character.

Description

The delete_char() primitive deletes one or more characters at the current cursor position.

This primitive is the default assignment for the <Delete> key on the keyboard.

Parameters

num	Optional integer, if stated specifies the number of characters to be deleted, if omitted only a single character is removed.

Returns

nothing

Portability

n/a

delete_dictionary

int delete_dictionary( int obj_id )

Destroy a dictionary.

Description

The delete_dictionary() primitive destroys the specified dictionary obj_id.

Parameters

obj_id

Dictionary identifier.

Returns

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

Portability

A GriefEdit extension.

delete_edge

int delete_edge( [int direction] )

Delete an edge, combining a split window.

Description

The delete_edge() primitive deletes an edge, combined two windows sharing an adjoining edge into a single window.

The windows located in the specified direction are joined as follows,

0	Above/up.
1	Right.
2	Below/down.
3	Left.

If direction is omitted the user is prompted for the split direction; the user indicates the split direction by use of the arrow keys.

Select edge to delete [<^v>]

Once a window is deleted with delete_edge, its window identifier become invalid.

Parameters

direction

Optional integer direction stating the edge on which the join operation occurs deleting the associated windows (as above), if omitted the user is prompted.

Returns

The delete_edge() primitive returns 1 on success, 0 if the edge does exist, otherwise -1 if the user aborted.

Portability

n/a

delete_line

void delete_line()

Delete current line.

Description

The delete_line() primitive deletes the current line, placing the cursor at the same column on the following line.

Parameters

none

Returns

nothing

Portability

n/a

delete_macro

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.

Note:

This primitive is provided for BRIEF compatibility and is currently a no-op as macros are not directly deletable. The storage allocated to a macro shall be lost when a macro by the same name is loaded from another file.

Parameters

macro

String containing the name of a macro file to be deleted. If no extension is supplied, then .cm shall be appended. If omitted the user is prompted.

Returns

nothing

Portability

Not implemented.

delete_nth

void delete_nth( list lst,
[int offset = 0],
[int length = 1] )

Remove one or more elements from a list.

Description

The delete_nth() primitive deletes length elements from the specified list lst starting at the index offset.

Parameters

lst	List reference which shall have elements removed.
offset	Optional integer offset within list, if omitted defaults to the first element being offset 0.
length	Optional integer length, states the number of elements to be removed; if omitted only one element is removed. If 0 or less, than no elements will be removed.

Returns

nothing

Portability

n/a

delete_to_eol

void delete_to_eol()

Delete to end-of-line.

Description

The delete_to_eol() primitive deletes from the current cursor position to the end-of-line, not including the newline. The cursor position remains unchanged.

Parameters

none

Returns

nothing

Portability

n/a

delete_window

void delete_window( [int winum] )

Delete a window.

Description

The delete_window() primitive deletes the specified window.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

none

Portability

Unlike BRIEF any window may be deleted.

detach_syntax

void detach_syntax()

Detach a syntax from a buffer.

Description

The detach_syntax() primitive removes the associated syntax definition from the current buffer.

Parameters

none

Returns

The detach_syntax() primitive returns the syntax identifier which was associated with the buffer, otherwise -1 if no syntax was associated.

Portability

A GriefEdit extension.

dialog_create

int dialog_create( list decl )

Build a dialog resource.

Description

The dialog_create() primitive creates a dialog resource from the specified definition decl.

The buffer information dialog is just one example.

The declaration list should the contain the dialog elements plus their associated value, if any. Elements classifications are Containers, Widgets and Attributes.

Containers

Atom	Description
DLGC_GROUP	Variable sized visual and logical group container, with an optional frame and title.
DLGC_CONTAINER	General widget group, used to logical group a collection of widgets.
DLGC_TAB	Fixed size visual and logical container, with an optional title.

Widgets

Atom	Description
DLGC_CHECK_BOX	Check box
DLGC_COMBO_FIELD	Combo field
DLGC_EDIT_FIELD	Edit field
DLGC_LABEL	Text label
DLGC_LIST_BOX	List box
DLGC_NUMERIC_FIELD	Numeric field
DLGC_PUSH_BUTTON	Push button
DLGC_RADIO_BUTTON	Radio button
DLGC_SEPARATOR_HORIZONTAL	Horizontal separator
DLGC_SEPARATOR_VERTICAL	Vertical separator
DLGC_SPACER	Spacer

Attributes

Atom	Type	Description
DLGA_TITLE	String	Attribute title.
DLGA_NAME	String	Attribute name.
DLGA_IDENT	Int	Identifier.
DLGA_CALLBACK	String	Macro callback.
DLGA_HELP	String	Help topic.
DLGA_TOOLTIP	String	Tooltip topic.
DLGA_X	Int	Horizontal position.
DLGA_Y	Int	Vertical position.
DLGA_COLS	Int	Width in columns.
DLGA_ROWS	Int	Height in rows.
DLGA_ATTACH_TOP	n/a
DLGA_ATTACH_BOTTOM	n/a
DLGA_ATTACH_LEFT	n/a
DLGA_ATTACH_RIGHT	n/a
DLGA_ALIGN_N	n/a
DLGA_ALIGN_NE	n/a
DLGA_ALIGN_E	n/a
DLGA_ALIGN_SE	n/a
DLGA_ALIGN_S	n/a
DLGA_ALIGN_SW	n/a
DLGA_ALIGN_W	n/a
DLGA_ALIGN_NW	n/a
DLGA_ALIGN_CENTER	n/a
DLGA_ALLOW_EXPAND	n/a
DLGA_ALLOW_FILLX	n/a
DLGA_ALLOW_FILLY	n/a
DLGA_PROPAGATE	Boolean
DLGA_CANCEL_BUTTON	n/a
DLGA_DEFAULT_BUTTON	n/a
DLGA_DEFAULT_FOCUS	n/a
DLGA_VALUE	Any
DLGA_LABEL	String
DLGA_TEXT_ONLY	n/a
DLGA_GUI_ONLY	n/a
DLGA_ACCELERATOR	String
DLGA_HOTKEY	Integer
DLGA_GREYED	n/a
DLGA_ACTIVE	n/a
DLGA_SENSITIVE	Integer
DLGA_PADX	Integer
DLGA_PADY	Integer
DLGA_ORIENTATION	Integer
DLGA_HIDDEN	n/a
DLGA_VISIBLE	n/a
DLGA_KEYDOWN	Boolean
DLGA_TABSTOP	Boolean
DLGA_AUTOMOVE	Boolean
DLCA_USERDATA	Int
DLGA_EDEDITABLE	Boolean
DLGA_EDMAXLENGTH	Integer
DLGA_EDVISIBLITY	Boolean
DLGA_EDPOSITION	Integer
DLGA_EDPLACEHOLDER	String
DLGA_LBCOUNT	Integer
DLGA_LBELEMENTS	Any
DLGA_LBSORTMODE	Integer
DLGA_LBHASSTRINGS	Integer
DLGA_LBICASESTRINGS	Integer
DLGA_LBDUPLICATES	Integer
DLGA_LBCLEAR	n/a
DLGA_LBCURSOR	Integer
DLGA_LBACTIVE	Integer
DLGA_LBDISPLAYTEXT	Integer
DLGA_LBDISPLAYTEXTLEN	Integer
DLGA_LBTEXT	Integer
DLGA_LBTEXTLEN	Integer
DLGA_LBPAGEMODE	Boolean
DLGA_LBINDEXMODE	Boolean
DLGA_CBEDITABLE	Boolean
DLGA_CBRELAXMODE	Integer
DLGA_CBAUTOCOMPLETEMODE	Integer
DLGA_CBPOPUPMODE	Integer
DLGA_CBPOPUPSTATE	Integer
DLGA_GAUGEMIN	Int\|Str
DLGA_GAUGEMAX	Int\|Str

Parameters

decl	Dialog definition.

TODO

Allow the dialog definition to be XML.

Returns

On success returns a unique dialog resource identifier otherwise -1 on error.

Portability

A GriefEdit extension.

dialog_delete

int dialog_delete( int dialog )

Delete a dialog resource.

Description

The dialog_delete() primitive deletes the specified dialog resource.

Parameters

dialog

Optional dialog instance handle, if omitted the current dialog is referenced.

Returns

The dialog_delete() primitive return non-zero on success, otherwise zero on error.

Portability

A GriefEdit extension.

dialog_exit

int dialog_exit( int retval = 0,
[int dialog] )

Exit a dialog resource.

Description

The dialog_exit() primitive exits the current dialog.

Parameters

retval	Integer return value, returned to the original dialog_run caller.
dialog	Optional dialog instance handle, if omitted the current dialog is referenced.

Returns

Returns 1 on success otherwise 0.

Portability

A GriefEdit extension.

Description

The dialog_run() primitive executes the dialog associated with the instance dialog, supplying the arguments args.

Parameters

dialog	Dialog instance handle.
args	Optional string containing

Returns

The dialog_run() primitive returns the exit value of the terminating dialog_exit.

Portability

A GriefEdit extension.

dict_clear

int dict_clear( int obj_id )

Clear a dictionary.

Description

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

Parameters

obj_id

Dictionary identifier.

Returns

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

Portability

A GriefEdit extension.

dict_delete

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

obj_id	Dictionary identifier.
key	Item key.

Returns

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

Portability

A GriefEdit extension.

dict_each

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

obj_id	Dictionary identifier.
key	Retrieval key.
value	Value.

Returns

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

Portability

A GriefEdit extension.

dict_exists

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

obj_id	Dictionary identifier.
key	Item key.

Returns

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

Portability

A GriefEdit extension.

dict_keys

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.

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

obj_id	Dictionary identifier.
key	Retrieval key.

Returns

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

Portability

A GriefEdit extension.

dict_list

list dict_list( int obj_id )

Retrieve dictionary items.

Description

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

Parameters

obj_id	Dictionary identifier.
keys	Optional boolean value unless FALSE key values are retrieved otherwise values are retrieved.

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.

dict_name

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

obj_id

Dictionary identifier.

Returns

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

Portability

A GriefEdit extension.

dict_values

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.

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

obj_id	Dictionary identifier.
value	Value.

Returns

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

Portability

A GriefEdit extension.

diff_strings

int diff_strings( [int flags],
string s1,
string s2 )

Compare to strings.

Description

The diff_strings() primitive determines whether the specified strings are equivalent based on the set of formatting rules specified by the comparison flags flags.

Comparison Flags

Line comparison flags, which affects the treatment of whitespace and character case.

Constant	Description
DIFF_IGNORE_WHITESPACE	Ignore white-space differences.
DIFF_IGNORE_CASE	Ignore character case, whereby characters using different case shall be treated as equivalent.
DIFF_COMPRESS_WHITESPACE	Repeated whitespace characters are compressed into a single space and compared as such.
DIFF_SUPPRESS_LEADING	Leading whitespace is ignored.
DIFF_SUPPRESS_TRAILING	Trailing whitespace is ignored.
DIFF_SUPPRESS_LFCR	Line-feed and carriage-return characters are ignored.

Parameters

flags	Optional integer flags defining the rules to be applied during their comparison which maybe one or more of the predefined flags or’ed together. If omitted or zero diff_strings behaves similar to strcmp.
s1	First string to compare.
s2	Second string against which to compare the first.

Returns

The diff_strings() primitive returns zero if the two string are equivalent otherwise non-zero.

Portability

A GriefEdit extension.

dirname

int dirname( string path )

Report the parent directory name of a file pathname.

Description

The dirname() primitive shall take a string path that contains a pathname, and return a string containing that is a pathname of the parent directory of that file. Trailing directory separators (/ and \) characters in the path are not counted as part of the path.

If path does not contain a directory separator (/ and \) or is an empty string, then dirname shall return a string “.”.

Returns

The dirname() primitive returns string containing the parent directory name of a file pathname, otherwise a string containing “.”.

Portiablity

A GriefEdit extension.

disconnect

int disconnect()

Disconnect a buffer from a process.

Description

The disconnect() primitive disconnects the current buffer from any attached process, if any, terminating the subprocess.

Note:

Under Unix the terminated subprocess is sent a SIGTERM followed by a SIGKILL signal.

Parameters

none

Returns

Returns 1 on success otherwise 0.

Portability

n/a

display_mode

int display_mode( [int or_mask|string set-list],
[int and_mask|string clear-list],
[int scroll_cols],
[int scroll_rows],
[int visible_cols],
[int visible_rows],
[int number_cols] )

Set/retrieve display control flags.

Description

The display_mode() primitive controls primary features of the display interface. Features are either stated using their manifest constant or in the case of values an explicit parameters

If specified one or more flags shall be cleared using the and_mask, in additional one or more flags are set using the or_mask.

Constant	Name	Description
DC_WINDOW	window	Running under a windowing system (ro).
DC_MOUSE	mouse	Mouse enabled/available (ro).
DC_READONLY	readonly	Read-only mode (ro).
DC_CHARMODE	charmode	Character-mode with basic GUI features (r
DC_SHADOW	shadow	Display shadow around popups.
DC_SHADOW_SHOWTHRU	showthru	Show-thru shadow around popups.
DC_STATUSLINE	statusline	Status line.
DC_UNICODE	unicode	UNICODE character encoding available (ro)
DC_ASCIIONLY	asciionly	ASCII only characters witihin UI/dialogs.
DC_ROSUFFIX	rosuffix	Read-only suffix on titles.
DC_MODSUFFIX	modsuffix	Modified suffix.
DC_EOF_DISPLAY	eof_display	Show <EOF> marker.
DC_TILDE_DISPLAY	tilde_display	Show ~ marker.
DC_EOL_HILITE	eol_hilite	Limit hilites to EOL.
DC_HIMODIFIED	himodified	Hilite modified lines.
DC_HIADDITIONAL	hiadditional	Hilite additional lines.

Note:

Items marked as (ro) are Read-Only with any specified changes against the attribute shall be quietly ignored.

The optional parameters scroll_cols and scroll_rows define the screen distance each scroll operation shall employ. Values greater than one result in scroll jumps, which may be desired on slower terminals.

The optional parameters visual_cols and visual_rows define the smallest display arena which shall be permitted, with number_cols defining the number line arena width.

Parameters

set_mask	Optional mask of flags to set. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.
clear_mask	Optional mask of flags to clear. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.
scroll_cols	Optional integer value, if stated sets the number of screen columns scroll operations shall employ. A value of zero shall clear the scroll override, defaulting the value to 1. Upon a negative value, the current override shall be returned.
scroll_rows	Optional integer value, if stated sets the number of screen rows scroll operations shall employ. A value of zero shall clear the scroll override, defaulting the value to 1. Upon a negative value, the current override shall be returned.
visible_cols	Optional integer value, if stated sets the lower bounds of the display arena width. Upon a negative value, the current override shall be returned.
visible_rows	Optional integer value, if stated sets the lower bounds of the display arena height. Upon a negative value, the current override shall be returned.
number_cols	Optional integer value, if stated as a positive integer sets the width of the number-line column within windows, disabling dynamic width selection. A value of zero shall clear the width override, enabling the default dynamic width based upon the buffer length. Upon a negative value, the current override shall be returned.

Returns

The display_mode() primitive by default returns the previous value of the display control flags prior to any modifications.

If one of the integer parameters is a negative value (e.g. -1) then display_mode returns the current value of the associated parameter. If more than one is negative, then the value of last shall be returned.

Portability

The string mask variants and set parameter are GRIEF extensions.

Many of the flags are GRIEF specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.

display_windows

int display_windows( [int mode] )

Control window display.

Description

The display_window() primitive control the state of the display driver.

This primitive should be called prior to the creation of any windows using create_tiled_window enabling the display driver. If any tiled windows exist when enabled the following error shall be echoed, denoting incorrect system initialisation.

display_window: overlapping window exist

The original functionality was intended to initialise a set of tiled windows, between two successive calls; firstly with disable (0) which cleared all windows and secondary on the completion of the window creation with enable (1). This implementation only obeys the first enable command, with any disable requests silently ignored.

Parameters

mode	Optional integer, if specified states the new display mode, otherwise if omitted the current display mode is toggled.

Returns

The display_window() primitive returns the previous status.

Portability

Unlike BRIEF existing tiled windows are not destroyed upon the initial mode change.

distance_to_indent

int distance_to_indent( [int column] )

Calculate distance to next indent.

Description

The distance_to_indent() primitive calculates the distance in characters to the next active indentation from either the specified column otherwise if omitted the current cursor position.

The active indentation information is sourced from the first available specification in order from the following:

Ruler specification (See: set_ruler).
Buffer indentation (See: set_indent).
Tab specification (See: tabs).

Parameters

column

Optional column if omitted the current buffer position is referenced.

Returns

Returns the number of columns/characters between the referenced column and the next indentation. If the referenced column is on a tab stop, then the number of characters to the next tab stop shall be returned.

Portability

A GriefEdit extension.

distance_to_tab

int distance_to_tab( [int column] )

Calculate distance to next tab.

Description

The distance_to_tab() primitive calculates the distance in characters to the next tab from either the specified column otherwise if omitted the current cursor position.

Parameters

column

Optional column if omitted the current buffer position is referenced.

Returns

Returns the number of columns/characters between the referenced column and the next tab stop. If the referenced column is on a tab stop, then the number of characters to the next tab stop shall be returned.

Portability

n/a

do

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

double

double sym1, sym2 ...;

Declare a double float symbol.

Description

The double statement is an alias for the float type.

Note:

Unlike C and C++, both float and double are internally representing using a 64-bit double precision floating-point

Returns

nothing

Portability

n/a

down

int down( [int lines = 1] )

Move position down one line.

Description

The down() primitive moves the cursor down one line to the same column on the next line.

Parameters

lines

Optional number of lines to move the cursor; may be negative in which case the cursor moves backwards behaving like up.

Returns

The down() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

dprintf

int dprintf( string format,
... )

Formatted diagnostics output.

Description

This primitive is used to write a diagnostic messages to the trace log when debug is enabled.

The dprintf() primitive produces formatted output according to the format specification format into the diagnostics log. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.

The format primitive is similar to the C fprintf() primitive, exporting the formatted result to an external stream.

This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.

Parameters

format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The dprintf() primitive returns the number of charaters stored within the result string buffer.

Portability

This is a GriefEdit extension.

drop_anchor

int drop_anchor( [int type = MK_NORMAL] )

Start marking a selection.

Description

The drop_anchor() primitive starts marking a block of the specified type at the current position in the current buffer.

Marked regions are highlighted to stand out on the screen either in a different colour or in reverse video dependent on the available display capacities.

The following are the available region types.

Value	Constant	Description
1	MK_NORMAL	A normal mark.
2	MK_COLUMN	A column mark.
3	MK_LINE	A line mark.
4	MK_NONINC	A non-inclusive mark.

MK_NORMAL	A normal mark is a region which encompasses from the place where the anchor was dropped up to and including the current cursor position.
MK_COLUMN	A column mark allows a rectangular section of the buffer to be marked, highlighting the inclusive columns between the left and right boundaries.
MK_LINE	A line mark selects entire lines, and allows for easy movement of text from one part of a buffer to another.
MK_NONINC	A non-inclusive mark, like a normal, is a region which encompasses from the place where the anchor was dropped up to and but does not include the current cursor position.

Regions are nestable, in that a drop_anchor may be issued without an intervening raise_anchor. Each mark is pushed into a LIFO (last-in, first-out) stack, allowing multiple marks to exist simultaneously; each mark must however be eventually raised. The most recent mark shall be the one displayed by the buffer.

The current active marked region can queried using inq_marked.

The marked region can be cleared by calling raise_anchor or performing a high level copy or cut buffer operations plus a numebr of the lower level functions, for example delete_block.

Parameters

type	Optional anchor type to be dropped Otherwise if omitted a MK_NORMAL anchor shall created.

Returns

The drop_anchor returns 1 if successful, otherwise 0 on error.

Portability

n/a

drop_bookmark

int drop_bookmark( [int bookid],
[string yesno],
[int bufnum],
[int line],
[int column],
[int local = FALSE] )

Create or update a bookmark.

Description

The drop_bookmark() primitive either create a new or updates an existing bookmark. A bookmark is a named place holder with a buffer, representing a specific physical location within that buffer.

bookid is the unique identifier to be associated with the bookmark; any valid integer may be used as the identifier. The bookmark shall be associated with the buffer bufnum, line and column, if any are omitted the current buffer and location with that shall be used.

Upon there being an existing definition against the specified bookmark identifier, the user shall be prompted as follows, asking whether or not the bookmark should be replaced:

Overwrite existing bookmark [y/n]?

The yesno argument if given disables the user prompt. If supplied with either “y” or “yes” the bookmark shall automatically be replaced, otherwise the bookmark is retained without change with the user informed as follows:

Bookmark already exists.

Upon successful completion, the user shall be informed as follows regardless of whether a new or updated definition resulted:

Bookmark dropped.

Parameters

bookid	Optional bookmark identifier, if omitted a new unique book mark identifier shall be generated.
yesno	Optional string buffer containing the answer to be applied upon the bookmark pre-existing, if given as “y[es]” the bookmark shall be overridden otherwise is shall be related. Otherwise if omitted upon a preexisting bookmark the user shall be prompted.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
line	Optional integer line number within the buffer, if omitted shall default to the top of the buffer (1).
column	Optional integer column number within the buffer, if omitted shall default to the left of the buffer (1).
local	Reserved for future use.

Returns

The drop_bookmark() primitive returns the associated book mark identifier, otherwise 0 on error.

Portability

n/a

TODO

Support buffer local bookmark identifiers; improves Vim compatibility.

echo_line

int echo_line( [int flags] )

Set echo line flags.

Description

The echo_line() primitive controls the fields which are to be visible within the status area.

The status area layout can be defined by one of two means. The echo_line specification controls the elements visible using a fixed layout whereas set_echo_format allows a user defined format specification.

The default echo_line configuration is.

E_CHARVALUE | E_VIRTUAL | E_LINE | E_COL | \
    E_CURSOR | E_REMEMBER | E_TIME

Parameters

flags

Optional integer flags, one or more of the following flags OR’ed together control the components to be reported against each attribute. If omitted then only the current flag values are returned without any change.

Flags

Constant	Order	Definition
E_CHARVALUE	1	Character value.
E_VIRTUAL	2	Virtual character indicator.
E_LINE	3	Line: field.
E_COL	4	Col: field.
E_PERCENT	5	nn%
E_CURSOR	7	Insert/overstrike status (OV or blank).
E_REMEMBER	6	Remember status (RE and PA).
E_TIME	8	HH:MM a/pm
E_TIME24	8	Time in 24hour form (HH:MM).
E_FORMAT	n/a	Format override active.
E_FROZEN	n/a	Echo line is frozen, ie not updated.

When an status area user specified format is active then the E_FORMAT flag is enabled (See: set_echo_format). Setting a format also sets E_FORMAT similarly clearing the format clears E_FORMAT.

The E_FROZEN flag disables status area updates whilst set. E_FROZEN can be utilised by macros to reduce screen updates during buffer operations.

Active Character

The E_CHARVALUE element identifies the character under the cursor. Normal printable characters are enclosed within a set of square brackets, with non-printable characters represented by their hexadecimal value. When the cursor is positioned past the end of the current line, EOL is displayed, and when past the end of file, EOF is displayed.

Virtual Character

The E_VIRTUAL element indicates whether the current character is either a physical or virtual character in the case of tabs, EOL and EOF conditions.

The virtual character status is represented by one of the following otherwise blank if a normal character.

X	Virtual space, for example logical space created as the result of tab expansion.
$	End of line.
+	Position is past the end-of-line.
#	Is a Unicode encoded character.
!	Is an illegal Unicode character code.

Buffer Coordinates

The E_LINE and E_COL elements represents the line (row) and column where the cursor is located. Unless invoked with restore enabled, when GRIEF is started the cursor is located at top of the current buffer, being line one(1) and column one(1).

Cursor Mode

The E_CURSOR element represents the optional cursor mode.

On systems which have means of controlling the cursor, the current insert/overstrike mode is represented by the cursor shape; when overstrike mode a large/block cursor is used wheras insert mode shall utilise a small/underline cursor.

Otherwise on systems without cursor control a mode indicator shall be displayed, OV when overstrike is active otherwise blank when in insert mode.

Remember Status

The E_REMEMBER element represents the remember status.

When macro recording is active or paused, RE and PA respectively are displayed.

Time

Last item in the status area is the time, which is displayed in hours and minutes, with a colon as a separator either using a 12-hour format E_TIME or a 24-hour format E_TIME24.

Returns

The echo_line() primitive returns the previous flags value.

Portability

n/a

edit_file

int edit_file( ... )

Edit a file.

Description

The edit_file() primitive creates a new buffer, loads the contents, attaches the buffer to the current window and executes any registered macros, see register_macro.

The argument specification is a set of one or more strings with optional leading integer modes. Modes control the flags under which the subsequent files are processed.

If the specified file is already within another buffer, that buffer becomes the current buffer and is attached to the current window.

If more than one argument is specified; either directly or as the result of file expansion; then a separate edit action is performed on each file, with the current buffer being the last stated file.

File Expansion

The edit_file() primitive performs file name globbing in a fashion similar to the csh shell. It returns a list of the files whose names match any of the pattern arguments.

The pattern arguments may contain any of the following special characters:

~[user/]	Home directory of either the current or the specified user.
?	Matches any single character.
*	Matches any sequence of zero or more characters.
[ch]	Matches any single character in chars. If ch’s contains a sequence of the form a-b then any character between a and b (inclusive) will match.
\x	Matches the character x.

File detection

During file loading GRIEF performs a number of tests against the sections of the file content in an attempt to determine the file encoding. These operations are generally invisible to end user and behave on most file types without interaction.

The current default scanners include, see set_file_magic for additional details on each.

mark	Encoding: < marker >
utf32bom	UTF-32 BOM marker.
utf16bom	UTF-16 BOM marker.
udet	Mozilla Universal Character Detector.
magic	File magic.
binary	Possible binary image.
ascii	ASCII only (7-bit).
latin1	Latin-1 (ISO-8859-x) data.
big5	Chinese Big5.
gb18030	Chinese GB-18030.
shiftjis	Shift-JIS.
xascii	Extended ASCII.

Parameters

...

Argument specification is a set of one or more strings with optional leading integer modes.
Modes control the flags under which the subsequent files are processed, see examples. Unless specified files are loaded using EDIT_NORMAL.
If no arguments are specified, the user shall be prompted for a file specification.

Modes

Constant	Description
EDIT_NORMAL	Default mode; auto-guess the file type.
EDIT_BINARY	Force file to be read in binary mode, see set_binary_size.
EDIT_ASCII	Force file to be read in ASCII mode.
EDIT_STRIP_CR	Force CR removal on input and write them on output.
EDIT_STRIP_CTRLZ	Force Ctrl-Z removal.
EDIT_SYSTEM	System buffer.
EDIT_RC	Enable extended return codes.
EDIT_QUICK	Quick detection, removes more costly character-encoding methods.
EDIT_AGAIN	<edit_again> implementation.
EDIT_LOCAL	Edit locally, do not rely on the disk being stable.
EDIT_READONLY	Set as read-only.
EDIT_LOCK	Lock on read (strict-locking).
EDIT_NOLOCK	Disable auto-locking.
EDIT_PREVIEW	Limit the load to the window size.

Returns

The edit_file() primitive returns a positive value on success, 0 if the user was prompted and cancelled, otherwise -1 on error.

If more than one argument is specified; either directly or as the result of file expansion; the return relates to the last loaded file.

Under EDIT_RC the return code are extended to differentiation between success conditions as follows.

Value	Desciption
-1	Error.
0	Cancelled.
1	Successfully loaded buffer.
2	New image, file created.
3	Pre-existing buffer, not reloaded.

Example

Expand and load all .cpp files located within the current working directory.

edit_file(".cpp");

Loads a system buffer with the content from config.ini sourced from the users home directory.

edit_file(EDIT_SYSTEM, "~/config.ini");

Portability

The feature set exposed differs from implementations. It is therefore advised that the symbolic constants are using within a #ifdef construct.

edit_file2

int edit_file2( string encoding,
string|list file )

Extended file edit.

Description

The edit_file2() primitive extends the functionality provided by edit_file with the leading parameter of encoding.

Parameters

encoding	String containing the character encoding of the source file.
...	See edit_file

Returns

The edit_file2() primitive returns a positive value on success, 0 if the user was prompted and cancelled, otherwise -1 on error.

See edit_file for additional return information.

Portability

A GriefEdit extension.

ega

int ega( int lines )

Terminal line display.

Description

The ega() primitive attempts to configure the console size to the specified number of lines with an implied width of 80 columns on supporting terminals.

Possible screen dimensions include.

60 x 80
50 x 80
43 x 80
25 x 80

Parameters

lines

Optional integer specifing the required number of console lines. Under WIN32 if -1 the console size shall toggled bewteen minimized and maximised. If omitted, then only the current state is returned.

Notes!

When running within a windows console, before Windows 7 one could press <Alt+Enter> to run the application in full screen. As of Windows 7 this functionality is no longer available resulting in the following.

This system does not support full screen mode

The ega() primitive can be used to emulate this functionality, using the special -1 flag, which shall toggle between a minimized or maximised sized console.

ega(-1)

Returns

The ega() primitive returns the previous status, otherwise -1 upon an error.

Portability

A GriefEdit extension.

end_anchor

int end_anchor( [int line],
[int column] )

Set the end of the anchor.

Description

The end_anchor() primitive sets the end of the current marked region without the need to move the cursor.

Parameters

line	Optional new line, if omitted the line shall be unchanged.
column	Optional new column, if omitted the column shall be unchanged.

Returns

The end_anchor returns 1 if successful, otherwise 0 on error.

Portability

n/a

end_of_buffer

int end_of_buffer()

Move cursor to end of current buffer.

Description

The end_of_buffer() primitive moves the buffer cursor to the end of the last line of the current buffer.

Parameters

none

Returns

The end_of_buffer() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

end_of_line

int end_of_line()

Goto end of line.

Description

The end_of_line() primitive moves the buffer cursor to the last character of the current line.

Parameters

none

Returns

The end_of_line() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

end_of_window

int end_of_window()

Goto end of the current window.

Description

The end_of_window() primitive moves the buffer cursor to the last line of the current window.

Parameters

none

Returns

Returns non-zero if the current cursor position moved, otherwise zero if already positioned at the end of the window.

Portability

n/a

error

int error( string format,
... )

Issue an error message on the command line.

Description

The error() primitive is used to display a message on the prompt line at the bottom of the screen. format is a string and may contain printf-like % formatting characters. The following arguments format and so forth are integer or string expressions used to satisfy the % formatting options.

This primitive may be used to error messages on the bottom of the screen; if informational messages are required to be displayed then the message primitive macro should be used instead.

Error messages are printed in the error color (See: color) and truncated if they are too long.

In addition, upon enabling pause_on_error then the error message is displayed suffixed with a .. and GriefEdit waits for the user to type any key to continue; useful during debugging.

This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.

Parameters

format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The message() primitive returns the number of characters printed.

Example

message("File: %s", current_name);

Portability

Many of the format options are GriefEdit extensions, including %b, %n, %t, %B and * support.

The original implementation has a void declaration and returns nothing.

The standard interface only permits upto 6 arguments, whereas GriefEdit is unbound.

execute_macro

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.

Note:

The execute_macro primitive cannot be overloaded with a replacement macro.

Parameters

cmd	Optional string buffer containing the command to be executed. Otherwise if omitted the user shall be prompted for the command.
...	Depending on the macro, the executed command may expect a sequence of additional arguments.

Returns

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

Portability

n/a

exist

int exist( string path,
[int canon = TRUE] )

Check file existence.

Description

The exist() primitive tests whether of the specified file path exists.

If canon is not specified, then the filename is canonised first. This involves expanding any tilde prefixes and converting DOS style filenames to Unix style ones.

Returns

The exist() primitive returns non-zero if the file exists, otherwise 0 on error. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

exit

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

y_or_w

Optional string that is applied to the answer regarding the action to occur when modified buffers are detected; Y or y GriefEdit shall exit without saving any modifiers buffers, whereas W or w all modified buffers are written.
Any other values other than “YyWW” shall cause the user to be prompted. In addition, the parameter is ignored if exit is being applied to a secondary process loop, which would not cause GriefEdit to terminate.

Returns

nothing

Portability

n/a

exp

float exp( float x )

Exponential function.

Description

The exp() primitive calculates the exponent of x, defined as e**x, where e equals 2.17128128....

Returns

If successful, the function returns the calculated value.

If an overflow occurs, the function returns HUGE_VAL. If an underflow occurs, it returns 0. Both overflow and underflow set errno to ERANGE.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

expandpath

string expandpath( string path,
[int env] )

Expand the path.

Description

The expandpath() primitive expands any shell style home directory ~[user] references/short-hands contained within the specified path, returning the result.

The supported shell constructs are.

~/	is expanded to your current home directory.
~user/	is expanded to the specified users home directory (unix only).

If env is specified and is non-zero, then the any embedded environment variable references are also expanded following the following syntax. When a macro is not defined it expands to \”\” (an empty string), and {} are synonyms for ().

$(name)	Expands to value of name.
${name}	Expands to value of name.
$name/	Expands to value of name.

Returns

The expandpath() primitive returns a string containing the expanded path following the above rules, otherwise an empty string.

Portability

A GriefEdit extension.

extern

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.

Note:

You should note that we are using the words definition and declaration carefully when we refer to external variables in this section. Definition refers to the place where the variable is created or assigned storage; declaration refers to places where the nature of the variable is stated but no storage is allocated.

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

fabs

float fabs( float x )

Floating-point absolute value.

Description

The fabs() primitive calculates the absolute value of a floating-point argument x.

Returns

Returns the absolute value of the float input.

Portability

n/a

fclose

int fclose( int handle )

Close a stream.

Description

The fclose() primitive shall cause the stream pointed to by stream to be flushed and the associated file to be closed. Any unwritten buffered data for the stream shall be written to the file; any unread buffered data shall be discarded.

Returns

On successful completion, fclose() shall return 0; otherwise, it shall return -1 and set errno to indicate the error.

Portability

A GriefEdit extension.

feof

int feof( int handle )

Test end-of-file indicator on a stream.

Description

The feof() primitive shall test the end-of-file indicator for the stream pointed to by stream.

Returns

The feof() primitive returns non-zero if and only if the end-of-file indicator is set for stream.

Portability

A GriefEdit extension.

Notes

The feof() primitive is reserved for future use, and currently returns -1 in all cases.

ferror

int ferror( int handle,
[int clearerr] )

Test error indicator on a stream.

Description

The ferror() primitive shall test the error indicator for the stream referenced by handle.

Returns

The ferror() primitive shall return non-zero if and only if the error indicator is set for stream.

Portability

A GriefEdit extension.

Notes

The ferror() primitive is reserved for future use, and currently returns -1 in all cases.

fflush

int fflush( int handle,
[int sync] )

Flush a stream.

Description

The fflush() primitive is reserved for future use.

Returns

The fflush function returns non-zero if a write error occurs and zero otherwise. When an error has occurred, errno contains a value indicating the type of error that has been detected

Portability

An experimental GriefEdit extension; functionality may change.

Notes

The fflush() primitive is reserved for future use, and currently returns -1 in all cases.

file_canon

string file_canon( string filepath )

Canonicalize a path.

Description

The file_canon() primitive performs canonicalizes the specified path filepath and returns a new path.

The new path differs from path in

Slashes are normalised with \ replaced with ‘/’.
Relative paths are prefixed with the current working directory.
Multiple `/’s are collapsed to a single `/’.
Leading `./’s and trailing `/.’s are removed.
Trailing `/’s are removed.
Non-leading `../’s and trailing `..’s are handled by removing portions of the path.

Returns

The file_canon() primitive returns the canonicalized file path.

Portability

A GriefEdit extension.

file_glob

list file_glob( string files )

Return names of files that match patterns.

Description

The file_glob() primitive performs file name globbing in a fashion similar to the csh shell. It returns a list of the files whose names match any of the pattern arguments.

No particular order is guaranteed in the list, so if a sorted list is required the caller should use sort_list.

The pattern arguments may contain any of the following special characters:

~[user/]	Home directory of either the current or the specified user.
?	Matches any single character.
*	Matches any sequence of zero or more characters.
[ch]	Matches any single character in chars. If ch’s contains a sequence of the form a-b then any character between a and b (inclusive) will match.
\x	Matches the character x.

Returns

The file_glob() primitive returns a list of strings corresponding to the filenames which match the wild card expression in string. When no matches or error, an empty list is returned.

file_match

int file_match( pattern,
file,
[flags] )

File match utility.

Description

The file_match() primitive performs wild-card name matching, which has two major uses. It could be used by an application or utility that needs to read a directory and apply a pattern against each entry.

The find_file() primitive is an example of this. It can also be used by the ts macro to process its pattern operands, or by applications that need to match strings in a similar manner.

The file_match() primitive is intended to imply filename match, rather than pathname match. The default action of this primitive is to match filenames, rather than path names, since it gives no special significance to the slash character.

pattern can be a list of search expressions or a string containing a single expression. file is the file-name that shall be tested.

If supplied, flags allows control over how directory delimiters slash(/) and dots (.) are matched within file-name. Otherwise it defaults to setting the MATCH_PERIODA and MATCH_NOCASE based on the current operating environment similar to ones used during edit_file() pattern matching.

Pattern

The following patterns matching a single character match a single character: ordinary characters, special pattern characters and pattern bracket expressions. The pattern bracket expression will also match a single collating element.

An ordinary character is a pattern that matches itself. It can be any character in the supported character set except for NUL, those special shell characters that require quoting, and the following three special pattern characters.

When unquoted and outside a bracket expression, the following three characters will have special meaning in the specification of patterns:

?	A question-mark is a pattern that will match any character.
*	An asterisk is a pattern that will match multiple characters, as described in Patterns Matching Multiple Characters, see below.
[	The open bracket will introduce a pattern bracket expression, see below.

Patterns Matching Multiple Characters

The following rules are used to construct patterns matching multiple characters from patterns matching a single character:

The asterisk (*) is a pattern that will match any string, including the null string.
The concatenation of patterns matching a single character is a valid pattern that will match the concatenation of the single characters or collating elements matched by each of the concatenated patterns.
The concatenation of one or more patterns matching a single character with one or more asterisks is a valid pattern. In such patterns, each asterisk will match a string of zero or more characters, matching the greatest possible number of characters that still allows the remainder of the pattern to match the string.

Character Set Range Match

[ introduces a pattern bracket expression, that will matches a single collating element contained in the non-empty set of collating elements. The following rules apply:

A bracket expression is either a matching list expression or a non-matching list expression. It consists of one or more expressions.
A matching list expression specifies a list that matches any one of the expressions represented in the list. The first character in the list must not be the circumflex (^). For example, [abc] is a pattern that matches any of the characters a, b or c.
A non-matching list expression begins with a circumflex (^), and specifies a list that matches any character or collating element except for the expressions represented in the list after the leading circumflex. The circumflex will have this special meaning only when it occurs first in the list, immediately following the left-bracket.
A range expression represents the set of collating elements that fall between two elements in the current collation sequence, inclusively. It is expressed as the starting point and the ending point separated by a hyphen (-). For example, [a-z] is a pattern that matches any of the characters a to z inclusive.
A bracket expression followed by + means one or more times.

Character Classes

Within bracket expressions, the name of a character class enclosed in [: and :] stands for the list of all characters belonging to that class.

Standard (POSIX style) character classes are;

alnum	An alphanumeric (letter or digit).
alpha	A letter.
blank	A space or tab character.
cntrl	A control character.
csym	An alphanumeric (letter or digit) or or underscore character.
digit	A decimal digit.
graph	A character with a visible representation.
lower	A lower-case letter.
print	An alphanumeric (same as alnum).
punct	A punctuation character.
space	A character producing white space in displayed text, space or a tab.
upper	An upper-case letter.
xdigit	A hexadecimal digit.

Flags

If supplied the flags argument shall modify the interpretation of pattern and string. It is the bitwise-inclusive OR of zero or more of the flags defined in grief.h.

MATCH_PATHNAME - If the MATCH_PATHNAME flag is set in flags, then a slash character (‘/’) in string shall be explicitly matched by a slash in pattern; it shall not be matched by either the asterisk (*) or question-mark (?) special characters, nor by a bracket expression ([]). If the MATCH_PATHNAME flag is not set, the slash character shall be treated as an ordinary character.

MATCH_NOCASE - If the MATCH_NOCASE flag is set in flags, then the pattern is treated non-case sensitively, i.e. A matches a. Otherwise the search is performed with case being sensitive.

MATCH_NOESCAPE - If MATCH_NOESCAPE is not set in flags, a backslash character (\\) in pattern followed by any other character shall match that second character in string. In particular, “\\” shall match a backslash in string. If MATCH_NOESCAPE is set, a backslash character shall be treated as an ordinary character.

MATCH_PERIOD - If MATCH_PERIOD is set, a leading period in string will match a period in pattern; where the location of “leading” is indicated by the value of MATCH_PATHNAME as follows:

If not set, no special restrictions are placed on matching a period.

is set, a period is “leading” if it is the first character in string or if it immediately follows a slash.
is not set, a period is “leading” only if it is the first character of string.

MATCH_PERIODA, MATCH_PERIODQ and MATCH_PERIODB - If set these allow selective control whether the asterisk (*) or question mark (?) special characters, nor by a bracket ([]) expression have affect.

Examples

a[bc]

matches the strings ab and ac.

a*d

matches the strings ad, abd and abcd, but not the string abc.

a*d*

matches the strings ad, abcd, abcdef, aaaad and adddd.

*a*d

matches the strings ad, abcd, efabcd, aaaad and adddd.

Note

file_match() does not perform tilde expansion (See: expandpath).

Returns

The file_match() primitive returns 1 if file matches the specified pattern; returns 0 if pattern isnt matched. If pattern is a list, then the index into the list that matched the expression or -1.

Portability

A GriefEdit extension.

file_pattern

int file_pattern( string filespec )

Directory file pattern.

Description

The file_pattern() primitive sets the search pattern for files, using find_file, and reset the internal status to the first matching file.

Parameters

filespec

String containing the file pattern specification which should evaluate to a file name or a wild-card filename, see the file_match for details regarding the supported wildcard.

Returns

The file_pattern() primitive returns 0 on success, otherwise -1 on error. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Notes

This interface enforces the rule (MATCH_PERIODA) that a leading “” wont match any files which begin with a “.” as such use “?” to match all files contained within a directory. See file_match for details on the filespec syntax.

filename_match

int filename_match( string file,
declare pattern )

Perform file pattern matching.

Description

The filename_match() primitive is similar to the file_match() primitive but is provided for CRiSP ™ compatibility. It is used to compare a filename to see if it matches a filename regular expression.

A filename expression is a regular expression similar to that accepted by the command line shells on Unix systems (e.g. you can use * for wildcard, ? for wild-character, and [..] to select a range of characters).

file is the filename that shall be tested. pattern can be a list of search expressions or a string containing a single expression (See: file_match) for details on the expression syntax.

Returns

The filname_match() primitive return value is dependent on the pattern type. If pattern is a string, then 1 if the filename matches; 0 otherwise. If pattern is a list, then the index into the list that matched the expression or -1.

Portability

Functionality has not been formally verified against CRiSPEdit and whether it supports the [..]+ expression construct.

filename_realpath

string filename_realpath( string pathname )

Return a resolved pathname.

Description

The filename_realpath() primitive shall derive, from the pathname an absolute pathname that names the same file, whose resolution does not involve ., .., or symbolic links.

Returns

The file_realpath() primitive returns the resolved file if successful otherwise the original pathname.

find_file

int find_file( [string &filename],
[int &size],
[int &mtime],
[int &ctime],
[int &mode] )

Description

The find_file() primitive retrieves the next file which matches the current file pattern. The active source directory and pattern are controlled using file_pattern.

Example

The following example retrieves are .txt files within the current working directory.

string name;
int size;

file_pattern("*.txt");
while (file_find(name)) {
    parsename(name, size);
}

This primitive is used in conjunction with file_pattern.

Parameters

For regular files, the file size in bytes.

For symbolic links, the length in bytes of the path-name contained in the symbolic link.

For a shared memory object, the length in bytes.

For a typed memory object, the length in bytes.

For other file types, the use of this field is unspecified.

filename	Optional string, is populated with the base filename; without any path.
size	Optional integer, if specified is populated with the size of the related file in bytes.
mtime	Optional integer, populated with the files modification time (See: time).
ctime	Optional integer, populated with the time of the last status change.
mode	Mode of file (See: stat).

Returns

Returns zero if there are no more files; returns 1 if next directory entry successfully received.

Portability

The mtime, ctime and mode parameters are GriefEdit extensions.

find_file2

int find_file2( string filename,
[int &size],
[int &mtime],
[int &ctime],
[int &atime],
[int &mode],
[int &uid],
[string &uid2name],
[int &gid],
[string &gid2name],
[int &nlink],
[int &inode] )

Extended read next directory entry.

Description

The find_file2() primitive is an extended version of find_file returning additional file information on which matching file.

Parameters

For regular files, the file size in bytes.

For symbolic links, the length in bytes of the path-name contained in the symbolic link.

For a shared memory object, the length in bytes.

For a typed memory object, the length in bytes.

For other file types, the use of this field is unspecified.

filename	Optional string, is populated with the base filename; without any path.
size	Optional integer, if specified is populated with the size of the related file in bytes.
mtime	Optional integer, populated with the files modification time (See: time).
ctime	Optional integer, populated with the time of the last status change.
atime	Optional integer, populated with the last access time.
mode	Optional integer, mode of file (See: stat).
uid	Optional integer, user identifier of the file.
uid2name	User name associated with the file uid.
gid	Optional integer, group identifier of the file.
gid2name	Group name associated with the file gid.
nlink	Optional integer, number of hard links to the file.
inode	Optional integer, populated with the file-system internal node number.

Returns

Returns zero if there are no more files; returns 1 if next directory entry successfully received.

Portability

A GriefEdit extension.

find_line_flags

int find_line_flags( [int bufnum],
[int lineno],
int mode,
int and_mask,
[int or_value],
[int value] )

Locate next line with specific flags.

Description

The find_line_flag() primitive positions the cursor at the next line which matches the specified flag value.

bufnum and lineno allow explicit buffer and line number references to be stated, otherwise if omitted the current buffer and/or associated line number shall be used.

flags defines direction and type of equivalence test to be utilised. and_mask and or_value parameterise the equivalence expression.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
lineno	Starting line number.
mode	Search mode flags.

LF_FORWARDS	Forward search (default).
LF_BACKWARDS	Backwards search.
LF_MATCH_EQ	Absolute value match against the line flags AND’ed against and_mask and then OR’ed against or_value. ie. ((flags & and_mask) \| or_value) == value)
LF_MATCH_ANY	Match line flags were any flags contained within the and_mask are set, ie. ((flags & and_masK) != 0).

and_maskAND mask.or_valueOR value during LF_MATCH_EQ operations.valueValue being matched during LF_MATCH_EQ operations.

Returns

The find_line_flag() primitive returns the matched line number, 0 if not suitable match was found, otherwise -1 on error, for example invalid parameters.

find_macro

string find_macro( string filename )

Determine path of a macro object.

Description

The find_module resolves the full-path to the macro object filename. Using the same mechanism as load_macro, the macro object search path environment variable GRPATH is utilised to search for the specified macro object.

Parameters

filename

String containing the macro object to resolve. If the specified file has an extension, then an exact match is located. Otherwise files matching one of the following extensions are .cm, .cr, and .m are located.

Returns

The find_module returns a string containing the full-path to the resolved macro object, otherwise an empty string if the object could not be found.

Portability

n/a

find_marker

int find_marker( [int marker = L_MARKED] )

Locate next marker.

Description

The find_marker() primitive positions the cursor at the next line which has a user defined marker enabled. On successful completion the marker is removed.

marker is the optional marker against which to search, by default L_MARKED. Only L_MARKED or one of the L_USERx definitions maybe be specified, if other bits or more then one user bit is stated the search shall not succeed.

Returns

The find_marker() primitive returns 1 on success and 0 if no additional markers exist.

Compatibility

The marker parameter is a GriefEdit extension.

fioctl

int fioctl( int handle,
.. )

File miscellaneous control.

Description

The fioctl() primitive is reserved for future use.

Returns

Returns -1.

Portability

An experimental GriefEdit extension; functionality may change.

first_time

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.

Note:

A GRIEF macro compiler utilises this primitive to perform run-time initialisation of function static variables.

Parameters

none

Returns

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

Portability

n/a

firstof

int firstof( string str,
string chars,
[int &result] )

Leftmost character search.

Description

The firstof() primitive returns the offset to the first occurrence of any of the characters contained within chars in the string str.

If supplied, on success result shall be populated with the matching character otherwise is set if zero.

firstof() is similar to index yet allows multiple characters to be matched.

Parameters

str	String object to be searched.
chars	Character set to match against.
result	Optional result, populated with the matching character value.

Returns

The firstof() primitive returns the starting offset or 0 if non of the characters are found.

Portability

A GriefEdit extension.

flock

int flock( int handle,
.. )

File lock operations.

Description

The flock() primitive is reserved for future use.

Returns

Returns -1.

Portability

A GriefEdit extension.

Notes

The flock() primitive is reserved for future use, and currently returns -1 in all cases.

floor

float floor( float x )

Round down to integral value.

Description

The floor() primitive calculates the largest integer that is less than or equal to x.

Returns

Returns the calculated integral value expressed as a double, float, or long double value. The result cannot have a range error.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

fmktemp

int fmktemp( string template );

Make a unique filename.

Description

The fmktemp() primitive shall replace the contents of the string template by a unique filename, and return a stream for the file open for reading and writing.

The primitive is equivalent to the mkstemp().

The function thus prevents any possible race condition between testing whether the file exists and opening it for use. The string in template should look like a filename with six trailing X s; fmktemp replaces each X with a character from the portable filename character set.

The characters are chosen such that the resulting name does not duplicate the name of an existing file at the time of a call to fmktemp.

Returns

Upon successful completion, fmktemp() shall return an open stream and return the resulting filename. Otherwise, -1 shall be returned if no suitable file could be created.

Portability

A GriefEdit extension.

fmod

float fmod( float x,
float y )

Floating-point remainder.

Description

The fmod() primitive Calculates the floating-point remainder of x/y. The absolute value of the result is always less than the absolute value of y. The result will have the same sign as x.

Returns

If successful, the function returns the floating-point remainder of x/y.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

Dependent on the implementation if y is 0 one of two may occur,

fmod returns 0;
the function sets errno to EDOM and returns NaN.

No other errors will occur.

fopen

int fopen( string path,
int|string flags,
[int mode = 0644],
[int bufsiz] )

Open a stream.

Description

The fopen() primitive shall open the file whose pathname is the string path, and associates a stream with it.

The flags argument contains a string. If the string is one of the following, the file shall be opened in the indicated mode.

r	Open file for reading.
w	Truncate to zero length or create file for writing.
a	Append; open or create file for writing at end-of-file.
r+	Open file for update (reading and writing).
w+	Truncate to zero length or create file for update.
a+	Append; open or create file for update, writing at end-of-file.
wx	create text file for writing with exclusive access.
wbx	create binary file for writing with exclusive access.
w+x	create text file for update with exclusive access.
w+bx	create binary file for update with exclusive access.

Parameters

path	String containing either the full or relative path name of a file to be opened.
flags	Creation flags, see above.
mode	Optional creation mode.
bufsiz	Optionally stream buffer size, in bytes.

Returns

Upon successful completion, fopen() shall return a handle to the stream. Otherwise, -1 shall be returned, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

for

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

format

string format( string format,
... )

Formatted printing.

Description

The format() primitive produces formatted output according to the format specification format. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.

The format primitive is similar to the sprintf() primitive with the exception the formatted result is returned directly as a string.

This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.

Parameters

format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The format() primitive returns a string containing the formatted results, as defined by the format specification and the values contained within the associated arguments.

Portability

See message

fread

int fread( int handle,
string buffer,
[int bufsiz = BUFSIZ],
[int null = ' '] )

Read from a stream.

Description

The fread() primitive shall read into the array pointed to by ptr up to nitems elements whose size is specified by size in bytes, from the stream referenced by handle.

Parameters

handle	Stream handle.
buffer	String buffer to be written.
bufsiz	Optional length of buffer to be read.

Returns

Upon successful completion, fread() shall return the number of elements successfully read which is less than bufsiz only if a read error or end-of-file is encountered.

If nitems is 0, fread() shall return 0 and the contents of the array and the state of the stream remain unchanged. Otherwise, if a read error occurs, the error indicator for the stream shall be set, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

frexp

float frexp( float num,
int & exp )

Extract mantissa and exponent.

Description

The frexp() primitive breaks a floating-point number num into a normalised fraction and an integral power of 2. It stores the integer exponent in the int object exp.

An application wishing to check for error situations should set errno to 0 before calling frexp(). If errno is non-zero on return, or the return value is NaN, an error has occurred.

Returns

The frexp() primitive returns the value x, such that x is a double with magnitude in the interval [0.5, 1) or 0, and num equals x times 2 raised to the power exp.

If num is 0, both parts of the result are 0.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

fseek

int fseek( int handle,
int offset,
int whence )

Reposition a file-position indicator in a stream.

Description

The fseek() primitive shall set the file-position indicator for the stream pointed to by stream. If a read or write error occurs, the error indicator for the stream shall be set and fseek() fails.

The argument offset is the position to seek to relative to one of three positions specified by the argument whence.

SEEK_SET	The new file position is computed relative to the start of the file. The value of offset must not be negative.
SEEK_CUR	The new file position is computed relative to the current file position. The value of offset may be positive, negative or zero.
SEEK_END	The new file position is computed relative to the end of the file.

Parameters

handle	Stream handle.
offset	The new position, measured in bytes from the beginning of the file, shall be obtained by adding offset to the position specified by whence.
whence	The specified point is the beginning of the file for SEEK_SET, the current value of the file-position indicator for SEEK_CUR, or end-of-file for SEEK_END.

Returns

On success the fseek() functions returns, otherwise -1 and set errno to indicate the error.

Portability

A GriefEdit extension.

fstat

int fstat( int handle,
[int size],
[int mtime],
[int ctime],
[int atime],
[int mode],
[int uid],
[string uid2name],
[int gid],
[string gid2name],
[int nlink] )

Stream status information.

Description

The fstat() primitive obtain information about the file referenced by the handle handle.

This information is returned in the parameters following the handle parameter (if supported by the underlying filesystem)

size	Total file size, in bytes.
mode	File’s mode (See: chmod).
mtime	The files “last modified” time (See: time).
atime	Time the file was “last accessed”.
ctime	Time of the files “last status change”.
uid	user-id.
gid	group-id.
nlink	Number of hard links.

Returns

The fstat function returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

fstype

int fstype( [string path] )

File system type.

Description

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

Parameters

path	Optional string containing path on the file-system to be tested, if omitted the current working directory is referenced.

Returns

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

Portability

A GriefEdit extension.

ftell

int ftell( int handle )

Report the file-position indicator of a stream.

Description

The ftell() primitive shall obtain the current value of the file-position indicator for the stream pointed to by stream.

Returns

On successful completion, ftell() shall return the current value of the file-position indicator for the stream measured in bytes from the beginning of the file.

Otherwise, ftell() shall return -1, and set errno to indicate the error.

Portability

A GriefEdit extension.

ftest

int ftest( int|string condition,
string path )

Test file type.

Description

The ftest() primitive tests the type of the specified file path against the type condition. The file test operations are modelled on standard unix test operators as follows.

a	True if file exists.
b	True if file exists and is a block special file.
B	True if file exists and is a possible binary stream.
c	True if file exists and is a character special file.
d	True if file exists and is a directory.
e	True if file exists.
f	True if file exists and is a regular file.
g	True if file exists and its set group ID flag is set.
G	True if file exists and its group matches the effective group ID of this process.
h	True if file exists and is a symbolic link.
k	True if file exists and has its sticky bit set.
L	True if file exists and is a symbolic link.
N	True if file exists and has been modified since last access.
O	True if file exists and is owned by the effective user ID of this process.
p	True if file is a named pipe (FIFO).
r	True if file exists and is readable.
s	True if file exists and has a size greater than zero.
S	True if file exists and is a socket.
u	True if file exists and its set-user-ID flag is set.
w	True if file exists and is writable. True will indicate only that the write flag is on. The file will not be writable on a read-only file system even if this test indicates true.
x	True if file exists and is executable. True will indicate only that the execute flag is on. If file is a directory, true indicates that file can be searched.

Returns

The ftest() primitive returns the result of the test operation either 1 when true otherwise 0.

Portability

A GriefEdit extenions.

ftruncate

int ftruncate( int handle,
[int size] )

Truncate the specified file.

Description

The ftruncate() primitive cause the regular file referenced by handle to be truncated to a size of precisely length bytes.

If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes (\0).

The file offset is not changed.

With ftruncate(), the file must be open for writing.

Returns

The ftruncate function returns zero on success. When an error has occurred, errno contains a value indicating the type of error that has been detected

Portability

A GriefEdit extension.

Notes

The ftruncate() primitive is reserved for future use, and currently returns -1 in all cases.

fwrite

int fwrite( int handle,
string buffer,
[int length] )

Write to a stream.

Description

The fwrite() primitive shall write, from the string buffer, up to length, to the stream pointed to by handle. If omitted, length by default to the string current length.

The file-position indicator for the stream (if defined) shall be advanced by the number of bytes successfully written. If an error occurs, the resulting value of the file-position indicator for the stream is unspecified.

Parameters

handle	Stream handle.
buffer	String buffer to be written.
length	Optional length of buffer to be written.

Returns

The fwrite() primitive shall return the number of elements successfully written, which may be less than length if a write error is encountered.

If length is 0, fwrite() shall return 0 and the state of the stream remains unchanged. Otherwise, if a write error occurs, the error indicator for the stream shall be set, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

get_color

list get_color( [int flags = 0] )

Retrieve screen colors.

Description

The get_color() primitive retrieves the current display color scheme as a list of strings, each string containing the specification of an individual color attribute.

The reported specifications following the form based upon the optional flags.

[<id>,][<flags>,][<name>=]<spec>

id	Numeric identifier of the attribute.
flags	Control flags.
name	Attribute name.
spec	Color specification.

Color Specification

Each color specification followings the following form.

attribute=
     sticky@<attribute>|none
   | link@<attribute>|none
   | <foreground-color>[,<background-color>][|font][:style ...]
   | clear

Where colors take one the following forms, see set_color for a list of the reported attributes.

color-name|none
foreground|fg|background|bg|dynamic_fg|dyanmic_bg
decimal (xx), octal (0xxx) or hex (0x###)
#RRGGBB
color[#]ddd

style specifications are in the form :<style> [,<style> ...]

bold
inverse
underline
blink
italic
reverse
standout
dim
undercurl

Parameters

flags

Optional integer flags, one or more of the following flags OR’ed together control the components to be reported against each attribute.

Flags

Constant	Definition
COLORGET_FVALUE	Attribute numeric value/identifier.
COLORGET_FFLAGS	Type flags.
COLORGET_FNAME	Name.

Returns

Returns a list of colors associated with the color attributes.

If flags was specified then the color attribute flags are returned in a list, instead of the color names.

Example

Example list content using COLORGET_FNAME

"background=none"
"normal=none"
"select=light-cyan"
"message=light-green"
"error=light-red"
"hilite=red"
"hilite_fg=light-white"
"frame=white"
"inscursor=black"
"ovcursor=black"
"shadow=clear"
"prompt=light-magenta,dynamic-bg:link@message"
"question=clear:link@message"
"echo_line=yellow,dynamic-bg"
"statuscolumn=clear:link@message"
"linenocolumn=clear:link@message"
"nonbuffer=brown,dynamic-bg:link@message"
    :
    :

Portability

A GriefEdit extension.

get_color_pair

void get_color_pair( string name|int ident,
[int|string fg],
[int|string bg],
[int|string sf] )

Retrieve the specific color.

Description

The get_color_pair() primitive retrieves a specific attribute that GRIEF utilities on a color display. Attributes may be specified as integers or strings, with strings being case-insensitive see set_color for more details.

The specified attribute color values shall be assigned to the specified arguments foreground, backbround and style.

Parameters

ident	Attribute identifier.
fg	Optional variable reference to be populated with the foreground color. If an integer reference the numeric colour value is assigned otherwise if a string reference the associated name.
bg	Optional variable reference to be populated with the background color. If an integer reference the numeric colour value is assigned otherwise if a string reference the associated name.
sf	Optional variable reference to be populated with the style and flags. If an integer reference the numeric value is assigned otherwise when a string reference the human readable decoding version is assigned.

Returns

nothing

Portability

A GriefEdit extension.

get_mouse_pos

void get_mouse_pos( [int &x],
[int &y],
[int &winnum],
[int &line],
[int &col],
[int &where],
[int &region],
[int &event] )

Retrieve last mouse action.

Description

The get_mouse_pos() primitive retrieves the details of the last mouse action.

Note:

The details returned are only valid immediately after the macro assigned to a button press event. Any subsequent calls to read_char or process will overwrite the internal values.

Parameters

x, y	Screen coordinates.
winnum	Optional an integer variable which shall be populated with the window identifier within which the (x, y) position falls, otherwise -1 if no window was mapped.
line, col	Optional integer variables which shall be populated with the translated window coordinates, otherwise -1 if no window was mapped.
where	Where the cursor is located within the window.
region	Cursor position relative to any marked regions.
event	Associated mouse event.

Where

Value	Definition
MOBJ_NOWHERE	Not in any window.
MOBJ_LEFT_EDGE	Left bar of window.
MOBJ_RIGHT_EDGE	Right bar of window.
MOBJ_TOP_EDGE	Top line of window.
MOBJ_BOTTOM_EDGE	Bottom line of window.
MOBJ_INSIDE	Mouse inside window.
MOBJ_TITLE	On title.
MOBJ_VSCROLL	Vertical scroll area.
MOBJ_VTHUMB	Vertical scroll area.
MOBJ_HSCROLL	Horizontal scroll area.
MOBJ_HTHUMB	Horizontal scroll area.
MOBJ_ZOOM	Zoom button,
MOBJ_CLOSE	Close.
MOBJ_SYSMENU	System Menu.

Region

Value	Description
0	No region selected.
1	Cursor is before the region.
2	Cursor is inside the region.
3	Cursor is after the region.
4	Cursor is to the left of a column region.
5	Cursor is to the right of a column region.

Returns

nothing

Portability

n/a

get_nth

declare get_nth( int idx,
list expr )

Retrieve a list element.

Description

The get_nth() primitive retrieves the element positioned at offset idx within the specified list expression expr.

Note:

This primitive is generally not utilised directly as the GRIEF language supports list offset operator of the form [idx].

Returns

The get_nth() primitive returns the value of the referenced element, otherwise NULL if the index is out of bounds.

Portability

n/a

get_parm

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.

Key	Function
Right, Left	Move cursor the back/forward one character.
Ctrl+Right, Ctrl+Left	Move cursor the start/end of the current word.
Home, End	Move to first/last character within the edit field.
Alt+I, Ctrl-O	Toggle insert/overstrike mode.
DEL	Delete character under the cursor.
Backspace, Ctrl+H	Delete character prior to the cursor.
Alt+K	Delete from cursor to the end of line.
Insert	Paste from scape.
Backspace, Ctrl+H	Delete character prior to the cursor.
ESC	Abort current edit, restoring original content.
Alt-D	Delete current line.
Alt-K	Delete from cursor to the end of line.
Alt+Q, Ctrl+Q	Quote next character.
Enter	Process change.
ALT+H	Help.
Ctrl+A (*)	Move cursor to beginning of line.
Ctrl+D (*)	Delete character under cursor.
Ctrl+K (*)	Delete from cursor to the end of line.
Ctrl+X, Ctrl+U (*)	Delete current line.
Ctrl+V, Ctrl+Y (*)	Paste from clipboard.

(*) Emacs style key mappings.

Note:

Arguments passed to macros are passed as call by name, that is every time a get_parm is issued against a particular parameter, that parameter is re-evaluated.

This lazy evaluation has a number of implications.

The order of parameter evaluation is dependent on the get_parm execution order within the called macro, not the arguments position.
Each parameter may be evaluated several times.
Parameters may never be evaluated, which is again dependent on the logic placed around get_parm usage.

This feature can be very useful sometimes, and at other times it can cause anomalous side-effects ((see Lazy Evaluation )).

Parameters

argument	An integer stating the associated macro argument index to be retrieved, starting at an offset of zero for the first parameter.
symbol	Specifies the symbol reference into which the resulting parameter shall be stored.
prompt	Option string which specifies the prompt which is represented to the user. If the prompt is omitted, the user is not prompted.
length	Optional integer parameter that specifies the upper limit of the string length that is to be retrieved. When given as 1 then single character mode is implied unless overriden using the one parameter. If omitted the upper length is assumed to be MAXPROMPT.
default	An optional value, whos type should match the type of symbol, if specified contains the value which shall initially be placed on the command line if a prompt is required.
one	Optional integer flag, if specified as non-zero than the user shall be prompted for a single character. Generally the user must complete the input using an enter, whereas in single character mode the first key is taken as the input. In addition, single character mode disables the execution of the _prompt_begin and _prompt_end callbacks plus any associated prompt history. If omitted the character mode shall be implied from the specified length; a length of 1 being true otherwise false.

Returns

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

Return	Description
0	Abort, invalid argument or conversion error.
1	Success.
2	Default was assigned (extension).

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.

get_property

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

obj_id	Dictionary identifier.
key	Item key.

Returns

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

Portability

A GriefEdit extension.

get_region

int get_region( [int bufnum] )

Retrieve marked region content.

Description

The get_region() primitive is similar to copy yet is copies the content of the current marked region and returns the result as a string.

Parameters

bufnum

Optional window identifier, if omitted the current buffer is referenced.

Returns

The get_region() primitive returns the content of the current marked region as a string, otherwise an empty string.

Portability

n/a

get_term_characters

list get_term_characters( [top_left],
[top_right],
[bottom_left],
[bottom_right],
[vertical],
[horizontal],
[top_join],
[bottom_join],
[cross],
[left_join],
[right_join],
[scrol],
[thumb] )

Retrieve terminal special characters.

Description

The set_term_characters() primitive retrieves the set of characters which are utilised by the tty console driver to represent window borders.

set_term_characters() operators in one of two modes. Without arguments a list of strings, one for each character is retrieved. Alternatively each parameter is either an integer or string variable to be populated with the associated character value. Values can be omitted by supplying a NULL parameter against the associated character index.

Refer to set_term_characters for the order and meaning of each of these characters.

Parameters

...	Integer character value or string escape sequence, one for each character within the set.

Returns

Without any arguments the get_term_characters primitive returns a list of strings, one for each terminal character, in the form name=value. Otherwise a NULL list is returned.

Portability

n/a

get_term_feature

int get_term_feature( string | int ident,
declare value )

Get value of a terminal feature.

Description

The get_term_feature() primitive retrieves the value associated with the specified attribute ident.

Parameters

ident	Either the integer identifier or the a string containing the name of the terminal attribute to be retrieved.
value	Variable to populated with the referenced attribute.

Returns

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

Portability

A GriefEdit extension.

get_term_features

list get_term_features( ... )

Retrieve terminate features.

Description

The get_term_features() primitive retrieves a list of string pairs one for each terminal attribute.

Parameters

none

Returns

Without any arguments the get_term_features() primitive returns a list of strings, one for each terminal attribute, in the form name=value. Otherwise a NULL list is returned.

Portability

Many of the return values are only meaningful on systems that use a tty based console interface.

The CRiSPEdit™ version is similar to get_term_feature.

get_term_keyboard

list get_term_keyboard()

Retrieve the terminal keyboard definitions.

Description

The get_term_keyboard() primitive retrieves the current terminal keyboard definition.

Under Unix™ console attributes are derived from the system termcap or terminfo databases or similar interfaces under non-unix systems.

See get_term_keyboard for further details.

Parameters

none

Returns

The get_term_keyboard() primitive returns a list of key binding pairs, each pair consisting of an integer key-code plus a string containing the associated escape sequence.

Portability

On systems not utilising a tty based console interface, the list shall be empty.

getenv

string getenv( string name )

Retrieve an environment variable.

Description

The getenv() primitive searches the environment of the calling process for the environment variable name if it exists and returns the value of that environment variable. If the specified environment variable cannot be found, an empty string shall be returned.

Parameters

name	String containing the name of the environment variable.

Returns

The getenv() primitive returns the value of the corresponding environment variable, otherwise an empty string.

Portability

n/a

geteuid

int geteuid()

Retrieve the effective user identifier.

Description

The geteuid() primitive shall return the effective user ID of the calling process.

Parameters

none

Returns

The geteuid() primitive shall always be successful returning the current effective user identifier.

Portability

n/a

getopt

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]]"

tag	Option tag or name.
value	Index value returned upon an option match. The value is either a character or a numeric denoted by a leading #. If omitted the index shall be taken as the next within the sequence either following the previous index or using the opening index of zero(0).
operator	Defines whether the value is optional (=) or required (:). If omitted, it is assumed no value is required.
type	Optional value type against which the value shall be validated, stated as either a single character or it equivalent full name.

a[nything]	Anything.
s[tring]	String.
c[haracter]	Character value.
i[integer][+]	Decimal integer value plus optional positive only modifier.
n[numeric][+]	Numeric (oct, dec and hex).
f[loat]	Floating point including integer.
d[ouble]	Double precision floating point including integer.
b[oolean]	Boolean, 0/1, y[e]s/n[o], on/off, true/false; result being a string containing 0 or 1.

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.

-1	End of the options (EOF).
-2	Unknown option.
-3	Ambiguous option.
-4	Argument required.
-5	Unexpected argument.
-10	Invalid value, for example “expected a numeric value”.
-99	Invalid option specification.

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);
}

getpid

int getpid()

Retrieve the process identifier.

Description

The getpid() primitive shall return the process ID of the calling process.

Parameters

none

Returns

The getpid() primitive shall always be successful returning the current process identifier.

Portability

n/a

getsubopt

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

options	Option declaration list of one more strings of the following form “tag[, index][[:=][type]]”, see below for more details.
value	Tag value, otherwise set to an empty string.
args	Argument buffer to be processed. Note, on success the buffer shall be modified with the leading matched option and trailing value removed.
delim	Optional delimiter, if omitted defaults to a comma(,).

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,

-1	End of the options (EOF).
-2	Unknown option.
-4	Argument required.
-5	Unexpected argument.
-6	Invalid value, for example “expected a numeric value”.
-10	Invalid option specification.

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);
}

getuid

int getuid()

Retrieve the user identifier.

Description

The getuid() primitive shall return the real user ID of the calling process.

Parameters

none

Returns

The getuid() primitive shall always be successful returning the current user identifier.

Portability

n/a

getwd

int getwd( int ignored,
string dir )

Get current working directory.

Description

The getwd() primitive primitive retrieves the name of the current working directory.

The ignored parameter exists for compatibility with BRIEF.

Returns

The getwd() primitive returns 1 if successful otherwise zero on error. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

glob

string glob( string pattern )

Generate pathnames matching a pattern.

Description

The glob() primitive expands the specified pattern into single string similar to that which occurs on the shell command line.

*	Match any string of characters.
[]	Character class.
?	Match any single character.
~	User name home directory.
\x	Quote the next metacharacter x.

Returns

The glob() primitive returns a string containing the result of the pattern expansion on success, otherwise an empty string.

Portability

A GriefEdit extension.

global

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.

Note:

Both global and _init are considered as internal primitives, reserved for exclusive use by the GRIEF Macro Compiler and may change without notice.

Management of variable scoping and argument binding shall be handling automatically by the compiler.

Returns

nothing

Portability

n/a

gmtime

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.

Description

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.

Returns

The gmtime function returns the value of time in seconds since the Epoch which the components represent.

Portability

A GriefEdit extension

goto_bookmark

int goto_bookmark( int bookid = NULL,
[int &bufnum],
[int &line],
[int &column]    )

Seek a bookmark.

Description

The goto_bookmark() primitive changes the current buffer and cursor location to the values associated with the named bookmark.

bookid is the unique identifier or name associated with the bookmark; any valid integer may be used as the identifier. If omitted the user shall be prompted for the bookmark identifier.

Go to bookmark:

If any of the arguments bufnum, line or column are specified, these are modified to contain the related bookmark values without effecting the current buffer or location. If all are omitted the bookmark is applied, updating the buffer and/or cursor location as required.

Parameters

bookid	Bookmark identifier.
bufnum	Optional integer reference, if specified shall be populated with the associate buffer number.
line	Optional integer reference, if specified shall be populated with the buffer line number.
column	Optional integer reference, if specified shall be populated with the buffer column number.

Returns

The goto_bookmark() primitive returns a non-zero value and populate any of the supplied arguments bufnum, line and col. Otherwise on error returns zero and a related error shall be displayed.

No such bookmark

goto_bookmark: No such buffer

Examples

The following two examples deal with the bookmark labelled as 9.

Retrieves the bookmark definition and echos the details to the user.

int buf, line, column;

goto_bookmark(9, buf, line, column);
message("bookmark: buf=%d, %d/%d", buf, line, column);

Applies the bookmark definition.

goto_bookmark(9);

Portability

n/a

goto_line

int goto_line( [int lineno] )

Move to a particular line.

Description

The goto_line() primitive repositions the cursor to tbe beginning of the specified line lineno.

Parameters

lineno

Specifies the line number which to relocate the cursor, if omitted the user is prompted.

Returns

The goto_line() primitive returns true if successful, otherwise zero or less if unsuccessful.

Portability

n/a

goto_old_line

int goto_old_line( [int oldlineno] )

Move to line before buffer modification.

Description

The goto_old_line() primitive repositions the cursor as close as possible to the beginning of the specified line oldlineno, representing the line prior to any buffer modifications.

For each buffer the previous line numbers are retained for any one edit session, that is they are maintained until the buffer is saved, at which point line references are reset to the resulting new image.

This primitive is provided for seeking lines within a buffer that are referred to in an external listing. For example within a previous compiler error report yet since that time inserts and/or line deletes have occurred to the source, yet despite these edits the original line can still be addressed.

Parameters

oldlineno

Specifies the old line number which to relocate the cursor, if omitted the user is prompted.

Returns

The goto_old_line() primitive returns true if successful, otherwise zero or less if unsuccessful.

Portability

n/a

grief_version

int grief_version()

GRIEF version.

Description

The grief_version() primitive retrieves the current GRIEF version.

Parameters

none

Returns

The grief_version primitive returns the current version multiplied by 100 plus the minor; for example 101 represents version 1.1.

Portability

A GriefEdit extension.

hilite_create

int hilite_create( [int bufnam],
[int type],
[int timeout],
[int sline],
[int scol],
[int eline],
[int ecol],
[string | int attr],
[int ident] )

Create a hilite resource.

Description

The hilite_create() primitive creates a buffer hilite resource with the referenced buffer bufnum under the classification type; the given classification groups hilite resources allowing bulk management and removal.

Similar to the buffer anchors yet they can not be edited and there maybe as many as desired hilite’s are available for use by macros to mark elements within documents, for example search results.

The created resource decorators the region for the duration timeout between the stated starting position sline, eline upto the ending position eline, ecol using the display attribute attr.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
type	Optional type, default 0; user assignable label.
timeout	Specifies a timeout in seconds. If specified then the hilite shall be automatically deleted upon the timeout expiring. A timeout of -1 implies on next buffer change.
sline, scol	Start of the hilite region.
eline, ecol	End for the hilite region.
attr	Associated attribute.
ident	User assigned identifier.

Returns

The hilite_create() primitive returns the unique hilite identifier, otherwise -1 on error.

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

hilite_delete

int hilite_delete( [int bufnum],
int hilite )

Delete a hilite resource.

Description

The hilite_delete() primitive removes the stated hilite’s hilite from the associated with the buffer bufnum.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
hilite	Unique hilite identifier which are returned during the hilite’s corresponding creation by hilite_create.

Returns

The hilite_delete() primitive returns 1 if the hilite existed and was removed successfully, 0 if the hilite did not exist, otherwise -1 on error.

Portability

A GriefEdit extension.

hilite_destroy

int hilite_destroy( [int bufnum],
[int type] )

Destroy hilite resources.

Description

The hilite_destroy() primitive either removes hilite’s of the specified type otherwise if omitted all hilite’s associated with the buffer bufnum.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
type	Optional hilite type, if omitted all buffer hilite’s are released.

Returns

The hilite_destroy() primitive returns the number of hilite’s removed, 0 if none were found, otherwise -1 on error.

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

if

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 }

index

int index( string str,
int ch|string s )

Search string for a leftmost sub-string or character.

Description

The index() primitive returns the offset to the first occurrence of the character ch or the string s in the string str.

Parameters

str	String object to be searched.
ch\|s	Object to be matched against.

Returns

The index() primitive returns the starting offsetr or 0 if the character or string was not found.

Portability

The character needle form is a GriefEdit extension.

input_mode

int input_mode( int char,
int flag )

Effect of certain system keys.

Description

The input_mode() primitive controls the effect of certain characters when typed, setting the actions of character char to the desired state.

Normally the keyboard driver acts internal on specific characters which perform the control actions of XON/XOFF and the Job control stop; specifically Ctrl-S (0x13), Ctrl-Q (0x11) and Ctrl-Z (0x1a).

Parameters

char	Integer value of the ascii character to be effected.
flags	Boolean flag, if true enable the specified character to flow thru to GRIEF otherwise false to reset the default behaviour.

Returns

The input_mode() primitive returns 1 if character previously enabled; zero otherwise.

Portability

n/a

inq_assignment

string inq_assignment( int|string val,
[int tokey = FALSE] )

Get key assignment for function.

Description

The inq_assignment() primitive either retrieves the command that is assigned to the particular key val or the key sequence(s) that will invoke a specific command.

Parameters

val	String denoting the key sequence to be decoded or an integer representing the internal key code. The string representation should be of the form described by assign_to_key.
tokey	Optional boolean value, if true then val is taken as a macro name and the keys assigned to invoke this macro are returned. The key assignment returned is returned using the portable key definitions defined for assign_to_key.

Returns

The inq_assignment() primitive returns a string containing the desired conversion.

For key sequence to command: the name of the command; OR “nothing” if no command is assigned; OR “ambiguous” if there is more than key sequence starting with the val.

For command to key sequence enabled when tokey is non-zero

a list of the valid key sequences for the command. The list elements are formatted with the following separators:

-or	Separates different ways of specifying a single key.
-and	Separates keys in a multi-key sequence.
-also	Separates multiple (different) key sequences.

Portability

n/a

inq_attribute

int inq_attribute( [int &normal],
[int bufnum] )

Retrieve the current attributes.

Description

The inq_attribute() primitive retrieves the text and optionally the normal attribute for the specified buffer bufnum.

Parameters

normal	Optional integer reference, if stated is populated with the clear/normal attribute value.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_attribute() primitive returns the current text attribute, otherwise -1 on error.

Portability

A GriefEdit extension.

inq_backup

int inq_backup( [int bufnum] )

Get the backup creation mode.

Description

The inq_backup() primitive retrieves the value of the associated objects backup mode. If bufnum is specified, then the value of the stated buffer is returned, otherwise upon being omitted the global (default) backup mode shall be returned.

Returns

The inq_backup() primitive returns the current value of the backup flag.

Portability

A GriefEdit extension.

inq_backup_option

declare inq_backup_option( int what,
[int bufnum] )

Get backup options.

Description

The inq_backup_option() primitive retrieves the value of the backup option what for the associated object. If bufnum is specified, then the value of the stated buffer is returned, otherwise upon being omitted the global (default) backup option shall be modified.

Returns

The inq_backup_option() primitive returns the current value associated with the attribute what, as follows

BK_MODE - Backup creation mode, as an integer.
BK_AUTOSAVE - Buffer autosave flag, as an integer.
BK_DIR - Backup directory, as a string.
BK_DIRMODE - Directory creation mode, as an integer.
BK_VERSIONS - Number of versions to be maintained, as an integer.
BK_PREFIX - Backup filename prefix, as a string.
BK_SUFFIX - Backup filename suffix, as a string.
BK_ONESUFFIX - Whether only a single suffix to used replacing any existing, as an integer.
BK_ASK - Filesize watermark at which point backups shall be prompted before created a backup image, as an integer.
BK_DONT - Filesize watermark at which point backups shall not be created regardless of the current backup mode, as an integer.

Portability

A GriefEdit extension.

inq_borders

int inq_borders()

Retrieve the border status.

Description

The inq_borders() primitive retrieves the border status which controls whether or not tiled windows are displayed with borders.

Disabling borders can improve display performance on slow systems, yet shall disable scroll bars, title bars and may make working with multiple windows difficult.

Parameters

none

Returns

Returns non-zero if windows borders are enabled, otherwise zero if disabled.

Portability

n/a

inq_brief_level

int inq_brief_level()

Retrieve the editor nesting level.

Description

The inq_brief_level() primitive retrieves the number of copies of GRIEF running within the current session.

The original implementation returned the total number of instances in memory, whereas this emulation only reports the number of instances visible with the associated terminal.

This function is provided for compatibility using the getenv interface; see the getenv primitive and the brief macro module for details.

Parameters

none

Returns

The current number of active editor sessions.

Portability

Provided for BRIEF compatibility, retrieving the current GRLEVEL environment variable level.

inq_btn2_action

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

inq_buffer

int inq_buffer( [string filename] )

Retrieve a buffer identifier.

Description

The inq_buffer() primitive retrieves either the identifier associated with the buffer containing the specified file filename, otherwise if omitted the identifier of the current buffer.

Parameters

bufname

Optional string containing the file name to be matched against existing buffers.

Returns

The inq_buffer() primitive returns the unique identifier associated with the referenced file or the current buffer if no file_name was specified. If the specified file_name was not matched, zero is returned.

If omitted then the current buffer is returned.

Portability

Unlike BRIEF partial matches do not occur.

inq_buffer_flags

int inq_buffer_flags( [int bufnum],
[string flag|int set = 1],
[string ~flags] )

Retrieve buffer flags.

Description

The inq_buffer_flags() primitive retrieves one of the set of flags associated with the specific buffers, see Buffer Flags.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
flag/set	Optional internal set identifier, if omitted the primary set(1) shall be referenced.
...	Optional string of comma separated flag names.

Flags

The following table summaries the existing flags, for additional on a specific flag consult the set_buffer_flags primitive.

Returns

The inq_buffer_flags() primitive returns the value associated with the selected set of flags.

Portability

The string flag parameter variant is a GRIEF extension.

Many of the flags are GRIEF specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.

inq_buffer_title

string inq_buffer_title( [int bufnum] )

Retrieve a buffer title.

Description

The inq_buffer_title() primitive retrieves the title associated with the specified buffer.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

String containing the current buffer title.

Portability

n/a

inq_buffer_type

int inq_buffer_type( [int bufnum],
[string &desc],
[string &encoding] )

Retrieve buffer type.

Description

The inq_buffer_type() primitive retrieves the buffer type of the buffer bufnum.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
desc	Optional string variable reference to be populated with the buffer encoding description.
encoding	Optional string variable reference to be populated with the buffers character encoding name.

Returns

The inq_buffer_type() primitive returns on the following manifest constants representing the base encoding of the referenced buffer.

Buffer Types

The following manifest constants define the available Buffer Types.

Constant	Description
BFTYP_UNKNOWN	Unknown buffer type.
BFTYP_UNIX	Unix, LF line termination.
BFTYP_DOS	DOS, CF/LF line termination.
BFTYP_MAC	Old style MAX, CR termination.
BFTYP_BINARY	Binary.
BFTYP_ANSI	ANSI.
BFTYP_EBCDIC	EBCDIC.
BFTYP_UTF8	UTF8.
BFTYP_UTF16	UTF16/USC2.
BFTYP_UTF32	UTF32/USC4.
BFTYP_UTFEBCDIC	UTF8/EBCDIC.
BFTYP_BOCU1	Binary Ordered Compression for Unicode.
BFTYP_SCSU	Standard Compression Scheme for Unicode.
BFTYP_UTF7	7-bit Unicode Transformation Format.
BFTYP_GB	GB.
BFTYP_BIG5	BIG5.
BFTYP_ISO2022	ISO-2022.
BFTYP_SBCS	Single Byte.
BFTYP_DBCS	Double Byte.
BFTYP_MBCS	Multi-Byte (Non Unicode).
BFTYP_OTHER	Other supported.
BFTYP_UNSUPPORTED	Known file-type, yet no internal support.

Portability

n/a

inq_byte_pos

int inq_byte_pos( [int bufnum],
[int line],
[int col],
[int flags] )

Get current position in buffer stream.

Description

The inq_byte_pos() primitive is reserved for future compatibility.

The inq_byte_pos() primitive calculates and returns the byte offset from the start of the specified buffer with the first byte within the underlying buffer being at offset 0.

This primitive is similar the native library function tell.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
line	Optional line number.
col	Optional column.
flags	Offset origin flag, omitted when 0x00.

Returns

The inq_byte_pos() primitive returns the current value of the file-position indicator for the associated buffer measured in bytes from the beginning of the file. Otherwise, it returns -1 on error.

Portability

n/a

inq_called

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.

inq_char_map

int inq_char_map( [int winnum],
[string &name] )

Retrieve the character-map.

Description

The inq_char_map() primitive retrieves the current character-map identifier of the underlying buffer, otherwise if none is associated with the specified window. If the window identifier is omitted, the current window shall be queried.

Parameters

winnum	Optional window identifier, if omitted the current window shall be referenced.
name	Optional string referenced, if specified shall be populated with the assigned character-map name.

Returns

The inq_char_map() primitive returns the associated character-mapid otherwise -1 if one is not assigned.

Portability

The name parameter is a GRIEF extension.

inq_char_timeout

int inq_char_timeout()

Get the escape delay.

Description

The inq_char_timeout() primitive retrieves the current value of the terminal escape delay.

Parameters

none

Returns

The inq_char_timeout() primitive returns the current character timeout.

Portability

A GriefEdit extension

inq_clock

int inq_clock()

Retrieve the user identifier.

Description

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.

Parameters

none

Returns

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.

Portability

n/a

inq_cmd_line

string inq_cmd_line()

Retrieve the command line message.

Description

The inq_cmd_line() primitive returns the current prompt response displayed on the message line.

Parameters

none

Returns

The inq_cmd_line returns a string containing the current prompt.

Portability

n/a

inq_color

string inq_color( [int &background],
[int &normal],
[int &selected],
[int &messages],
[int &errors],
[int &hilite],
[int &hilite_fg] )

Retrieve the basic colors.

Description

The inq_color() primitive retrieves color details of the primary color attributes. inq_color is only intended for use with the basic color set and is provided only for backward compatibility.

The alternative interfaces of get_color, set_color, set_color_pair and get_color_pair are the preferred interfaces for new macros.

Parameters

background	Background color.
normal	Normal text color.
selected	Highlighting color for the selected window title.
message	Normal messages.
error	Error messages.
hilite	Color of marked areas. The value either states both the foreground and background of the marked areas as high nibble is background and the low is foreground. Unless hilite_fg is stated in which case only the foreground.
hilite_fg	Foreground color of marked areas.
frame	Window frame.

Returns

The inq_color() primitive returns a string containing the current color specification, being a space seperated list of color names

Portability

n/a

inq_command

string inq_command()

Retrieve name of last keyboard command.

Description

The inq_command() primitive retrieves the name of last command invoked from keyboard.

Commands with names beginning with an underscore (_) are ignored.

Parameters

none

Returns

The inq_command() primitive returns a string containing the name of the last macro called by the user.

Portability

n/a

inq_ctrl_state

int inq_ctrl_state( int ctrl,
[int winnum] )

Retrieve the state of a window control.

Description

The inq_ctrl_state() primitive retrieves the state of a window control of the specific window, if omitted the current window.

Parameters

ctrl	Control identifier; see set_ctrl_state for details.
winnum	Optional window identifier, if omitted the current window shall be referenced.

Returns

The return value depends on the specified control.

CLOSE_BTN, ZOOM_BTN, VERT_SCROLL, and HORZ_SCROLL

0	Disabled.
1	Enabled.
-1	Hidden globally.
-2	Hidden explicitly for this window.
-3	Hidden globally and explicitly.

VERT_THUMB and HORZ_THUMB,

-1	Disabled.
n	The position (percentage) of the thumb on the scroll bar, with a value 0 thru to 100.

Portability

n/a

inq_debug

int inq_debug()

Retrieve the current debug setting.

Description

The inq_debug() primitive retrieves the current debug flags.

Returns

The inq_debug() primitive returns an integer representing the debug flags which are currently in effect.

Example

Enable debug of regular expressions, invoke our macro for testing and then restore the previous flags.

int odebug = inq_debug();
debug(odebug | DB_REGEXP, FALSE);
myfunction();
debug(odebug, FALSE):

inq_dialog

int inq_dialog()

Retrieve the current dialog resource.

Description

The inq_dialog() primitive retrieves the resource handle of the current executing dialog source (if any), otherwise zero.

Parameters

none

Returns

The inq_dialog() primitive returns an integer representing the dialog resource handle (See: dialog_create) for more details.

Portability

A GriefEdit extension.

inq_display_mode

int inq_display_mode( [string flagname],
[string ~flags] )

Inquire display control flags.

Description

The inq_display_mode() primitive retrieves the value of the associated display attribute, given by the parameter flagname.

Name	Constant	Description
window	DC_WINDOW	Running under a windowing system (ro).
mouse	DC_MOUSE	Mouse enabled/available (ro).
readonly	DC_READONLY	Read-only mode (ro).
charmode	DC_CHARMODE	Character-mode with basic GUI features (ro
shadow	DC_SHADOW	Display shadow around popups.
showthru	DC_SHADOW_SHOWTHRU	Show-thru shadow around popups.
statusline	DC_STATUSLINE	Status line.
unicode	DC_UNICODE	UNICODE character encoding available (ro).
asciionly	DC_ASCIIONLY	ASCII only characters witihin UI/dialogs.
rosuffix	DC_ROSUFFIX	Read-only suffix on titles.
modsuffix	DC_MODSUFFIX	Modified suffix.
eof_display	DC_EOF_DISPLAY	Show <EOF> marker.
tilde_display	DC_TILDE_DISPLAY	Show ~ marker.
eol_hilite	DC_EOL_HILITE	Limit hilites to EOL.
himodified	DC_HIMODIFIED	Hilite modified lines.
hiadditional	DC_HIADDITIONAL	Hilite additional lines.
scroll_cols	n/a	Scroll jump column override.
scroll_rows	n/a	Scroll Jump row override.
visible_cols	n/a	Visible display window width lower bounds.
visible_rows	n/a	Display window height lower bounds.
number_cols	n/a	Line number column width override.

Parameter

flagname	Optional string parameter, if stated gives the name of the attribute to be retrieved (See: display_mode). If omitted the display mode are retrieved.
flags	Optional string parameter, if stated shall be populated with a comma separated list of active attribute names.

Returns

The inq_display_mode() primitive returns the value of the associated attribute, otherwise -1 on error.

Portability

GriefEdit extended.

For system portability use of the manifest constants is advised.

inq_echo_format

int inq_echo_format()

Retrieve the echo-line format.

Description

The inq_echo_format() primitive retrieves the current echo-line format specification.

Parameters

none

Returns

The inq_echo_format returns the current echo line format specification string, otherwise an empty string.

Portability

A GriefEdit extension.

inq_echo_line

int inq_echo_line()

Retrieve the echo-line flags.

Description

The inq_echo_line() primitive retrieves the current echo-line flags.

Parameters

none

Returns

The inq_echo_line() primitive returns the current echo_line flags.

Portability

A GriefEdit extension.

inq_encoding

string inq_encoding( [int bufnum] )

Retrieve a buffers character encoding.

Description

The inq_encoding() primitive retrieves the character encoding associated with the referenced buffer. See set_encoding for possible encodings.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_encoding() primitive returns the associated encoding.

Portability

A GriefEdit extension.

inq_feature

int|list inq_feature( [int|string feature],
[string value] )

Retrieve an editor feature.

Description

The inq_feature() primitive tsets the status of the specific feature feature, returning its current configuration value.

Warning:

The inq_feature() primitive is an experimental interface and may change without notice.

Parameters

feature	Name of the feature.
value	Configuration value.

Return

The inq_feature() primitive returns non-zero on success, otherwise zero on error.

Macro Portability; A GriefEdit extension.

inq_file_change

int inq_file_change( [int bufnum] )

Determine state of underlying file.

Description

The inq_file_change() primitive determines the state of the file which underlies the specified buffer bufnum. This primitive checks whether the associated file has been modified or deleted.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_file_change() primitive returns the reason code for the file state change.

0	No change.
1	File status detected; possible in-place changes.
2	File modified, size differences detected.
3	Underlying file does not exist (i.e. has been deleted).
-1	Unknown error, the cause of the error condition can be derived from the system return code (See: errno).

Portability

A GriefEdit extension.

inq_file_magic

string inq_file_magic( [int &isdefault] )

Retrieve the file type detection rules.

Description

The inq_file_magic primitive retrieves the current file character encoding detection rules. The returned shall contain one or comma separated detector names with optional arguments, see set_file_magic.

Example

mark,utf8,udet,xascii,ascii

Parameters

n/a

Returns

The inq_file_magic() primitive returns a string containing the current encoder specification.

Portability

A GriefEdit extension.

inq_font

int inq_font( string & normalfont,
[string &italicfont] )

Inquire the current window fonts.

Description

The inq_font() primitive retrieves the active normal and/or italic font of the current running GriefEdit image.

Note:

Only available when running under a suitable windowing system, otherwise this primitive is a no-op.

Parameters

normalfont	Optional string variable reference to be populated with the normal text font name.
italicfont	Optional string variable reference to be populated with the italic text font name.

Returns

The inq_font() primitive returns zero or greater on success, otherwise -1 on error.

Portability

GriefEdit extended.

inq_hilite

int inq_hilite( [int bufnum],
[int line],
[int column],
[int &attribute],
[int &ident] )

Retrieve a hilite definition.

Description

The inq_hilite() primitive retrieves details about the hilite resource at the specified position.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
line	Optional integer line number within the referenced buffer, if omitted the current line number is used.
column	Optional integer column number within the referenced buffer, if omitted the current column number is used.
attribute	Optional integer variable, if specified shall be populated with the hilite assigned attribute.
indent	Optional integer variable, if specified shall be populated with the hilite user assigned user identifier.

Returns

The inq_hilite() primitive returns the type of the active hilite and populates attribute and ident, otherwise -1 and the arguments shall remain unmodified..

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

inq_home

string inq_home()

Retrieve the user home directory.

Description

The inq_home() primitive retrieves the current users home directory.

Parameters

none

Returns

The inq_home() primitive returns a string containing the users home directory.

Portability

A GriefEdit extension.

inq_hostname

string inq_hostname()

Retrieve the local host name.

Description

The inq_hostname() primitive retrieves the name of the local host.

Parameters

none

Returns

The inq_hostname() primitive returns a string containing the local host name.

Portability

A GriefEdit extension.

inq_idle_default

int inq_idle_default()

Retrieve idle interval.

Description

The inq_idle_default() primitives retrieves the current keyboard idle interval, see set_idle_default.

Parameters

none

Returns

The inq_idle_default() primitives returns the current value of the interval timer.

Portability

n/a

inq_idle_time

int inq_idle_time()

Retrieve keyboard idle time.

Description

The inq_idle_time() primitives retrieves the number of seconds since the user last pressed a key, representing the time keyboard input has been idle.

Parameters

none

Returns

The inq_idle_time() primitive returns the idle timer in seconds.

Portability

n/a

inq_indent

int inq_indent( [int bufnum] )

Get current indentation settings.

Description

The inq_indent() primitive retrieves the current buffer indentation of the specified buffer bufnum.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

Returns the non-zero indentation value if indentation is active, otherwise 0.

Portability

A GriefEdit extension.

inq_kbd_char

int inq_kbd_char()

Peek at the keyboard.

Description

The inq_kbd_char() primitive determines whether a character is available to be retrieved from the keyboard using read_char.

Note:

This primitive only tests the internal look ahead buffer not the external terminal and/or keyboard stream.

Parameters

none

Returns

The inq_kbd_char() primitive returns non-zero if one or more characters are available, otherwise 0 if the keyboard buffer is empty.

Portability

n/a

inq_kbd_flags

int inq_kbd_flags()

Get keyboard key flags.

Description

The inq_kbd_flags() primitive returns the state of the special keyboard keys.

Bit	Definition
0x01	Right Shift
0x02	Left Shift
0x04	Ctrl
0x08	Alt
0x10	Scroll
0x20	Num Lock
0x40	Caps Lock

Parameters

none

Returns

Always returns 0.

Portability

Provided only for BRIEF compatibility.

inq_kbd_name

string inq_kbd_name( [int kbdid] )

Retrieve the assigned keyboard name.

Description

The inq_kbd_name() primitive retrieves the name assigned to the keyboard kbdid using <set_kdb_name>.

Parameters

kbdid

Optional integer keyboard identifier, if omitted the current keyboard shall be referenced.

Returns

The inq_kbd_name() primitive retrieves the keyboard name otherwise an empty string is none has been assigned.

Portability

n/a

inq_keyboard

int inq_keyboard()

Retrieve the keyboard identifier.

Description

The inq_keyboard() primitive retrieves the identifier associated with the current keyboard.

Parameters

none

Returns

The inq_keyboard() primitive returns the current keyboard identifier.

Portability

n/a

inq_keystroke_macro

string inq_keystroke_macro( [int macroid],
[int &bufnum] )

Retrieve the current keystroke macro.

Description

The inq_keystroke_macro() primitive retrieves a string containing the definition of the current keyboard macro, which may then be saved in a file and reloaded.

The returned definition may edited and/or saved for future use; see load_keystroke_macro.

Note:

The primitive and the returned definition is a useful reference when developing customised macros.

Consult the remember source as an example how this buffer can be saved.

Parameters

macroid	Optional integer macro identifier specifies the keyboard against which to derive the buffer name, if omitted the current macro identifier is utilised.
bufnum	Omitted integer variable if supplied shall be populated with the associated buffer number.

Returns

nothing

Portability

Under BRIEF this primitive behaved like the functionality available via inq_keystroke_status.

inq_keystroke_status

int inq_keystroke_macro( [int &macroid] )

Determine keystroke macro status.

Description

The inq_keystroke_macro() primitive determines whether keystroke macro record or playback is active.

Parameters

macroid

Optional integer variable if supplied shall be populated with the current macro identifier.

Returns

The inq_keystroke_macro() primitive returns greater than zero if a keystroke macro is being recorded or played back.

Portability

Under BRIEF this primitive is named inq_keystroke_macro.

inq_line_col

string inq_line_col()

Retrieve the echo_line content.

Description

The inq_line_col() primitive retrieves the current content of the echo_line.

Parameters

none

Returns

The inq_line_col() primitive returns the current echo line status.

Portability

n/a

inq_line_flags

int inq_line_flags( [int bufnum],
[int lineno],
[int& iflags] )

Retrieve a lines associated flags.

Description

The inq_line_flags() primitive retrieves the flags associated with the specified line.

The line flags was a set of 32 bit values, with the upper 16 bits being defined for GriefEdit usage and lower 16 bits for user/macro usage.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
lineno	Line number within the selected buffer, otherwise if omitted the current line is referenced.
iflags	Optional storage for the associated internal flags.

Returns

Associated line flags.

Compatibility

Internal flags are an GriefEdit extension.

inq_line_length

int inq_line_length( [int bufnum] )

Determine the longest line length.

Description

The inq_line_length() primitive determines the length of the longest line within the specified buffer bufnum.

The calculate line length corresponds to the logical column position at the end of the line, taking into account any tabs and control characters.

If the designated buffer contains a marked region, then only the lines within the marked region are including within the result.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_line_length() primitive returns the longest line within the referenced buffer or region, otherwise -1 on error.

Portability

Unlike BRIEF the longest current line is returned. BRIEF returned the upper global line length rounded up the the next multiple of 16, for example 202 would have been rounded to 208, not a buffer specific value.

Description

The inq_lines() primitive returns the current line number of the specified buffer bufnum.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_lines() primitive returns the line count within the referenced buffer, otherwise -1 on error.

Portability

n/a

inq_local_keyboard

int inq_local_keyboard()

Retrieve local keyboard identifier.

Description

The inq_local_keyboard() primitive retrieves the identifier associated with current local keyboard.

Parameters

none

Returns

The inq_local_keyboard() primitive returns the associated keyboard identifier, otherwise 0 if none is available.

Portability

n/a

inq_macro

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

name	String containing the macro name to be tested.
mode	Optional integer test type, if omitted defaults to 0, see table for mode behaviours.

Tests

The following test behaviours are available given by mode;

Value	Description
0x00	Default behaviour if mode is omitted. inq_macro tests specified macro name against both runtime loaded macros and built-in primitive. It returns 1 if the macro exists (loaded, autoload or a primitive replacement), 0 if it is a built-in primitive, otherwise -1 if neither a built-in primitive nor macro. Note: The returns are incompatible with the original BRIEF implementation.
0x01	inq_macro only tests whether the specified macro name is runtime loaded macro, ignoring built-in primitives. It returns 1 if the macro is loaded, 2 if it exists as an autoload but has yet to be loaded otherwise 0 if the macro does not exist.
0x02	inq_macro returns the assigned positive module number (See: inq_module) if the macro has been loaded, 0 i it is an autoload, otherwise -1 if the macro does not exist.
0x03	inq_macro only tests whether the specified macro name is a primitive, ignoring runtime loaded macros It returns 1 if the primitive exists, 2 if it has been replaced (See: replacement) otherwise 0 if the primitive does not exist.

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.

inq_macro_history

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

index

Optional int index.

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.

inq_margins

int inq_margins( [int bufnum],
[int &left],
[int &right],
[int &style],
[int &colorcolumn],
[int global = TRUE] )

Retrieve buffer formatting margins.

Description

The inq_margins() primitive retrieves one or more of the specified buffers bufnum current margins.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced. A negative bufnum (e.g. -1) shall retrieve the global margin parameters, which are applied when no buffer specific margin has been set.
left	Optional left margin.
right	Optional right margin.
style	Optional justification style.
colorcolumn	Optional colour column.
global	Optional integer flag, if given as FALSE when retrieving buffer margins the global settings shall not be applied when no buffer specific value is available.

Returns

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

Portability

A GriefEdit extension.

inq_mark_size

int inq_mark_size()

Retrieve size of marked region.

Description

The inq_mark_size() primitive determines the number of characters what are in the currently marked region; this represents the the length of a string which would be necessary to hold its content, see get_region.

Parameters

none

Returns

The inq_mark_size() primitive returns the number of characters in the currently marked region, otherwise 0 if there is no current region.

Portability

A GriefEdit extension.

inq_marked

int inq_marked( [int &start_line],
[int &start_col],
[int &end_line],
[int &end_col] )

Determine the current marked region.

Description

The inq_marked() primitive retrieves the current mark type and the associated coordinates of the marked area.

Region Types

Value	Constant	Description
0	MK_NONE	No mark is set
1	MK_NORMAL	Normal mark
2	MK_COLUMN	Column mark
3	MK_LINE	Line mark
4	MK_NONINC	Non-inclusive

Parameters

start_line	If specified the integer parameter is set to the line number at the top of the marked region.
start_col	If specified the integer parameter is set to the column number at the beginning of the marked region.
end_line	If specified the integer parameter is set to the line number marking the bottom of the marked region.
end_col	If specified the integer parameter is set to the column number at the end of the marked region.

Returns

The inq_marked() primitive returns the current region type, otherwise 0 if no mark is active.

Portability

n/a

inq_marked_size

int inq_marked_size()

Size the marked region.

Description

The inq_marked_size() primitive is reserved for future compatibility.

The inq_marked_size() primitive determines the number of characters contained within the current marked region.

Parameters

Returns

Returns the character count within the marked region.

Portability

Function is currently a no-op, returning -1.

inq_message

string inq_message()

Retrieve the prompt line.

Description

The inq_message() primitive returns the string that is currently displayed on the command prompt.

Parameters

none

Returns

The inq_message() primitive returns a string being what is currently displayed on the message line.

Portability

n/a

inq_mode

int inq_mode( [int bufnum],
[int &localised] )

Returns the overstrike mode.

Description

The inq_mode() primitive retrieves the current insert/overstrike (also known as overtype) mode.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
localised	Optional integer reference, if specified is populated with the localisation status. If true then the mode is specific to the referenced buffer, otherwise the global mode is active.

Returns

The inq_mode() primitive retrieves the non-zero if in insert mode, otherwise zero if in overstrike mode.

Portability

The localised status is a GriefEdit extension.

inq_modified

int inq_modified( [int bufnum] )

Determine a buffers modification status.

Description

The inq_modified() primitive determine whether the specified buffer bufnum has been modified.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Example

The following echos to the command prompt the current buffers modification status.

message("Buffer has %sbeen modified.",
            inq_modified() ? "" : "not ");

Returns

The inq_modified() primitive returns the modification status, true when modified otherwise false if the buffer has no changes since loading or the last save.

Portability

n/a

inq_module

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.

inq_mouse_action

string inq_mouse_action()

Retrieve the keyboard mouse handler.

Description

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

The inq_mouse_action() primitive retrieves the name of the current mouse action handler. This function can be used to save the current mouse handle prior to pushing a new keyboard.

Parameters

none

Returns

Returns the current mouse action.

Portability

n/a

inq_mouse_type

int inq_mouse_type()

Retrieve the button type.

Description

The inq_mouse_type() primitive retrieves the current mouse type.

Parameters

none

Returns

Returns the current mouse type.

Value	Description
0	No mouse.
1	One-button mouse.
2	Two-button mouse.
3	Three-button mouse.

Portability

n/a

inq_msg_level

int inq_msg_level()

Get the message level.

Description

The inq_msg_level() primitive retrieves the current message level.

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.

Parameters

none

Returns

The inq_msg_level() primitive returns the message level.

Portability

n/a

inq_names

int inq_names( [string fullname],
[string ext],
[string bufname],
[int bufnum] )

Retrieve associated buffer names.

Description

The inq_names() primitive retrieves the file and/or buffer names associated with the specified buffer bufnum.

Parameters

fullname	Optional string variable reference, if specified shall be populated with the full path name of the underlying file, that is used on write_buffer calls.
ext	Optional string variable reference, if specified shall be populated the file extension taken from the full path.
bufname	Optional string variable reference, if specified shall be populated with buffer name which is used as the buffer title, see set_buffer_title; which is usually the basename, i.e. full path without the path.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

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

Portability

n/a

inq_position

int inq_position( [int &line],
[int &col] )

Retrieve current buffer position.

Description

The inq_position() primitive retrieves the current cursor position in the current buffer.

Parameters

line	Optional integer variable when supplied shall be populated with the current buffer line.
col	Optional integer variable when supplied shall be populated with the current buffer column.

Returns

The inq_position() primitive returns 0 if the current position is not past the end of the buffer. Otherwise, the number of lines between the end of the buffer and the current position.

Portability

n/a

inq_process_position

int inq_process_position( [int &line],
[int &column] )

Get position of process buffer.

Description

The inq_process_position() primitive retrieves the current cursor position for the underlying process, this primitive is similar to inq_position.

The process position is used for output from the process; rather than inserting the output from the process where the users cursor is, a separate cursor is maintained instead.

This permits the user to move around the buffer whilst the process is generating output without the process output being sprinkled through the buffer.

Parameters

line	Optional integer variable to be populated with the cursor line.
column	Optional integer variable to be populated with the cursor row.

Returns

The inq_process_position() primitive returns 0 on sucess, otherwise -1 if the current buffer is not attached to a process.

Portability

n/a

inq_profile

string inq_profile()

Retrieve profile directory.

Description

The inq_profile() primitive retrieves the directory within which user specific profile information can be stored, examples include the restore state and personal dictionary.

This directory shall be system specific.

On Unix style systems, the profile is normally a sub-directory within the home directory of the current user is specified by the $HOME environment variable; this is also represented by the ~ directory.

~/.grief

On Windows systems, the profile is normally a sub-directory within the directory that serves as a common repository for application-specific data. A typical path is

C:\Documents and Settings\<user>\Application Data\.grief.

Parameters

none

Returns

The inq_profile() primitive returns a string containing system dependent profile directory.

Portability

A GriefEdit extension.

inq_prompt

int inq_prompt()

Retrieve the prompt status.

Description

The inq_prompt() primitive retrieves the prompt status flag, which can be used to detrmine whether the user prompt is current active.

Parameters

none

Returns

The inq_prompt() primitive returns a boolean value stating whether or not the user is currently being prompted for input on the command line.

Portability

n/a

inq_remember_buffer

string inq_remember_buffer( [int macroid] )

Determine the keystroke buffer name.

Description

The inq_remember_buffer() primitive derives the buffer name associated with the keyboard macro macro.

Unlike BRIEF multiple keystroke macros can be maintained. Each remember execution shall create a buffer named KBD-MACRO-# where # is the associated keyboard macro identifier. This buffer maybe then edited and/or saved to later use.

Parameters

macroid

Optional integer macro identifier specifies the keyboard against which to derive the buffer name, if omitted the current macro identifier is utilised.

Returns

The inq_remember_buffer() primitive returns the buffer name associated with the remember buffer.

Portability

n/a

inq_ruler

string|list inq_ruler( [int bufnum],
[int min_count],
[int aslist = FALSE] )

Retrieves the ruler specification.

Description

The inq_ruler() primitive retrieves the effective indentation specification of the current buffer.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
min_count	Optional integer, allows the specification of the minimum number of tab points which shall be presented within the returned specification.
aslist	Optional integer boolean flags, if TRUE the tab specification is returned in the form of a list of integers, otherwise by default as a string specification.

Returns

The inq_ruler() primitive either returns a space separated string or an integer list containing the current indentation specification; both are suitable for use by set_ruler.

Portability

A GriefEdit extension.

inq_scrap

int inq_scrap( [int &last],
[int &type] )

Obtain the scrap buffer identifier.

Description

The inq_scrap() primitive retrieves the buffer identifier of the current scrap buffer.

Parameters

last	Not used; provided for BRIEF compatibility. If false the last newline in the scrap is not considered part of the scrap, otherwise true it is considered part of the scrap.
type	Optional integer variable reference, if stated shall be populated with the buffers mark type.

Returns

The inq_scrap() primitive returns the scrap buffer identifier.

Portability

n/a

inq_screen_size

int inq_screen_size( [int &rows],
[int &cols],
[int &colors] )

Determine screen dimensions.

Description

The inq_screen_size() primitive retrieves the screen dimensions, being the number of text rows and character columns.

Parameters

rows	Optional integer reference populated with the number of text rows.
cols	Optional integer reference to be populated with the number of character columns.
colors	Optional integer reference populated with the color depth supported by the display.

Returns

The inq_screen_size() primitive returns zero if terminal is configured as a monochrome screen, or non-zero if in color mode.

Portability

GriefEdit extended.

inq_symbol

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

symbol

Name of the symbol.

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.

inq_syntax

int inq_syntax( [int &flags],
[int|string syntable] )

Retrieve the syntax identifier.

Description

The inq_syntax() primitive retrieves the syntax identifier associated with the specified syntax.

Parameters

flags	Option integer reference, to be populated with the active flags of the referenced syntax-table.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The inq_syntax() primitive returns the syntax-table identifier, otherwise -1 on error.

Portability

A GriefEdit extension.

inq_system

int inq_system( [int bufnum] )

Determine if buffer is a system buffer.

Description

The inq_system() primitive determines whether the specified buffer bufnum is marked as a system buffer.

System buffers do not appear in buffer lists, are not editable by users and are handled specially by many macros. System buffer are generally utilised by macros for internal work pads.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_system() primitive returns non-zero if the associated buffer is a system buffer, otherwise 0 if the buffer is a normal buffer.

Portability

n/a

inq_tab

int inq_tab( [int bufnum] )

Derive the tab increment.

Description

The inq_tab() primitive derives the tab increment in force at the current cursor position.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

Returns the current tab increment, otherwise the default of 8 if none is active.

Portability

An GriefEdit extension.

inq_tabs

string|list inq_tabs( [int bufnum],
[int min_count],
[int aslist = FALSE] ))

Retrieves the buffer tab specification.

Description

The inq_tabs() primitive retrieves the effective tabs specification of the current buffer.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
min_count	Optional integer, allows the specification of the minimum number of tab points which shall be presented within the returned specification.
aslist	Optional integer boolean flags, if TRUE the tab specification is returned in the form of a list of integers, otherwise by default as a string specification.

Returns

The inq_tabs() primitive either returns a space separated string or an integer list containing the current tabs specification; both are suitable for use by tabs.

Portability

A GriefEdit extension.

inq_terminator

int inq_terminator( [int bufnum],
[string &term] )

Retrieve a buffers line terminator.

Description

The inq_terminator() primitive retrieves the line terminator of the specified buffer bufnum.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
term	Optional string variable reference, to be populated with the line terminator of referenced buffer.

Returns

The inq_termintor() primitive returns the line terminator type of the specified buffer (See: set_terminator), otherwise -1 on error.

Portability

A GriefEdit extension.

inq_time

int inq_time( [int bufnum],
[int &ctime] )

Retrieve the last modification time.

Description

The inq_time() primitive returns the time at which the last modification occurred of the specified buffer bufnum, represented by the number seconds since the beginning of the current edit session.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
ctime	Optional integer value reference, if specified shall be populated with the associated system time, being the number of second since 1970/01/01 UTC.

Returns

The inq_time() primitive returns the time in seconds of last modification, 0 if the buffer has not been modified during the current edit session, otherwise -1 if the buffer is invalid.

Portability

n/a

inq_tmpdir

string inq_tmpdir()

Get the temporary-file directory.

Description

The inq_tmpdir() primitive retrieves the temporary file directory. The directory is determined by the current environment, which is host specific, for example on UNIX systems the default value of this property is typically “/tmp” or “/var/tmp”; on Microsoft Windows systems it is typically “c:\temp”.

Windows

On XP and greater the system folder local application data directory is queried.

If this fails, the function checks for the existence of environment variables in the following order and uses the first path found:

The path specified by the TMP environment variable.
The path specified by the TEMP environment variable.
The path specified by the USERPROFILE environment variable.
The Windows directory.

UNIX like Systems

TMPDIR is the canonical Unix environment variable that should be used to specify a temporary directory for scratch space.

Other forms accepted are TEMP, TEMPDIR and TMP, but these alternatives are used more commonly by non-POSIX operating systems or non-conformant programs.

Parameters

none

Returns

The inq_tmpdir() primitive returns a string containing the temporary file directory.

Portability

A GriefEdit extension.

inq_top_left

int inq_top_left( [int &top],
[int &indent],
[int winnum],
[int &line],
[int &col],
[int &bufnum] )

Retrieve window view port coordinates.

Description

The inq_top_left() primitive retrieves the view port coordinates of the specified window into their associated buffer, if omitted the current window is referenced.

The variables line and column retrieves the buffer coordinates displayed at the top left corner of the window. csrline and csrcolumn retrieve the buffers cursor position.

Parameters

line	Optional integer, if specified is populated with the line at the top of the window.
column	Optional integer, retrieves the column at the top left corner of the window.
winnum	Optional window identifier, if omitted the current window shall be referenced.
csrline	Optional integer, if specified is populated with the buffer cursor line position.
csrcolumn	Optional integer, retrieves the buffer cursor column position.
bufnum	Optional integer, if specified is populated with the associated buffer identifier.

Returns

The associated window identifier, otherwise -1 on error.

Portability

n/a

inq_username

string inq_username()

Retrieve the user name.

Description

The inq_username() primitive retrieves the current user name.

Parameters

none

Returns

The inq_username() primitive returns a string containing the current user name.

Portability

A GriefEdit extension.

inq_vfs_mounts

list inq_vfs_mounts()

Retrieve list of mounts.

Description

The inq_vfs_mounts() primitive retrieves a list of three elements describing each of the current mounted virtual file-systems.

Parameters

none

Returns

Returns a list of mount points, each mount description contains the following elements.

mountpoint	String containing the mount point, being the logical path representing the root of the mounted resource.
prefix	Prefix string, unique name detailing the underlying file-syste type, examples include ftp and gzip.
flags	Integer flags.

Portability

A GriefEdit extension.

inq_views

int inq_views( [int bufnum] )

Determine window count.

Description

The inq_views() primitive determines the number of windows that are viewing the specified buffer bufnum.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_views() primitive returns the number of windows attached to the specified buffer, otherwise 0 on error.

Portability

n/a

inq_window

int inq_window()

Retrieve the current window.

Description

The inq_window() primitive retrieves the window identifier of the current window.

Parameters

none

Returns

The inq_window() primitive returns the current window identifier otherwise -1 if there is no window. This identifier can be used to save and restore the active window.

Portability

n/a

inq_window_buf

int inq_window_buf( [int winnum] )

Retrieve the associated buffer.

Description

The inq_window_buf() primitive retrieves the associated buffer identifier of the specified window, if omitted the current window.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

The associated buffer identifier, otherwise -1 on error.

Portability

n/a

inq_window_color

int inq_window_color( [int winnum] )

Retrieve the window attribute.

Description

The inq_window_color returns the background and foreground colors of a window. If winnum is not specified then the colors of the current window are returned.

If the window color is set to < 0, then the default background color will be used. If the color is set to >= 0 then the specified color will be used.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

Returns the current window attribute, otherwise -1 on error.

Portability

Unlike BRIEF the assigned attributes is returned, whereas BRIEF returned an encoded colorl the foreground were the lower 4 bits (nibble) and the background was the upper 4 bits.

inq_window_flags

int inq_window_flags( [int winnum],
[string flags] )

Retrieve window flags.

Description

The inq_window_flags() primitive retrieves the window flags of the specified window winnum otherwise if omitted the current window.

Window Flags

Available window flags.

Constant	Name	Description
WF_HIDDEN	hidden	Hide the window from view, used to hide nested popup’s/boss mode etc.
WF_NO_SHADOW	no_shadow	Turn off the popup window shadows.
WF_NO_BORDER	no_border	Turn off borders, regardless of the borders() setting.
WF_SYSTEM	system	Window is a system window (e.g. menu).
WF_SHOWANCHOR	showanchor	Show anchor regardless of selection status.
WF_SELECTED	selected	Highlight the title regardless of selection status.
WF_LAZYUPDATE	lazyupdate	Delay any updates until next refresh().
WF_LINE_NUMBERS	line_numbers	Line numbers.
WF_LINE_STATUS	line_status	Line status.
WF_EOF_DISPLAY	eof_display	Show <EOF> marker.
WF_TILDE_DISPLAY	tilde_display	Show ~ marker as EOF marker.
WF_HIMODIFIED	himodified	Highlight modified lines.
WF_HIADDITIONAL	hiadditional	Highlight additional lines.
WF_HICHANGES	hichanges	Highlight in-line changes.
WF_EOL_HILITE	eol_hilite	Limit highlight to EOL.
WF_EOL_CURSOR	eol_cursor	Limit cursor to EOL.

Parameters

winnum	Optional window identifier, if omitted the current window shall be referenced.
flags	Optional comma separated list of window flag names, if given the value of the specific flags are returned, otherwise the full flags is returned.

Returns

Returns the associated window flags.

Portability

The feature set exposed differs from CRiSP ™. It is therefore advised that the symbolic constants are using within #ifdef constructs.

The flag argument is a GriefEdit extension.

inq_window_info

int inq_window_info( [int &winnum],
[int &bufnum],
[int &lx],
[int &by],
[int &rx],
[int &ty],
[string &title = NULL],
[string &message = NULL] )

Retrieve the current window information.

Description

The inq_window_info() primitive retrieves information associated with the current windowd.

Parameters

winnum	An integer variable which shall be populated with the window identifier, otherwise -1 if no buffer is attached.
bufnum	An integer variable which shall be populated with the buffer identifier of the buffer attached to the specified window, otherwise -1 if no buffer is attached.
lx	An integer variable which shall be populated with the left x coordinate of the specified window.
by	An integer variable which shall be populated with the bottom x coordinate of the specified window.
rx	An integer variable which shall be populated with the right x coordinate of the specified window.
ty	An integer variable which shall be populated with the top y coordinate of the specified window.
title	A string variable, which shall be assigned the specified window title value.
message	A string variable, which shall be assigned the specified window message value.

Returns

The inq_window_info() primitive returns zero if the specified window is tiled, one if the window is an popup/overlapping window and two if the menu window.

Portability

This primitive differs from the BRIEF implementation, in that it only returns information associated with the current window and update the first argument to reflect the windows identifier, also see inq_window_infox.

The title and message parameters are extensions.

inq_window_infox

int inq_window_infox( [int winnum],
[int &bufnum],
[int &lx],
[int &by],
[int &rx],
[int &ty],
[string &title = NULL],
[string &message = NULL] )

Retrieve information about a window.

Description

The inq_window_infox() primitive retrieves information associated with the specified window winnum or the current window if no window is specified.

Parameters

winnum	Optional integer window identifier, if omitted the current window is referenced.
bufnum	An integer variable which shall be populated with the buffer identifier of the buffer attached to the specified window, otherwise -1 if no buffer is attached.
lx	An integer variable which shall be populated with the left x coordinate of the specified window.
by	An integer variable which shall be populated with the bottom x coordinate of the specified window.
rx	An integer variable which shall be populated with the right x coordinate of the specified window.
ty	An integer variable which shall be populated with the top y coordinate of the specified window.
title	A string variable, which shall be assigned the specified window title value.
message	A string variable, which shall be assigned the specified window message value.

Returns

The inq_window_info() primitive returns zero if the specified window is tiled, one if the window is an popup/overlapping window and two if the menu window.

Portability

This primitive mirrors the original BRIEF interface presented by inq_window_info, permitted either the current or an explicit window to be referenced.

The title and message parameters are extensions.

inq_window_priority

int inq_window_priority( [int winnum] )

Retrieve the windows display priority.

Description

The inq_window_priority() primitive retrieves the display priority of the specified window, , if omitted the current window.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

Window priority, otherwise -1 on error.

Portability

A GriefEdit extension.

inq_window_size

int inq_window_size()

Retrieve the window size.

Description

The inq_window_size() primitive determines the size of the current window.

Parameters

height	An integer variable which shall be populated with the window height in lines.
width	An integer variable which shall be populated with the window width height in lines.
left_offset	An integer variable which shall be populated with the number of columns that the window has been scroll horizontally, being the number of columns to the left.
lmargin	An integer variable which shall be populated with the window left margin in lines.
rmargin	An integer variable which shall be populated with the window right margin in lines.

Returns

The inq_window_size() primitive returns the window height in rows, otherwise -1 if there is no current window.

Portability

The margins left and right are GriefEdit extensions.

insert

int insert( string|int val,
[int num = 1] )

Insert string into current buffer.

Description

The insert_process() primitive inserts the specified string or integer character value val into the current buffer. The value shall be inserted num times, which if omitted defaults to 1.

Parameters

val	String or integer character value to be inserted.
num	Option integer number stating the repeat count, if specified then the string is inserted the given number of times. If omitted, it defaults to 1.

Returns

The insert() primitive returns the number of characters inserted.

Portability

The standard function has a void declaration and returns nothing.

insert_buffer

int insert_buffer( int bufnum,
string format,
... )

Insert format text into a buffer.

Description

The insert_buffer() primitive behaves like the C printf() function. It inserts the string format into the specified buffer and applies the printf style formatting commands as specified in format, and using the argument list.

When more than one argument is specified then format is treated as a printf-style format specification. (ie. % sequences are interpreted, otherwise % characters are inserted literally).

Parameters

bufnum	Buffer number.
format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The insert_buffer() primitive returns the number of characters written to the referenced buffer, otherwise -1 on error.

Portability

The CRiSPEdit™ version has a void declaration and returns nothing.

insert_mode

int insert_mode( [int value],
[int bufnum] )

Set the buffer insert/overstrike mode.

Description

The insert_mode() primitive sets the insert/over-strike mode to value otherwise toggles if omitted.

The applied mode shall either be localised to the specified buffer bufname, otherwise if omitted the global (default) mode that applies to all buffers within a localised setting.

Parameters

value	Optional integer stating the insert mode being zero for over-strike and non-zero for insert. For localised modes -1 clears the active localisation, restoring use of the global (default) mode. If omitted the current mode is toggled.
bufnum	Optional buffer number when stated the buffer specific insert mode shall be modified, if omitted the global insert mode is modified.

Returns

The insert_mode() primitive returns the previous insert mode.

Portability

n/a

insert_process

int insert_process( string|int val,
[int num = 1] )

Send string to a attached process.

Description

The insert_process() primitive inserts the specified string or integer character value val into the process attached to the current buffer. The value shall be inserted num times, which if omitted defaults to 1.

Parameters

val	String or integer character value to be inserted.
num	Option integer number stating the repeat count, if specified then the string is inserted the given number of times. If omitted, it defaults to 1.

Returns

The insert_process() primitive returns the number of characters inserted.

Portability

n/a

insertf

int insertf( string format,
... )

Insert a formatted string.

Description

The insertf() primitive behaves like the C printf() function. It inserts the string format into the current buffer and applies the printf style formatting commands as specified in fmt, and using the argument list.

When more than one argument is specified then expr is treated as a printf-style format specification. (ie. % sequences are interpreted, otherwise % characters are inserted literally).

Parameters

format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The insertf() primitive returns the number of characters written to the referenced buffer, otherwise -1 on error.

Portability

A GriefEdit extension.

int

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

int_to_key

string int_to_key( int key )

Convert an keycode to mnemonic key string.

Description

The int_to_key() primitive generates the corresponding mnemonic representation for the specified keycode key; which can be used by assign_to_key

Parameters

key	Integer keycode.

Returns

The int_to_key() primitive returns the key mnemonic string associated with the specified keycode, for example “<Ctrl-D>”; see assign_to_key for full description of key mnemonics.

Portability

n/a

is_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.

Parameters

symbol

Symbol reference.

Returns

true if a array type, otherwise false.

Portability

n/a

is_float

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

symbol

Symbol reference.

Returns

true if a float type, otherwise false.

Portability

A GriefEdit extension.

is_integer

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

symbol

Symbol reference.

Returns

true if an integer type, otherwise false.

Portability

n/a

is_list

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

symbol

Symbol reference.

Returns

true if a list type, otherwise false.

Portability

n/a

is_null

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.

Parameters

symbol

Symbol reference.

Returns

true if a NULL type, otherwise false.

Portability

n/a

is_string

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.

Parameters

symbol

Symbol reference.

Returns

true if a string type, otherwise false.

Portability

n/a

is_type

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.

Parameters

symbol	Symbol reference.
type	Type identifier or name as follows.

Type	Name
F_INT	integer
F_STR	string
F_FLOAT	float, double
F_LIST	list
F_ARRAY	array
F_NULL	NULL
F_HALT	undef

Returns

true if the stated type, otherwise false.

Portability

n/a

isalnum

int isalnum( string |int object,
[int index] )

Alphanumeric character predicate.

Description

The isalnum() primitive determines whether the specified object object belongs to the alpha or numeric character-classes.

This is [0 through 9], [A through Z] and [a through z] in the program’s current locale; which is equivalent to (isalpha() || isdigit()).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isalnum() primitive returns non-zero if object is an alphanumeric character; otherwise it returns 0.

Portability

The index option is a GriefEdit extension.

Example

if (isalnum(read(1)))
    message("Next character is alnum.");

isalpha

int isalpha( string |int object,
[int index] )

Alpha character predicate.

Description

The isalph() primitive determines whether the specified object object belongs to the alpha character-class.

This is [A through Z] and [a through z] in the program’s current locale; which is equivalent to (isupper()

| islower()).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isalpha() primitive returns non-zero if object is an alphanumeric character; otherwise it returns 0.

Example

if (isalpha(read(1)))
    message("Next character is a alpha character.");

Portability

The index option is a GriefEdit extension.

isascii

int isascii( string |int object,
[int index] )

ASCII character predicate.

Description

The isascii() primitive determines whether the specified object object belongs to the ascii character-class.

This is any character value in the range 0 through 0177 (0 through 0x7F), inclusive.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isascii() primitive returns non-zero if object is an alphanumeric character; otherwise it returns 0.

Example

if (isascii(read(1)))
    message("Next character is an ascii character.");

Portability

The index option is a GriefEdit extension.

isblank

int isblank( string |int object,
[int index] )

Blank character predicate.

Description

The isblank() primitive determines whether the specified object object belongs to the blank character-class.

This is a space ( ) or tab (\t) character.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isblank() primitive returns non-zero if object is an alphanumeric character; otherwise it returns 0.

Example

if (isblank(read(1)))
    message("Next character is blank.");

Portability

The index option is a GriefEdit extension.

isclose

int isclose( float v1,
float v2,
float ~rel_tot,
float ~abs_tol )

Test for floating point equality.

Description

The isclose() primitive determines whether two floating point numbers are close in value.

Parameters

v1	First string.
v2	Second value to compare against.
rel_tol	Optional value, used for relative tolerance.
abs_tol	Optional value, used for the minimum absolute tolerance.

Returns

The isclose() primitive returns a non-zero value if v1 is close in value to v2, otherwise zero or -1 on error.

Portability

A GriefEdit extension.

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

iscntrl

int iscntrl( string |int object,
[int index] )

Control character predicate.

Description

The iscntrl() primitive determines whether the specified object object belongs to the control character-class.

The control-class is any character for which the isprint() subroutine returns a value of False (0) and any character that is designated a control character in the current locale. For the C locale, control characters are the ASCII delete character (0177 or 0x7F), or an ordinary control character

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The iscntrl() primitive returns non-zero if object is an control character; otherwise it returns 0.

Example

if (iscntrl(read(1)))
    message("Next character is a control character.");

Portability

The index option is a GriefEdit extension.

iscsym

int iscsym( string |int object,
[int index] )

A symbol character predicate.

Description

The iscsym() primitive determines whether the specified object object belongs to the c-symbol classes, which represent a symbol in the C/C++, GriefEdit macro and similar languages.

This is [0 through 9], [A through Z], [a through z] and underscore (_) in the program’s current locale. which is equivalent to (isalpha() || isdigit() || _).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The iscsym() primitive returns non-zero if object is a symbol character; otherwise it returns 0.

Example

if (iscsym(read(1)))
    message("Next character is symbol character.");

Portability

The index option is a GriefEdit extension.

isdigit

int isdigit( string |int object,
[int index] )

Numeric character predicate.

Description

The isdigit() primitive determines whether the specified object object belongs to the numeric character-class.

This is [0 through 9] in the program’s current locale.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isdigit() primitive returns non-zero if object is an numeric character; otherwise it returns 0.

Example

if (isdigit(read(1)))
    message("Next character is a numeric character.");

Portability

The index option is a GriefEdit extension.

isfinite

int isfinite( float val )

Test for finite value.

Description

The isfinite() primitive shall determine whether its argument has a finite value (zero, subnormal, or normal, and not infinite or NaN).

Returns

The isfinite() primitive shall return a non-zero value if and only if its argument has a finite value.

Portability

A GriefEdit extension.

isgold

int isgold( string |int object,
[int index] )

Alphanumeric character predicate.

Description

The isgold() primitive determines whether the specified object object belongs to either the function, keypad or special character-classes.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested. The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isgold() primitive returns non-zero if object is a meta/gold key character; otherwise it returns 0.

Portability

A GriefEdit extension.

Example

if (isgold(read(1)))
    message("Next character is gold.");

isgraph

int isgraph( string |int object,
[int index] )

Graphic character predicate.

Description

The isgraph() primitive determines whether the specified object object belongs to the graphic character-classes.

The a graphic character is equivalent to

(isprint() && not-space)

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isgraph() primitive returns non-zero if object is an graphic character; otherwise it returns 0.

Example

if (isgraph(read(1)))
    message("Next character is a graphic character.");

Portability

The index option is a GriefEdit extension.

isinf

int isinf( float val )

Test for infinity.

Description

The isinf() primitive shall determine whether its argument has a finite value (zero, subnormal, or normal, and not infinite or NaN).

Returns

The isinf() primitive shall return a non-zero value if and only if its argument has an infinite value.

Portability

A GriefEdit extension.

islower

int islower( string |int object,
[int index] )

Lowercase character predicate.

Description

The islower() primitive determines whether the specified object object belongs to the lower-case character-classes.

This is [a through z] in the program’s current locale.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The islower() primitive returns non-zero if object is an lower-case character; otherwise it returns 0.

Example

if (islower(read(1)))
    message("Next character is a lower-case character.");

Portability

The index option is a GriefEdit extension.

isnan

int isnan( float val )

Test for a NaN.

Description

The isnan() primitive tests the specified floating-point value val, returning a nonzero value if val is a not a number (NaN).

A NaN is generated when the result of a floating-point operation cannot be represented in Institute of Electrical and Electronics Engineers (IEEE) format.

On systems not supporting NaN values, isnan() always returns 0.

Returns

Non-zero if NaN, otherwise 0.

Portability

A GriefEdit extension.

isprint

int isprint( string |int object,
[int index] )

A printable character predicate.

Description

The isprint() primitive determines whether the specified object object belongs to the printable character-class.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isprint() primitive returns non-zero if object is an printable character; otherwise it returns 0.

Example

if (isprint(read(1)))
    message("Next character is printable.");

Portability

The index option is a GriefEdit extension.

ispunct

int ispunct( string |int object,
[int index] )

Punctuation character predicate.

Description

The ispunct() primitive determines whether the specified object object belongs to the punctuation character-class.

Punctuation characters are ones that are printable ((see isprint )) character but neither alphanumeric (See: isalnum) nor a space (See: isspace).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The ispunct() primitive returns non-zero if object is an alphanumeric character; otherwise it returns 0.

Example

if (ispunct(read(1)))
    message("Next character is alnum.");

Portability

The index option is a GriefEdit extension.

isspace

int isspace( string |int object,
[int index] )

Space character predicate.

Description

The isspace() primitive determines whether the specified object object belongs to the space character-class.

White-space characters are (space, form feed (\f), new-line (\n), carriage-return (\r), horizontal tab (\t) or vertical tab (\v).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The issspace() primitive returns non-zero if object is an whitespacec character; otherwise it returns 0.

Example

if (isspace(read(1)))
    message("Next character is a space character.");

Portability

The index option is a GriefEdit extension.

isupper

int isupper( string |int object,
[int index] )

Uppercase character predicate.

Description

The isupper() primitive determines whether the specified object object belongs to the uppercase character-class.

This is [A through Z] in the program’s current locale.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isupper() primitive returns non-zero if object is an uppercase character; otherwise it returns 0.

Example

if (isupper(read(1)))
    message("Next character is an uppercase character.");

Portability

The index option is a GriefEdit extension.

isword

int isword( string |int object,
[int index] )

Word character predicate.

Description

The isword() primitive determines whether the specified object object belongs to the word character-class.

This is [A through Z], [a through z], [o through 9] and underscore (_) or dash (-) in the program’s current locale; which is equivalent to (isalpha() || isdigit() || _ || ‘-’).

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isword() primitive returns non-zero if object is an word character; otherwise it returns 0.

Example

if (isword(read(1)))
    message("Next character is a word character.");

Portability

The index option is a GriefEdit extension.

isxdigit

int isxdigit( string |int object,
[int index] )

Hexadecimal character predicate.

Description

The isxdigit() primitive determines whether the specified object object belongs to the hexadecimal character-class.

This is [0 through 9], [A through f] and [a through f] in the program’s current locale.

The specified object can be an integer (whose ASCII code represents a single character), or a string, in which case the first character of the string is tested.

The optional index allows an alternative character within the string to be tested, with the first character represented by offset one.

Parameters

object	Character or string object.
[index]	If a string, an optional character index within the string, starting at offset one being the first character. if the index denotes a character out-of-bounds, the function returns 0.

Returns

The isxdigit() primitive returns non-zero if object is a hexadecimal character; otherwise it returns 0.

Example

if (isxdigit(read(1)))
    message("Next character is a hexadecimal character.");

Portability

The index option is a GriefEdit extension.

itoa

string itoa( int value,
[int base = 10] )

Convert an integer into a string.

Description

The itoa() primitive converts an integer value to a string using the specified base and returns the result.

If base is 10 and value is negative, the resulting string is preceded with a minus sign (-). With any other base, value is always considered unsigned.

Returns

Upon successful completion, itoa() returns the converted value. If no conversion could be performed, itoa() returns an empty string.

Portability

A GriefEdit extension.

key_list

list key_list( int kbdid,
[int self_inserts = 0],
[int bufnum] )

Retrieve keyboard bindings.

Description

The key_list() primitive retrieves the key bindings associated with the keyboard kbdid. The definitions are returned as a list of string pairs, the first element being the key name with the second being assigned macro.

Up to two keyboards can be specified. If bufnum is specified, then the local keyboard assigned to that buffer is used. If not specified then the local keyboard map of the current buffer is used. The returned list is a union of the set keyboards.

This primitive is designed to display a list of all valid keys currently mapped in both the current local and global keyboard maps. For an example see the key_map macro.

Parameters

kbdid	Optional integer keyboard identifier. If omitted then firstly the local keyboard if available is referenced otherwise the current keyboard is referenced.
self_inserts	Optional boolean flag when non-zero keys assigned to self_insert shall be including, otherwise they are omitted from the generated list.
bufnum	Optional buffer identifier to source the secondary local keyboard. If omitted then the local keyboard map of the current buffer is used.

Returns

The key_list() primitive returns a list of key binding, as a set of string pairs, the first element is the key name and second being assigned macro to that key. Otherwise on error a null list.

Portability

n/a

key_to_int

int key_to_int( string key,
int raw )

Convert key name to a code.

Description

The key_to_int() primitive converts a mnemonic key string to an integer.

The following scheme is utilised for encoding internal key-codes, allowing for simple conversion of ASCII character code to the internal codes and vice-versa.

Firstly key-codes are divided into several ranges.

Key Code	Range	Description
RANGE_CHARACTER	0x0 ... 1fffff	Character ASCII/Unicode range.
RANGE_FUNCTION	0x02000...	Function keys.
RANGE_KEYPAD	0x03000...	Keypad keys.
RANGE_MISC	0x04000...	Miscellaneous.
RANGE_MULTIKEY	0x05000...	Multi-key stroke.
RANGE_PRIVATE	0x06000...	Private key definitions for users.
RANGE_BUTTON	0x07000...	Mouse buttons and movement.

These ranges can be OR’ed with one or more of the following bits to indicate a modifier key, for example a Shift-F1 key or Ctrl-Shift-F2.

Modifier	Code	Description
MOD_SHIFT	0x00200000	Shift’ed.
MOD_CTRL	0x00400000	Control.
MOD_META	0x00800000	Meta or Alt.

To further simplify key handling, the follow special key manifest constants are predefined.

Key Code	Description
CTRL_1 .. CTRL_10	Control 1 thru 10.
ALT_1 .. ALT_10	Alt 1 thru 10.
CTRL_A .. CTRL_Z	Control A thru Z.
ALT_Z .. ALT_Z	Alt A thru Z.
KEY_BACKSPACE	Backspace.
KEY_BREAK	Break.
KEY_CANCEL	Cancel key.
KEY_CLOSE	Close key.
KEY_COMMAND
KEY_COPY	Copy to clipboard.
KEY_COPY_CMD
KEY_CUT	Cut to clipboard.
KEY_CUT_CMD
KEY_DEL	Delete, rubout.
KEY_DOWN	Move down, down arrow.
KEY_END	End key.
KEY_ENTER	Enter key.
KEY_ESC	Escape.
KEY_EXIT
KEY_HELP	Help, usage.
KEY_HOME	Home key.
KEY_INS	Insert.
KEY_LEFT	Move left, left arrow.
KEY_MENU	Menu key.
KEY_NEWLINE	New line.
KEY_NEXT	Next.
KEY_OPEN	Open key.
KEY_PAGEDOWN	Page down.
KEY_PAGEUP	Page up.
KEY_PASTE	Paste clipboard.
KEY_PREV	Prior, previous.
KEY_REDO	Redo, again.
KEY_REPLACE
KEY_RIGHT	Move right, right arrow.
KEY_SAVE
KEY_SEARCH	Search.
KEY_TAB	Tab.
KEY_UNDO	Undo key.
KEY_UNDO_CMD	Undo key.
KEY_UP	Move up, up arrow.
KEY_WDOWN
KEY_WDOWN2
KEY_WLEFT
KEY_WLEFT2
KEY_WRIGHT
KEY_WRIGHT2
KEY_WUP
KEY_WUP2
KEY_VOID	NUL key-code.

Warning:

The key encoding are exposed only for reference and may change without notice; for example to fully support Unicode. As such its advised keys should only be referenced using their string mnemonic representation when dealing directly with key-codes, for example.

switch (keycode) {
case key_to_int("<F1>"):
    f1();
    break;
case key_to_int("<Ctrl-A>"):
    ctrla();
    break;
case key_to_int("<Ctrl-B>"):
    ctrlb();
    break;
:

Parameters

key	String contains a single mnemonic key description (like “i” or “<Ctrl-z>”).
raw	Optional boolean flag. If non-zero, then key is taken to be a raw key stroke/escape sequence, as entered by a function key on the keyboard. In this case, the key-code assigned to that key is returned.

Returns

The key_to_int() primitive returns an integer representing the internal key code assigned to the specified key sequence, or -1 if the sequence does not correspond to an valid key.

Portability

n/a

keyboard_flush

void keyboard_flush()

Flush the keyboard buffer.

Description

The keyboard_flush() primitive flushs the keyboard input buffer, consuming any pending input, permanently removing the keystrokes.

Parameters

none

Returns

nothing

Portability

n/a

keyboard_pop

void keyboard_pop( [int save = FALSE] )

Pop a keyboard from the keyboard stack.

Description

The keyboard_pop() primitive removes the top keyboard, from the last-in/first-out (LIFO) keyboard stack.

Each invocation of keyboard_push must have a corresponding invocation of keyboard_pop.

The keyboard resource and associated identifier shall only remain valid if the save argument is non-zero, otherwise the keyboard definition is deleted and its memory reclaimed.

If the current buffer is the same as it was when the keyboard was pushed, the current local keyboard is also restored to its former value.

Parameters

save	Optional boolean value, if specified as true the keyboard resource is retained otherwise if false or omitted it is discarded.

Returns

nothing

Portability

n/a

keyboard_push

void keyboard_push( [int kbdid] )

Push a keyboard onto the keyboard stack.

Description

The keyboard_push() primitive pushes a keyboard, either an existing or new, onto the last-in/first-out (LIFO) keyboard stack. Being a stack each invocation of keyboard_push must have a corresponding invocation of keyboard_push; otherwise the keyboard objects shall never to released, resulting in a resource/memory leak.

Either the specified keyboard kbdid or if omitted a new empty keyboard object shall be pushed onto the stack and become the current keyboard (See: inq_keyboard). When a new keyboard is created, it is empty and the current local keyboard is temporarily unassigned.

A keyboard resource is a table of key bindings, that is keys mapped against the macro which should be executed when encountered. During initialisation the default keyboard resource binds the usual editing keys, keyboard_push() permits the creation of macro specific keyboards, supporting temporarily bind macros to keys for their operation.

Defaults

The default key bindings along with keyboard_typeables includes -

Key	Macro
F1	change_window
F2	move_edge
F3	create_edge
F4	delete_edge
F5	search_fwd
F6	translate
F7	remember
F8	playback
F9	load_macro
F10	execute_macro
Shift-F7	pause
Ins	paste
End	end_of_line
Down	down
Left	left
Right	right
Home	beginning_of_line
Up	up
Del	delete_block
Cut	cut
Copy	copy
Undo	undo
Page-Down	page_down
Page-Up	page_up
Wheel-Down	page_down
Wheel-Up	page_up
Shift-Keypad-2	”change_window 2”, see change_window
Shift-Keypad-4	”change_window 3”
Shift-Keypad-6	”change_window 1”
Shift-Keypad-8	”change_window 0”
Ctrl-Keypad-1	end_of_window
Ctrl-Keypad-3	end_of_buffer
Ctrl-Keypad-7	top_of_window
Ctrl-Keypad-9	top_of_buffer
Ctrl-X	exit
Alt-0	”drop_bookmark 0”, see drop_bookmark
Alt-1	”drop_bookmark 1”
Alt-2	”drop_bookmark 2”
Alt-3	”drop_bookmark 3”
Alt-4	”drop_bookmark 4”
Alt-5	”drop_bookmark 5”
Alt-6	”drop_bookmark 6”
Alt-7	”drop_bookmark 7”
Alt-8	”drop_bookmark 8”
Alt-9	”drop_bookmark 9”
Alt-A	”mark 4”, see mark
Alt-B	<buffer_list>
Alt-C	”mark 2”, see mark
Alt-D	delete_line
Alt-E	edit_file
Alt-F	<feature>
Alt-G	goto_line
Alt-I	insert_mode
Alt-J	goto_bookmark
Alt-K	delete_to_eol
Alt-L	mark
Alt-M	mark
Alt-O	output_file
Alt-P	print
Alt-Q	<quote>
Alt-R	read_file
Alt-S	search_fwd
Alt-T	translate
Alt-U	undo
Alt-V	version
Alt-W	write_buffer
Alt-X	exit
Alt-Z	shell

Parameters

kbdid

Integer keyboard identifier, if omitted or zero a new keyboard is created and pushed. Keyboards within the stack are assumed to be unique; beware pushing a keyboard which already exists which shall have undefined effects.

Returns

The keyboard_push() primitive returns the identifier of the referenced keyboard, otherwise -1 on error.

Example

The following example creates a new keyboard with only typeable key binds active.

keyboard_pop();
keyboard_push();
keyboad_typeables();

The following example shows how to create a temporary keyboard mapping for use within a macro.

keyboard_push();
assign_to_key("<Alt-H>", "help");
    // additional key bindings
                 ::
process();
keyboard_pop();

Portability

n/a

keyboard_typeables

int keyboard_typeables()

Assign self_insert to all typeable keys.

Description

The keyboard_typeables() primitive populates the keyboard with all of the standard keys, example include ASCII keys (for example A-Z and 0-9), Backspace, Tab, and Enter are bound to self_insert.

Parameters

none

Returns

nothing

Portability

n/a

lastof

int lastof( string str,
string chars,
[int &result] )

Rightmost character search.

Description

The lastof() primitive returns the offset to the last occurrence of any of the characters contained within chars in the string str.

If supplied, on success result shall be populated with the matching character otherwise is set if zero.

lastof() is similar to rindex yet allows multiple characters to be matched.

Parameters

str	String object to be searched.
chars	Character set to match against.
result	Optional result, populated with the matching character value.

Returns

The lastof() primitive returns the starting offset or 0 if non of the characters are found.

Portability

A GriefEdit extension.

ldexp

float ldexp( float val,
int exp )

Multiply by a power of two.

Description

The ldexp() primitive calculates the value of x*(2^exp).

This is x multiplied by 2 to the power of exp.

Returns

Returns the calculated value.

Otherwise, if the correct calculated value is outside the range of representable values, -/+HUGE_VAL is returned, according to the sign of the value. The value ERANGE is stored in errno to indicate that the result was out of range.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

left

int left( [int columns = 1],
[int wrap = TRUE] )

Move position left one charcter.

Description

The left() primitive moves the cursor left one column retaining the current line; unless at the beginning of the line, in which case the cursor moves to the end of the previous line.

Parameters

columns	Optional number of columns to move the cursor; negative in which case the cursor movement is reversed behaving like right.
wrap	Optional boolean value controlling whether the cursor wraps when positioned at the beginning of line. If FALSE line wrapping shall be disabled.

Returns

The left() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

Unlike BRIEF, if the cursor is moved past the beginning of the current line, then the cursor wraps around to the end of the previous line.

wrap is a GriefEdit extension.

length_of_list

int length_of_list( list lst )

Determine list element count.

Description

The length_of_list() primitive retrieves the number of top-level elements (atoms) within the list lst; with sub-lists being counted as single elements.

Returns

The length_of_list() primitive returns the top-level element count.

Portability

n/a

link

int link( string path1,
string path2 )

Link a file.

Description

The link() primitive is reserved for future use.

The link() primitive shall create a new link (directory entry) for the existing file, path1.

The path1 argument points to a pathname naming an existing file. The path2 argument points to a pathname naming the new directory entry to be created. The link() primitive shall atomically create a new link for the existing file and the link count of the file shall be incremented by one.

If path1 names a directory, link() shall fail unless the process has appropriate privileges and the implementation supports using link() on directories.

If path1 names a symbolic link, it is implementation-defined whether link() follows the symbolic link, or creates a new link to the symbolic link itself.

If link() fails, no link shall be created and the link count of the file shall remain unchanged.

Returns

Upon successful completion, link shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

list

list sym1, sym2 ...;

Declare a list symbol.

Description

The list statement declares a list being a container of atoms. More precisely, a list is either an empty container NULL, or a sequential list of values.

A list can store any other data type, including lists, allowing the creation of complex types. A list may generally only be extended at its end, by appending data; elements can be updated using put_nth and replaced using splice.

Any element may be referenced by specifying its ordinal position in the list using <get_th> and array subscripts. Lists are not the most efficient data types, since subscript element access involves iterating from the head until the associated value is referenced, whereas list_each primitive allows effective iteration.

Returns

nothing

Portability

n/a

list_each

int list_each( list lst,
declare & value,
[int increment = 1] )

Iterator though the list elements.

Description

The list_each() primitive iterates over a normal list value and sets the variable value to be each element of the list in turn.

Example

Split the flag list specification spec into its components and iterator the results.

const list flags = split(spec, ",");
string flag;

while (list_each(flags, flag) >= 0) {
    process_flag(flag);
}

Warning:

If any part of the list is modified, foreach may become very confused. Adding or removing elements within the loop body, for example with splice shall result in unpredictable results possibility crashing the editor.

Secondary list iteration continues until the last element within the list is consumed; if the loop is terminated prior to the end condition, list_reset should be used to reset the list cursor for subsequent iterations.

Parameters

lst	List expression.
value	Variable populated with the element value.
increment	Optional integer iterator loop increment, if omitted defaults to one element.

Returns

The list_each() primitive returns the element index retrieved, otherwise -1 upon an end-of-list condition or error.

Portability

A GriefEdit extension.

list_extract

list list_extract( list lst,
int start,
[int end],
[int increment] )

Extract list elements.

Description

The list_extract() primitive iterates over the list values generating a new list of the referenced elements within the list.

Parameters

lst	List expression.
start	Optional integer index, if specified states the first element index at which the iterations begins. When omitted the iterations begins from the start of the list.
end	Optional integer index, if specified states the last element index at which the iterations terminates. When omitted the iterations completes at the end of the list.
increment	Optional integer iterator loop increment, if omitted defaults to one element.

Returns

The list_extract() primitive returns a list containing the referenced elements, otherwise a NULL list on error.

Portability

n/a

list_of_dictionaries

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

nonempty	Empty diction filter. Optional integer boolean flag. If specified and is not-zero, then empty directionaries shall be filtered.
named	Named dictionary filter. Optional integer boolean flag. If specified and is not-zero, then unnamed directionaries shall be filtered.

Returns

The list_of_dictionaries() primitive retrieves a list of dictionaries.

Portability

A GriefEdit extension.

list_reset

int list_reset( list lst )

Reset the list iterator.

Description

The list_reset() primitive resets the list iteration cursor.

Parameters

lst	List expression.

Returns

The list_reset() primitive returns the selected element index.

Portability

A GriefEdit extension.

load_keystroke_macro

int load_keystroke_macro( string def )

Load a recorded macro from a file.

Description

The load_keystroke_macro() primitive loads the specified keystroke macro macro, being a string in a similar format returned by inq_keystroke_macro. This primitive is designed to allow user macros to load macros from external files.

Parameters

macro

String containing the macro definition.

Returns

The load_keystroke_macro() primitive returns the newly associated macro identifier, otherwise -1 on error.

Portability

n/a

load_macro

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.

Note:

Upon loading pre-compiled macro objects (.cm), several interface checks occur confirming whether the object is compatible with the current GRIEF version, for example engine version number and primitive count. Check failure results in a load error and suitable diagnostics being echoed on the command prompt.

Parameters

filename	String containing the macro object to be loaded. If the specified file has an extension, then an exact match is located. Otherwise files matching one of the following extensions are .cm, .cr, and .m are located.
reload	Optional boolean flag, if given as false and the same macro object was previously loaded, nothing shall be loaded.

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.

localtime

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.

Description

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.

Returns

The localtime function returns the value of time in seconds since the Epoch which the components represent.

Portability

A GriefEdit extension.

log

float log( float x )

Natural logarithm.

Description

The log() primitive calculates the natural logarithm (base e) of x, for x greater than 0.

Returns

Returns the computed value.

If x is negative, the function sets errno to EDOM and returns -HUGE_VAL. If x is 0.0, the function returns -HUGE_VAL and sets errno to ERANGE.

If the correct value would cause an underflow, 0 is returned and the value ERANGE is stored in errno.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

log10

float log10( float val )

Base 10 logarithm function.

Description

The log10() primitive calculates the base 10 logarithm of the positive value of x.

Returns

Returns the computed value.

If x is negative, the function sets errno to EDOM and returns -HUGE_VAL. If x is 0.0, the function returns -HUGE_VAL and sets errno to ERANGE.

If the correct value would cause an underflow, 0 is returned and the value ERANGE is stored in errno.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

lower

string|int lower( string str|int character )

Convert string or character to lowercase.

Description

The lower() primitive converts all alphabetic characters within the string object str or just the specified character ch to lowercase.

Returns

Returns the specified object with all alphabetic characters converted to lowercase.

If the argument is a string then a copy of the string is returned, otherwise the integer value of the converted character.

Portability

Character support is a GriefEdit extension.

lstat

int lstat( string path,
[int size],
[int mtime],
[int ctime],
[int atime],
[int mode],
[int uid],
[string uid2name],
[int gid],
[string gid2name],
[int nlink],
[int inode] )

Get symbolic link status.

Description

The lstat() primitive shall be equivalent to stat, except when path refers to a symbolic link. In that case lstat shall return information about the link, while stat shall return information about the file the link references.

For symbolic links, the mode member shall contain meaningful information when used with the file type macros, and the size member shall contain the length of the pathname contained in the symbolic link. File mode bits and the contents of the remaining members of the stat structure are unspecified. The value returned in the size member is the length of the contents of the symbolic link, and does not count any trailing null.

Parameters

For regular files, the file size in bytes.

For symbolic links, the length in bytes of the path-name contained in the symbolic link.

For a shared memory object, the length in bytes.

For a typed memory object, the length in bytes.

For other file types, the use of this field is unspecified.

path	String containing the file path.
size	Optional integer, if specified is populated with the size of the related file in bytes.
mtime	Optional integer, populated with the files modification time (See: time).
ctime	Optional integer, populated with the time of the last status change.
atime	Optional integer, populated with the last access time.
mode	Optional integer, mode of file ((see File Modes )).
uid	Optional integer, user identifier of the file.
uid2name	User name associated with the file uid.
gid	Optional integer, group identifier of the file.
gid2name	Group name associated with the file gid.
nlink	Optional integer, number of hard links to the file.
inode	Optional integer, populated with the file-system internal node number.

Returns

The lstat() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

ltrim

string ltrim( string str,
[string chars = " \\t\\r\\n"] )

Chomp characters from the front of a string.

Description

The ltrim() primitive removes leading (or left) characters from the specified string.

The default is to remove all tabs, spaces and newline characters. If chars is specified, then all characters within the trimchar string are removed from the beginning of the string.

Returns

Returns a copy of string with all leading white space characters removed. (spaces, tabs and newlines by default).

Portability

n/a

macro

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

decl	List containing the macro declaration, including scoping flags, macro name and the function body.

Note:

This interface should be considered as a internal primitive, reserved for exclusive use by the GRIEF Macro Compiler and may change without notice. Management of macro definitions plus any associated argument binding shall be handled automatically by the compiler.

Registering an ill-formed macro declaration shall have undefined effects, most likely resulting in GRIEF crashes.

Returns

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

Portability

n/a

macro_list

list macro_list( [string pattern = NULL] )

Retrieve list of current macros.

Description

The macro_list() primitive retrieves a sorted list of all defined macros.

The optional pattern is a regular expression similar to that accepted by the command line shells (See: file_match), providing an inclusion filter.

Parameters

pattern

Optional string value containing the macro-name pattern to be applied against each name, only returning the matching. A macro-name expression is a shell style regular expression (See: file_match) (e.g. * for wildcard, ? for wild-character, and [..] to select a range of characters).

Returns

The macro_list() primitive returns a list of strings each containing the name of a macro.

Portability

n/a

make_list

list make_list( ... )

Build an evaluated list.

Description

The make_list() primitive builds a new list constructed from the specified arguments. Each of the specified arguments shall be evaluated and appended the end of the list. This is in contrast to the quote_list primitive which does not evaluate any of the arguments.

Parameters

...	One or more values to be made into list elements.

Returns

The make_list() primitive returns the built list.

Portability

n/a

make_local_variable

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

sym	Symbol reference.
...	Optional additional symbol references.

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

mark

int mark( [int type = MK_NORMAL] )

Toggle the anchor status.

Description

The mark() primitive toggles the status of the marked region. If the anchor is currently dropped it shall be raised, and if raised it shall be dropped.

To be independent of the current state macros should generally utilise drop_anchor and raise_anchor, with mark reserved for keyboard bindings.

Parameters

type	Optional anchor type to be dropped, if omitted a MK_NORMAL (1) mark shall be dropped.

Value	Constant	Description
1	MK_NORMAL	A normal mark.
2	MK_COLUMN	A column mark.
3	MK_LINE	A line mark.
4	MK_NONINC	A non-inclusive mark.

Returns

The mark returns 1 if successful, otherwise 0 on error.

Portability

Unlike BRIEF the anchor status is always toggled.

BRIEF logic was equivalent to the following. If type was stated and an anchor of a different type current exists, the anchor is converted.

if (! inq_marked() || type) {
    drop_anchor(type);
} else {
    raise_anchor();
}

mark_line

int mark_line( int flag,
[int toggleall],
[int bufnum],
[int lineno = 0],
[int marker = L_MARKED] )

Create a line marker.

Description

The mark_line primitive controls the value of the user defined line marker within the current buffer. This mark maybe be utilised by macro developers to maintain a collection of lines on which can then can be queried using find_marker() for additional processing.

The flags parameter controls the mark value; if non-zero true then the marker is set otherwise it is cleared. When toggleall is stated then the mark status of all lines is toggled, ignoring the flag specification.

bufnum and lineno allow explicit buffer and line number references to be stated, otherwise if omitted the current buffer and/or associated line number shall be used.

marker is the optional marker against which to search, by default L_MARKED. Only L_MARKED or one of the L_USERx definitions maybe be specified.

Note:

Markers are only a temporary resource which maybe cleared when line are modified, deleted etc.

Returns

The mark_line primitives returns 1 if the marker was already set, 0 if the marker was not set, otherwise -1 when beyond the end of the buffer.

Compatibility

The options bufnum, lineno and marker are GriefEdit extensions.

message

int message( string format,
... )

Display a message on the command line.

Description

The message() primitive is used to display a message on the prompt line at the bottom of the screen. format is a string and may contain printf-like % formatting characters. The following arguments format and so forth are integer or string expressions used to satisfy the % formatting options.

This primitive may be used to display informational messages on the bottom of the screen; if error messages are to be displayed then the error primitive macro should be used instead.

Parameters

format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Format Specification

A format specification, which consists of optional and required fields, has the following form:

%[FLAGS] [WIDTH] [.PRECISION] [PREFIXES] type

Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is simply copied. For example, to print a percent-sign character, use %%.

The optional fields, which appear before the type character, control other aspects of the formatting, as follows:

type	Required character that determines whether the associated argument is interpreted as a character, a string, or a number.
flags	Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.
width	Optional number that specifies the minimum number of characters output.
precision	Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values.

The following format types are supported;

Type	Description
%d	Print an integer expression. Options such as %03d can be used to perform zero insertion and supply a field width.
%i	Print an integer expression, same as %d.
%u	Print an unsigned expression.
%x	Print integer expression in hex.
%t	Print using the symbol natural type (ie d = integers and s = strings).
%o	Print integer expression in octal.
%s	Print a string. Field width and alignments are allowed.
%c	Print a character.
%p	If its less than a second since the last call to message (or error), then don’t display the message. This is used by macros which want to print progress messages.
%e	Double signed value having the form [-]d.dddd e[sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or.
%E	Double identical to the e format except that E rather than e introduces the exponent.
%f	Double signed value having the form [ ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
%g	Double signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than 4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
%G	Double identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).
%n	Number of characters successfully written so far to the stream or buffer; this value is stored in the integer variable given as the argument.
%b	Print integer expression in binary.
%B	Print integer expression as a decoded binary, using the bit values as described within the secondary string parameter of the form; `<base><arg>`Where <base> is the output base expressed as a control character, e.g. \10 gives octal; \20 gives hex. Each arg is a sequence of characters, the first of which gives the bit number to be inspected (origin 1), and the next characters (up to a control character, i.e. a character <= 32), give the name of the register. Thus:

Flags

The following flags are supported.

Flag	Description	Default
-	Left align the result within the given field width.	Right align.
+	Prefix the output value with a sign (+ or -) if the output value is of a signed type.	Sign appears only for negative signed values ().
0	If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored.	No padding.
<space>	Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.	No blank appears.
#	When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Ignored when used with c, d, i, u, or s.	No blank appears. Decimal point appears only if digits follow it. Decimal point appears only if digits follow it. Trailing zeros are truncated.

Prefixes

The following prefixes are supported.

Prefix	Description
l	User long format for printing, e.g. floats are printed with full double-precision.

Width

The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values depending on whether the flag (for left alignment) is specified until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).

If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

Precision

The third optional field of the format specification is the precision specification. It specifies a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output, as shown below:

"%.0d", 0   // characters output

If the precision specification is an asterisk (*), an int argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.

The type determines the interpretation of precision and the default when precision is omitted, as shown in the following table.

Type	Description	Default
c,C	Character is printed.
d,i,u,o,x,X	Minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.	Default precision is 1.
e,E	Number of digits to be printed after the decimal point. The last printed digit is rounded.	Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
f	Number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.	Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
g,G	Maximum number of significant digits printed.	Six significant digits are printed, with any trailing zeros truncated.
s	Maximum number of characters to be printed.	Characters in excess of precision are not printed. Characters are printed until EOS is encountered.

Examples

String output

message("See %s %s.", "spot", "run");

message("%pMacro completed: %d%%", (val*100)/total);

Binary output

message("val=%B", 3, "\\10\\2BITTWO\\1BITONE\\n")

shall produce the output.

val=3<BITTWO,BITONE>

Return

The message() primitive returns the number of characters printed.

Portablility

Many of the format options are GriefEdit extensions, including %b, %n, %t, %B and * support.

The original implementation has a void declaration and returns nothing.

The standard interface only permits upto 6 arguments, whereas GriefEdit is unbound.

CRisPEdit™ allows the second argument to be a list expression, which emulates a vsprintf() style of operation. In this case, the first element of the list is assumed to be a string format descriptor, and subsequent elements of the list are the arguments to print; this feature is not currently supported.

mkdir

int mkdir( string pathname,
int mode = 0755 )

Create a directory.

Description

The mkdir() primitive creates a new subdirectory with name path. The path can be either relative to the current working directory or it can be an absolute path name.

mode is the protection codes used to create the directory. If omitted, the value 0755 (-rwxr-xr-x) will be used.

Returns

The mkdir() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

mktemp

string mktemp( string path )

Make a temporary filename.

Description

The mktemp() primitive shall replace the contents of the string path to by template by a unique filename and return template.

The application shall initialize template to be a filename with six trailing ‘X’s. mktemp() shall replace each X with a single byte character from the portable filename character set.

Returns

The mktemp() primitive shall return the string template. If a unique name cannot be created, template shall point to an empty string.

mode_string

string mode_string( [int mode],
[int format = 0],
[string path] )

Conversion stat mode to a string representation.

Description

The mode_string() primitive decodes the specified mode into a human readable form using a style similar to ls long listing format output detailing type and permissions, for example

drwxr-xr-x-

Mode String

The decoded mode string consists of a ten character string, using the following format ((see File Modes ))

<type> <owner> <group> <other> <sticky>

Type

The first character indicates the file type and is not related to permissions, when format is omitted or (0) shall be on of the following:

’d’	Directory.
’c’	Character-device.
’b’	Block-device.
’l’	Link.
’p’	Fifo/pipe.
’s’	Sockets.
’n’	Name.
’D’	Door.
’-’	Normal.

The alternative format shall be used when format is given as a non-zero value. In addition if specified source shall be utilised to verify the status of the link.

’/’	Directories.
’-’	Character devices.
’+’	Block devices.
’~’	Directory link.
’!’	Broken link.
’@’	Link.
’\|’	Fifo/pipe.
’=’	Sockets.
’$’	Name/door.
’*’	Executable.
’ ‘	Normal (space).

Permissions

Following are three permission sets defining the user, group and other access rights.

Each of the three characters represent the read, write, and execute permissions for each of the groups in the order (rwx).

’r’	Read permission.
’w’	Write permission.
’x’	Execute permission
’-’	No associated permission read, write or execute.

Sticky

The trailing character details the one of two special attributes.

’S’	S_ISUID is set.
’T’	S_ISVTX is set.

Parameters

mode	Optional mode specification, otherwise the associate mode of current buffer is decoded.
format	Optional format, when stated and non-zero the <type> field is decoded using an alternative form.
path	Optional source of the mode, is supplied shall be utilised to verify the status of links.

Returns

Returns the decoded mode string.

Portability

A GriefEdit extension.

modf

float modf( float num,
float & mod )

Decompose a floating-point number.

Description

The modf() primitive breaks the argument num into integral and fractional parts, each of which has the same sign as the argument. It stores the integral part as a double in the object mod.

An application wishing to check for error situations should set errno to 0 before calling modf(). If errno is non-zero on return, or the return value is NaN, an error has occurred.

Returns

Upon successful completion, modf() returns the signed fractional part of num.

If num is NaN, NaN is returned, errno may be set to EDOM.

If the correct value would cause underflow, 0 is returned and errno may be set to ERANGE.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

module

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 allowed 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.

move_abs

int move_abs( [int line = -1],
[int column = -1],
[int bufnum],
[int clip = FALSE] )

Move to an absolute location in the buffer.

Description

The move_abs() primitive moves the buffer cursor to an absolute location, with top of the buffer being position (1,1).

If a parameter is 0 or omitted, the corresponding line or column coordinate is unchanged; positive values set the line and/or column.

Parameters

line	Optional integer specifying the line number, if positive the cursor is set to the specified line.
column	Optional integer specifying the column number, if positive the cursor is set to the specified column.
bufnum	Optional buffer number, if specified the associated buffer is affected, otherwise the current buffer.
clip	Optional int flag, if non-zero the resulting buffer cursor shall be clipped to the buffer size.

Returns

The move_abs() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

bufnum and clip are extensions.

move_edge

int move_edge( [int direction],
[int amount] )

Modify a window.

Description

The move_edge() primitive modifies the edges of tiled window, whereas for popup’s allow the user to increase or decrease the size, and also move the window around the screen.

Example

Moves the lower edge of the current window up four lines.

move_edge(2, -4);

Parameters

direction	Optional integer direction stating the edge on which the move operation occurs resizing the associated windows (as above), if omitted the user is prompted.
amount	Optional integer expression stating the number or characters or lines to move the window. The number is relative to the top left of the screen, so positive numbers move away from the origin (0, 0) and negative numbers towards the origin. If not specified, the user will be prompted to move the edge with the arrow keys.

Returns

The move_edge() primitive returns non-zero if cursor moved, otherwise 0 if cursor did not move.

Portability

n/a

move_rel

int move_rel( [int lines = 1],
[int cols = 1] )

Move to a relative location in the buffer.

Description

The move_rel() primitive moves the buffer cursor to a new position relative to the current position.

If a parameter is 0 or omitted, the corresponding line or column coordinate is unchanged. Positive values move the cursor towards the end of the line and/or column, likewise negative values move towards the beginning of the line and/or column.

Parameters

lines	Optional integer specifying the line number, if positive the cursor moves forwards the end of the file, likewise a negative moves to backwards towards the top.
cols	Optional integer specifying the column number, if positive the cursor moves forwards the front of the line, likewise a negative moves to backwards towards the beginning.

Returns

The mov_rel() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

next_buffer

int next_buffer( [int sysflag = 0],
[int previous],
[int tab] )

Identifier of the next buffer.

Description

The next_buffer() primitive retrieves the buffer identifier of the next buffer after the current buffer in the buffer list, optionally filtering system buffers.

The buffer list, which is maintained by the GRIEF kernel, is a circular list of all buffers. Upon the end of list being reached, the first buffer on the list is returned as the next.

Note:

The next_buffer primitive does not alter the current buffer, the set_buffer can be used to select the returned buffer.

Parameters

sysflag	Optional system buffer filter selection. If either omitted or zero system buffers shall be filtered from the returned identifiers. Otherwise all buffers including system shall be returned.
prev	Optional boolean flag, if stated as non-zero then the previous buffer in the buffer list is retrieved.
tab	Reserved for future use; tab identifier.

Returns

The next_buffer() primitive returns the buffer identifier of the next or previous buffer.

Portability

n/a

next_char

int next_char( [int characters = 1] )

Move to the next character.

Description

The next_char() primitive moves the current buffer position forward to the next character, wrapping around line ends when encountered.

The primitive is similar to right except it moves physical characters as opposed to logic characters, as the result tabs and newlines are both treated as one character.

Within navigating binary files newlines are not implied, as such are not counted within the character count.

Parameters

characters

Optional number of characters to move forward in the buffer, which if omitted is 1.

Returns

The next_char() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

next_window

int next_window( int winnum )

Obtain the next window identifier.

Description

The next_window() primitive retrieves the window identifier of the next window from the internal window list relative to the specified window, if omitted the current window shall be referenced.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

The next_window() primitive returns the window identifier of the next tiled window from the window list.

If there is only a single window, then the same identifier as the specified shall be returned.

Example

Iterate though all windows

int curwin, win;

curwin = inq_window();
if ((win = curwin) != -1) {
    do {

        // ... process

    } while ((win = next_window(win)) != curwin);
}

Portability

n/a

nothing

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

nth

declare nth( list expr,
int idx,
[int idx2 ...] )

Extract the indexed list item.

Description

The nth() primitive retrieves the value of the referenced list element at the index idx from the list expression expr. The first element of a list is element 0; the nth primitive allows lists to be treated like arrays. The last element of a list is length_of_list minus one.

The nth() primitive is an efficient way of accessing random elements within a list, than for example using the lists primitive car and cdr. In addition nth can access access multidimensional lists as a single operation.

Note:

This primitive is the underlying implementation of the list offset operator [], which are converted by the GRIEF Macro Compiler.

Furthermore, this interface should be considered as an internal primitive. As this primitive is not compatible with the nth macro of CRiSP ™ its direct usage is not recommended, instead rely on the offset operator [].

Parameters

expr	List expression.
idx	Integer index.
...	None or more integer indexs of sub-elements.

Returns

The nth() primitive returns the value of the specified element from the referenced list, otherwise NULL on error.

Portability

GRIEF uses an alternative prototype to support support multidimensional lists, unlike CRiSP ™ which only supports a single dimension.

nth(expr, list_expr)

As such for portability nth use should be restricted.

output_file

int output_file( [string filename] )

Change the output file-name.

Description

The output_file() primitive changes the file-name associated with the current buffer to filename; the new name should be unique, it cannot be the file-name of an exist buffer or file.

By default the associated file-name associated with a buffer is the file-name specified on an edit_file or create_buffer.

If filename is omitted the user shall be prompted as follows;

Enter new output file name:

Note:

Once changed backups shall be created under the new file-name, not the original name.

Parameters

filename

Optional string containing the new output file-name, if omitted the user is prompted.

Returns

The output_file() primitive returns greater than zero on success, otherwise zero or less on error.

The following error conditions shall be reported to the user;

filename must be a unique buffer.

Duplicate buffer name 'xxx'.

Unless a system buffer stated filename must not already exist on the file-system.

Output file 'xxx' already exists.

Portability

n/a

page_down

int page_down( [int pages = 1] )

Move position down a page.

Description

The page_down() primitive moves the buffer position down or forward one or more pages down, with a page being the current window size in lines.

Parameters

pages

If supplied, states the number of pages to move the cursor forward, otherwise the cursor is moved 1 page.

Returns

The page_down() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

pages is a GriefEdit extension.

page_up

int page_up( [int pages = 1] )

Move position up a page.

Description

The page_up() primitive moves the buffer position up or backwards one or more pages up, with a page being the current window size in lines.

Parameters

pages

If supplied, states the number of pages to move the cursor backwards, otherwise the cursor is moved 1 page.

Returns

The page_up() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

pages is a GriefEdit extension.

parse_filename

int parse_filename( string fullname,
[string &drive],
[string &path],
[string &filename],
[string &ext] )

Parse a file into its components.

Description

The parse_filename() primitive parsing and brakes the file name fullname into it components.

Note:

Since this primitive is not portable outside of a DOS/Windows environment, its use is not adviced.

Parameters

fullname	A string containing the file-name to be parsed.
drive	Optional string variable when supplied to be populated with the drive component, if any.
path	Optional string variable when supplied to be populated with the path component.
filename	Optional string variable when supplied to be populated with the file-name component.
ext	Optional string variable when supplied to be populated with the file extension.

Returns

The parse_filename() primitive returns non-zero on success denoted the fullname was parsed, otherwise zero was unsuccessful and -1 if an empty fullname was supplied.

Portability

Provided for BRIEF compatibility.

paste

int paste( [int syspaste = FALSE] )

Insert scrap buffer at cursor location.

Description

The paste() primitive insert the contents of the scrap buffer at the current cursor location.

The buffer is pasted according to the type of the mark which created it:

Normal or non-exclusive mark, the scrape is inserted before the current position.
Line mark, the scrape is inserted before the current line.

Parameters

syspaste

Optional boolean flag, is specified and is non-zero, then the text contents of the operating system buffer shall (e.g. clipboard under WIN32) shall be inserted into the current buffer where the cursor is located, if the feature is supported/available.

Returns

The paste() primitive returns 1 on success, otherwise 0 on failure.

Portability

n/a

pause

void pause()

Pause keystroke definition.

Description

The pause() primitive pauses a keyboard macro definition.

Usually all keyboard input typed during a remember sequence is saved in the keyboard macro buffer. Pressing a key assigned to pause causes the remember sequence to suspend saving the characters.

Parameters

none

Returns

nothing

Portability

n/a

pause_on_error

int pause_on_error( [int pause = NULL],
[int echo = TRUE] )

Set the error display mode.

Description

The pause_on_error() primitive controls the automatic pausing upon a macro error; by default the pause status is off.

On the execution of the error primitive plus the internal equivalent, the pause status is checked and when enabled error messages shall be displayed with a .. suffix and GriefEdit shall await for the user to acknowledge the condition via a key-press before execution continues.

If pause is specified as a non-negative (>= 0) then the current setting is set to the pause value of the integer expression, whereas a negative value (-1) behaves like a inquiry primitive reporting the current value without change. Otherwise if omitted the current status is toggled.

Unless echo is stated as FALSE, upon modification of the pause state, the new status shall be echoed on the command as follows

Pausing errors on.

Pausing errors off.

Parameters

pause	Optional int flag, when a non-negative value (>=0) it states the new pause status, a negative value (-1) reports the current value without change, otherwise if omitted the current pause state is toggled.
echo	Optional int flag, when stated as FALSE the function is silent, otherwise the change in the pause state is echoed on the command prompt.

Returns

The pause_on_error function returns the previous pause state.

Portability

echo is a GriefEdit extension.

Example

The following examples enables error acknowledgement during the execution of the macro subshell() and restores the previous status on completion.

int state = pause_on_error(TRUE);
subshell();
pause_on_error(status, FALSE);

pause_on_message

int pause_on_message( [int pause = NULL],
[int echo = TRUE] )

Set the message display mode.

Description

The pause_on_message() primitive controls the automatic pausing upon a macro message; by default the pause status is off.

On the execution of the message primitive plus the internal equivalent, the pause status is checked and when enabled error messages shall be displayed with a .. suffix and Grief shall await for the user to acknowledge the condition via a key-press before execution continues.

Unless echo is stated as FALSE, upon modification of the pause state, the new status shall be echoed on the command as follows

Pausing all messages on.

Pausing all messages off.

Parameters

pause	Optional int flag, when a non-negative value (>=0) it states the new pause status, a negative value (-1) reports the current value without change, otherwise if omitted the current pause state is toggled.
echo	Optional int flag, when stated as FALSE the function is silent, otherwise the change in the pause state is echoed on the command prompt.

Returns

The pause_on_message function returns the previous pause state.

Portability

echo is a GriefEdit extension.

Example

The following examples enables error acknowledgement during the execution of the macro subshell() and restores the previous status on completion.

int state = pause_on_message(TRUE);
subshell();
pause_on_message(status, FALSE);

perror

string perror( [int errnum = errno],
string format,
... )

Print error.

Description

The perror() primitive shall map the error number specified by errnum to a language-dependent error message, which shall be written to the standard error stream as follows:

<message> : <error - description>

Parameters

errnum

Integer value of the error condition to be decoded, if omitted the current system errno is decoded.

Returns

The perror function returns a string containing the formatted message with a trailing description of the the error value.

Portability

A GriefEdit extenions.

playback

int playback( [int macroid] )

Replay a keystroke macro.

Description

The playback() primitive replays the previously saved keyboard macro macro.

Parameters

macroid

Optional integer macro identifier specifies the keyboard against which to derive the buffer name, if omitted the current macro identifier is utilised.

Returns

The playback() primitive returns greater than or equal to zero if playback was successful, otherwise less than zero on error.

Portability

n/a

pop

declare pop( list expr )

Pop the last element.

Description

The pop() primitive removes and returns the last value of the list, shortening the list by one element.

Returns

The pop() primitive returns the element removed, otherwise NULL on error.

Example

Iterator the list from the end, removing and then printing each element in the process;

list l = {"one", "two", "three", "four"};

while (length_of_list(l)) {
    message("%s", pop(l));
}

the resulting output

four
three
two
one

Portability

A GriefEdit extension

pow

float pow( float x,
float y )

Raise to power.

Description

The pow() primitive returns x raised to the power of y.

Returns

Returns the computed value.

If y is 0, the function returns 1.

If x is negative and y is non-integral, the function sets errno to EDOM and returns -HUGE_VAL. If the correct value is outside the range of representable values, +HUGE_VAL is returned according to the sign of the value, and the value of ERANGE is stored in errno.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

prev_char

int prev_char( [int characters = 1] )

Move to the previous character.

Description

The prev_char() primitive moves the current buffer position backward to the previous character, wrapping around line ends when encountered.

The primitive is similar to left except it moves physical characters as opposed to logic characters, as the result tabs and newlines are both treated as one character.

Within navigating binary files newlines are not implied, as such are not counted within the character count.

Parameters

characters

Optional number of characters to move backward in the buffer, which if omitted is 1.

Returns

The prev_char() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

previous_buffer

int previous_buffer( [int sysflag = 0],
[int tab] )

Identifier of the previous buffer.

Description

The previous_buffer() primitive retrieves the buffer identifier of the previous buffer after the current buffer in the buffer list, optionally filtering system buffers.

The buffer list, which is maintained by the GRIEF kernel, is a circular list of all buffers. Upon the beginning of list being reached, the last buffer on the list is returned as the previous.

Note:

The previous_buffer primitive does not alter the current buffer, the set_buffer can be used to select the returned buffer.

Parameters

sysflag	Optional system buffer filter selection. If either omitted or zero system buffers shall be filtered from the returned identifiers. Otherwise all buffers including system shall be returned.
tab	Reserved for future use; tab identifier.

Returns

The previous_buffer() primitive returns the buffer identifier of the previous buffer.

Portability

n/a

print

int print()

Print formatted string to stdout.

Description

The print() primitive sends the contents of the currently marked area to the printer.

Parameters

none

Returns

0 for success, -1 for printer busy, less than -1 for other printer errors or no marked block.

Portability

n/a

printf

void printf( string format,
... )

Print formatted string to stdout.

Description

The printf() primitive can be used for debugging macros, although its use is questionable. It exists for compatibility reasons with BRIEF. It causes the formatted string to be sent directly to stdout, bypassing all of Griefs internal screen manipulations.

The format primitive is similar to the C printf() primitive, exporting the formatted result to stdout. Use of this interface is debatable as output is written to standard out, which is also the primary interface to the terminal/display.

The printf() primitive produces formatted output according to the format specification format into the diagnostics log. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.

This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.

Parameters

format	String containing the <Format Specification>.
...	Optional list of arguments which should correspond to the values required to satisfy the format specification.

Returns

nothing

Portability

The standard function has a void declaration and returns nothing.

process

void process()

Invoke a Grief engine.

Description

The process() primitive invokes an instance of the Grief command-loop recursively by accepting keystrokes and calling the functions assigned thru the associated key bindings (See: assign_to_key).

process is usually invoked after building the required environment including buffers and/or windows with an associated keyboard. Process nesting may occur to any depth, within the bounds of Griefs maximum nesting level. The

current command loop executes until the session is terminated by an exit command.

Parameters

none

Returns

nothing

Portability

n/a

process_mouse

void process_mouse( [int b1],
[int b2],
[int b3],
int x,
int y )

Process mouse event.

Description

The process_mouse() primitive allows an external mouse event to be processed; some mice types are handled internally whereas others require macro support.

Parameters

b1, b2, b3	Button states, zero for up otherwise non-zero for down.
x, y	Screen coordinates.

Returns

nothing

Portability

n/a

profile

void profile( [int flags] )

Profiling support.

Description

The profile() primitive controls the profiler flags.

If flags is omitted, then the current profiler state is toggled, otherwise sets the profiler state to the specified flags.

Returns

nothing

push

declare push( list lst,
declare value ... )

Add an element onto a list.

Description

The push() primitive adds one or more elements value to the end of the list.

Returns

The push() primitive returns a copy of the value added.

Portability

A GriefEdit extension.

push_back

void push_back( int key,
[int front],
[int x],
[int y] )

Push back a character into the keyboard.

Description

The push_back() primitive pushes the specified key code key into the keyboard input buffer.

The front is zero or omitted the key shall pushed to the back of the keyboard buffer, otherwise to the front.

Parameters

key	Key code.
front	Optional boolean value, which if specified and is TRUE (non-zero) then the character is pushed pushed at the front of any previous characters. Otherwise if either omitted or FALSE (zero) then the key is pushed back after all previously pushed back characters.
x, y	Mouse position, required when pushing back mouse events.

Returns

nothing

Portability

Mouse support is a GriefEdit extension.

put_nth

declare put_nth( symbol,
... )

Modify a list element.

Description

The put_nth() primitive modifies the element within the specified list.

Note:

This primitive is generally not utilised directly as the GRIEF language supports a list offset operator of the form [idx].

Returns

The put_nth() primitive returns the value of the referenced element, otherwise NULL if the index is out of bounds.

Portability

Standard CRiSP ™ implementation utilises an alternative prototype which does not support multidimensional lists.

put_nth(expr, list_expr, value)

As such for portability put_nth use should be restricted.

put_parm

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

argidx	Integer argument index of the parameter passed to the current macro which is to be assigned a value; parameter indexs start at zero.
val	Value to be assigned to the parameter; the value type should match the type of the parameter.
optional	Optional boolean value, if true missing parameters shall not generate an error, otherwose if false or omitted an error will be echoed.

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

putenv

void putenv( string name,
[string value] )

Set an environment variable.

Description

The putenv() primitive shall use the string arguments to set the value of an environment variable.

The arguments must construct a string of the form

"name=value"

This construction may be stated by one or two means. Firstly by the explicit string arguments name and value, or alternatively a single argument name already correctly formed containing both components separated by an embedded = within the string.

Parameters

name	String containing the name of the environment variable and if value is omitted should also contain the associated value separated by an equals =.
value	Optional value to be assigned.

Returns

Upon successful completion, putenv shall return one on success, otherwise zero and set errno to indicate the error.

Portability

A GriefEdit extension.

quote_list

list quote_list( ... )

Build an unevaluated list.

Description

The quote_list() primitive builds a list of the specified arguments unchanged and unevaluated. This is in contrast to the make_list primitive which shall evaluate which of the arguments.

quote_list is the one of the mechanisms for creating list literal constants, also see make_list. It is normally used for assigning initial values to lists, or for passing an anonymous macro to another macro.

Example

An example usage results in the list contains two strings followed by two integers.

list l;
l = quote_list("first", "second", 1, 2);

As an alternative the following syntax implies the use of quote_list by the GRIEF Macro compiler.

list l = {"first", "second", 1, 2};

Parameters

...	One or more values to be made into list elements.

Returns

The quote_list() primitive returns the built list.

Portability

n/a

quote_regexp

string quote_regexp( string text )

Quote regexp special characters.

Description

The quote_regexp() primitive quotes (i.e. prefixes with a backslash) the following set of predefined characters in the specified string text, representing most of the regular expression special characters.

The predefined characters are;

asterisk (*)
backslash (\)
caret (^)
curvy brackets ({})
dollar sign ($)
parenthesis (())
percentage (%)
period (.)
pipe (|)
plus sign (+)
question mark (?)
square brackets ([])

Parameters

text	String containing the text to quote, protecting special regular expression characters..

Returns

The quote_regexp() primitive returns the resulting quoted string.

Portability

n/a

raise_anchor

int raise_anchor()

Raise the last dropped mark.

Description

The raise_anchor() primitive raises the last anchor mark that was dropped.

If no mark is dropped, this primitive has no effect.

Parameters

none

Returns

The raise_anchor returns 1 if successful, otherwise 0 on error.

Portability

n/a

rand

int rand( [int upper] )

Generate a random number.

Description

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).

Parameters

upper

Optional integer stating the upper range of the returned random number, if omitted 2^32.

Returns

The rand primitive returns a random number in the range 0..2^31 or 0..upper if a positive upper value is stated.

re_comp

list re_comp( [int flags],
string pattern,
[string &error] )

Compile a regular expression.

Description

The re_comp() primitive is reserved for future development.

The re_comp primitive converts a regular expression string (RE) into an internal form suitable for pattern matching.

Parameters

flags	Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search and replace.
pattern	String containing the pattern to translate.
error	Optional string reference, on an error shall be populated with a description of the error.
parms	Optional string containing configuration parameters.

Returns

The re_comp() primitive returns list containing the compiled expression, otherwise a null list.

Warning:

DONOT modify the result otherwise you shall encounter undefined results during search operations.

Portability

n/a

re_delete

int re_delete( list handle )

Delete a compiled expression.

Description

The re_delete() primitive

Parameters

handle -

Returns

The re_delete() primitive returns 1 on success, otherwise 0.

Portability

n/a

re_result

int re_result( [int capture],
[string &value],
[int &offset],
[int &length] )

Retrieve search captures.

Description

The re_result() primitive retrieves the results of the last regular expression re_search operation. In addition the prior search must have had SF_CAPTURES enabled.

Warning:

The captured regions reference the original searched object, as such the original buffer, list or string *must not be modified prior to executing re_result.

Parameters

capture	Integer capture index, see details below.
value	String variable reference, is populated with the value of the referenced capture.
offset	Optional integer variable reference, is populated with the starting offset of the capture within the original source.

Capture Index

Value	Description
1 .. 9	Xth captured expression.
CAPTURE_BEFORE	Everything prior to matched string
CAPTURE_ARENA	Entire matched string.
CAPTURE_AFTER	Everything after to matched string
CAPTURE_LAST	Last parenthesized pattern match.

Returns

The re_result() primitive returns the length of the capture, otherwise -1 on error.

Portability

A GriefEdit extension.

re_search

int re_search( [int flags],
[string pattern],
[declare object],
[int start],
[int lensym] )

Search for a string.

Description

The re_search() primitive is a generalised search interface, combining the functionality of the more specialised search primitives but presenting consistent and stateless search capabilities.

In addition both the re and case modes are explicit based upon the flags values.

Parameters

flags	Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search.
pattern	A string containing the pattern to be matched.
object	Optional object to be searched. The search depends on the type of object. If object is a string, then a string search is performed. If object is a list then a list search is done. Ifn an integer the buffer associated with the stated buffer number is searched, otherwise if omitted a search on the current buffer is performed.
start	Optional integer index for list objects, states the element offset at which search operation shall start. If omitted, the search is started from the beginning of the list.
lensym	Optional integer reference for string objects is populated with the length of the matched region.

Flags

General control flags.

Constant	Description
SF_BACKWARDS	Search in backwards direction. By default searchs are performed in a forward direction; only meaningful for buffer searches or translates.
SF_IGNORE_CASE	Ignore/fold case.
SF_BLOCK	Restrict search to current block.
SF_LINE	Line mode.
SF_LENGTH	Return length of match.
SF_MAXIMAL	BRIEF maximal search mode.
SF_CAPTURES	Capture elements are retained.
SF_QUIET	Do not display progress messages.
SF_GLOBAL	Global translate (*); re_translate only.
SF_PROMPT	Prompt for translate changes; re_translate only.
SF_AWK	awk(1) style capture references.
SF_PERLVARS	perl(1) style capture references.

(*) PROMPT is given priority over GLOBAL.

Syntax selection, one of the following mutually exclusive options can be stated.

Constant	Description
SF_NOT_REGEXP	Treat as plain test, not as a regular expression.
SF_BRIEF/SF_CRISP	BRIEF/CRiSP/GRIEF expressions (default).
SF_UNIX	Unix regular expressions.
SF_EXTENDED	Extended Unix expressions.
SF_PERL	PERL syntax.
SF_RUBY	Ruby syntax.

Returns

The re_search() primitive return is dependent on the type of the object searched; matching the corresponding specialised primitive search_fwd, search_list and search_string. These are summarised below.

Object Type	return
buffer	on success the length of the matched text; otherwise 0 if no match or -1 on error.
list	on success index of the matched element, otherwise -1 if on match.
string	on success the index of first character of match, otherwise 0 if no match.

On error re_search returns -1.

Portability

n/a

re_syntax

int re_syntax( [int re],
[int case],
[int capture] )

Set the regular expression mode.

Description

The re_syntax() primitive configures the global regular expression syntax mode to the mode re. By default, the mode is set to the RE_BRIEF regular expression syntax.

re_syntax affects the defaults of the following primitives;

search_string
search_list
search_fwd and search_back
translate

The supported regular expression syntax modes.

Value	Constant	Description
0	RE_BRIEF	BRIEF/Crisp Edit mode.
1	RE_UNIX	Basic Unix syntax.
2	RE_EXTENDED	POSIX Extended Unix.
3	RE_PERL	Perl.
4	RE_RUBY	Ruby style syntax.

Parameters

re	Optional integer value, specifying the new regular expression syntax to by applied. If omitted, the current value is unchanged.
case	Optional integer value, specifying the new state of the global case mode. If case is specified and is zero, then searches are performed as case insensitive, otherwise when non-zero they shall be case sensitive. If omitted, the current value is unchanged.
capture	Optional integer value, specifying the new state of the global replacement pattern reference mode. If RE_PERLVARS then Perl style capture references shall be utilised, when RE_AWKVARS AWK style capture references are utilised, otherwise then 0 the style is dependent on the re mode; see translate. If omitted, the current value is unchanged.

Returns

The re_syntax() primitive returns the current/resulting regular expression syntax mode.

Portability

The case and re arguments are GriefEdit extensions.

re_translate

int|string re_translate( [int flags],
string pattern,
[string replacement],
[declare object] )

Search and replace.

Description

The re_translate() primitive is a generalised search and replace interface, combining the functionality of the more specialised primitives but presenting consistent and stateless search capabilities.

Parameters

flags	Optional integer flags, one or more of the SF_XXX flags OR’ed together control the options to be applied during the search and replace.
pattern	String containing the pattern to translate.
replacement	String containing the replacement expression for each matched pattern. It may contain references to the pattern’s capture groups by special variables using one of three forms GRIEF, AWK or Perl, see below.
object	Optional object to be searched. The search depends on the type of object. If object is a string, then a string search is performed; translating a string provides similar functionality to awk’s sub() and gsub() functions. If object is a list then a list search is done. If an integer the buffer associated with the stated buffer number is searched, otherwise if omitted a search on the current buffer is performed.

Special Variables

GRIEF variables - GRIEF style references.

This style take the form of of the form “\d”, where d is a numeric group number started at an index of 0; note escapes need to be preceded by an additional backslash.

Variable	Value
\0, \1 ...	Xth + 1 captured expression.

AWK Variable - AWK style references are selected using SF_AWK.

This style take the form of “\d”, where d is a numeric group number indexed from 1; note escapes need to be preceded by an additional backslash.

Variable	Value
\0	Matched string.
\1, \2 ...	Xth captured expression.
&	Match string, same as \0.

PERL Variables - PERL style references are selected using SF_PERLVARS; is it also implied under SF_PERL, SF_RUBY and SF_TRE unless SF_AWK is stated.

This style is super-set of all three forms. Capture references take the form “$x” when x is a numeric group number indexed from 1 or one of the special variables $`, $&, and $’. In addition the AWK “\x” syntax is supported, yet their use should be avoided due to the need to quote the escapes.

Variable	Value
\1, \2 ...	Old style, Xth captured expression.
$1, $2 ...	Xth captured expression.
${xx}	Xth captured expression.
$+	Last parenthesized pattern match.
$`	Everything prior to the matched string.
$&	Entire matched string.
$’	Everything after the matched string.

Returns

If object is a string, then the resulting translated string is returned.

Otherwise the re_translate() primitive returns the number of translations which occurred, otherwise -1 on error.

Portability

n/a

read

string read( [int number],
[int &status] )

Read characters from the buffer.

Description

The read() primitive reads characters up to the specified number of characters length, if omitted characters are read up to the end of the current buffer including the new-line terminator.

The current buffer position remains unchanged.

Parameters

0 - Partial, within a line.

1 - End of line.

-1 - End of file.

number	An optional number of characters to be read.
status	Optional integer variable reference to be populated with the read completion status, representing the position of the cursor at the end of the read operation;

Returns

The read() primitive returns the string read.

Portability

n/a

read_char

void read_char( [int timeout = 0],
[int mode = 0] )

Description

The read_char() primitive attempts to retrieve the next character from the keyboard.

The timeout argument specifies the handling of non key conditions, is other words when no keys are available. If a positive value the timeout argument specifies the interval in milliseconds read_char() should block waiting for a key to become ready. If the time limit expires before any key events read_char returns -1. If omitted or zero read_char shall block unconditionally until a key is available. A negative (-1) timeout shall not block returning immediately effectively polling the keyboard.

The mode parameter controls the type of keyboard event to be returned. Supported modes are as follows.

Mode	Description
0	Normal.
>0	Raw mode.
<0	Extended, returning additional keys codes including mouse.

Parameters

timeout	Optional timeout in milliseconds, if omitted or zero read_char blocks until a key-code is available, otherwise -1 shall simply poll for the next key.
mode	Optional request mode, see above.

Returns

The read_char() primitive returns the key-code, otherwise -1 on a timeout.

Portability

Use of a ‘-’1 timeout value is required to emulate BRIEF.

read_file

int read_file( [string filename],
[int glob = TRUE],
[string encoding = NULL] )

Read into the current buffer.

Description

The read_file() primitive reads the content of the specified file filename into the current buffer.

If filename is omitted the user shall be prompted as follows;

File to read:

Parameters

filename	Optional string containing the file to read, if omitted the user shall be prompted.
glob	Optional boolean flag, if either TRUE or omitted the filename shall be expanded, see expandpath.
encoding	Optional string containing the character encoding to be applied to the source file.

Returns

The read_file() primitive returns a positive value on success, 0 if the user was prompted and cancelled, otherwise -1 on error.

Portability

n/a

readlink

string|int readlink( string path,
[string &link] )

Read the contents of a symbolic link.

Description

The readlink() primitive shall place the contents of the symbolic link referred to by path in the string link.

Returns

If link is omitted the return value is a string. Upon successful completion readlink() shall return the resolved link, otherwise it shall return an empty string and set the global errno to indicate the error.

Then link is given the return value is an int. Upon successful completion, readlink shall return the count of character placed in the string. Otherwise, it shall return a value of -1, and set the global errno to indicate the error.

Portability

A GriefEdit extension.

realpath

int realpath( string pathname,
string resolved_path )

Resolve a pathname.

Description

The realpath() primitive shall derive, from the pathname an absolute pathname that names the same file, whose resolution does not involve ., .., or symbolic links.

Returns

The realpath() primitive returns 0 if successful otherwise -1 on error. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

redraw

void redraw( [int winch] )

Redraw screen.

Description

The redraw() primitive redisplays the screen.

Parameters

none

Returns

nothing

Portability

n/a

ref_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");

Note:

This interface should be considered as an internal primitive, reserved for exclusive use by the GRIEF Macro Compiler and may change without notice. Management of variable scoping and argument binding shall be handled automatically by the compiler.

Parameters

argument	Argument index.
local_symbol	Name of the local symbol used as the local alias to the referenced argument.
optional	Optional integer flag determining whether the argument is optional, if omitted is assumed FALSE.

Returns

nothing

Portability

A GriefEdit extension

refresh

void refresh()

Update the display.

Description

The refresh() primitive updates the screen flushing any pending changes.

Parameters

none

Returns

nothing

Portability

n/a

register

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.

register_macro

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

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.

Constant	Description
REG_TYPED	Character typed.
REG_EDIT	Different file edited.
REG_ALT_H	ALT-H pressed in response to a prompt.
REG_UNASSIGNED	Unassigned key pressed.
REG_IDLE	Idle time expired.
REG_EXIT	About to exit.
REG_NEW	New file edited and readin.
REG_CTRLC	CTRL-C (SIGINT) pressed during macro.
REG_INVALID	Invalid key pressed during response input.
REG_INTERNAL	Internal error.
REG_MOUSE	Mouse callback.
REG_PROC_INPUT	Process input available.
REG_KEYBOARD	Keyboard buffer empty.
REG_STARTUP	Startup complete.
REG_BOOKMARK	Bookmark dropped/deleted.
REG_INSERT_MODE	Insert mode has changed.
REG_BUFFER_MOD	Buffer has been modified.
REG_BUFFER_WRITE	Buffer write operation.
REG_BUFFER_RENAME	Buffer rename operation.
REG_BUFFER_DELETE	buffer delete operation.
REG_FILE_SAVE	File write request.
REG_FILE_WRITTEN	File write completion.
REG_FILE_CHANGE	File external change.
REG_SIGUSR1	SIGUSR1 signal trap.
REG_SIGUSR2	SIGUSR2 signal trap.

Parameters

type	Event type against which to register.
name	Name of the macro to be registered.
local	Optional int, Whether the trigger is of local or global scope. Note currently local is only effective on REG_TYPED.

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.

reload_buffer

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

Reload the buffer content.

Description

The reload_buffer() primitive is reserved for future use.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
encoding	Optional string containing the character encoding to be applied to the source file.

Returns

n/a

Portability

n/a

remember

int remember( [string|int overwrite],
[int macroid] )

Start remembering keystrokes.

Description

The remember() primitive control macro recording, starts remembering keystrokes, which can be later replayed with the playback function.

Recording is stopped by a second call to the remember macro.

The remember() primitive is not usually called as part of a macro but is usually bound to a keyboard key, for example (<F7>).

Note:

Only the macros directly executed by the user are saved within the macro. In other words top level macros, for example the resulting dialog, shall not be reported.

The pause primitive temporarily stops recording the current keystroke sequence; by default assigned to (<Shift+F7>). This feature is useful if part of the keystroke macro being remembered is different each time the macro is played back. Before the variable part of the macro, press Shift+F7. Perform the variable part and press Shift+F7 to resume recording.

When the macro is played back, it will pause at the point Shift+F7 was pressed to allow the user to perform the variable portion of the sequence. Pressing Shift+F7 then resumes playback.

Parameters

overwrite	Optional string containing whether or not the current macro should be overwritten. If either a case insensitive string contained “y[es]” or a non-zero the macro shall be overwritten. If omitted the user shall be prompted.
macroid	Optional integer macro identifier specifies the keyboard against which to store the keystrokes, if omitted the next free keyboard identifier is utilised.

Returns

The remember() primitive returns the positive identifier assigned to the keystroke macro on completion, 0 if the remember was cancelled, otherwise -1 on error or the recording began.

Portability

n/a

remove

int remove( string filename )

Remove a file.

Description

The remove() primitive deletes the file whose name is contained within the string filename.

Returns

The remove() primitive returns zero if successful, and a non-zero value (-1)f otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

rename

int rename( string old,
string new )

Rename a file.

Description

The rename() primitive causes the file whose name is indicated by the string old to be renamed to the name given by the string new.

Returns

The rename() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

replacement

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

require

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
}

Note:

autoload and require usage should generally be exclusive for any given macro object.

Within CRiSPEdit™ documentation it is stated that the results are undefined due to the tables maintained for each are separate which can result in the macro being mistakenly loaded more then once. As such the side-effect of the reload shall be any global state the macro was maintained shall be lost.

Under GRIEF their usage may be mixed yet for compatibility this style of usage should be avoided.

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

reregister_macro

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

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

type	Event type against which to register.
name	Name of the macro to be registered.
local	Optional int, Whether the trigger is of local or global scope. Note currently local is only effective on REG_TYPED.

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.

restore_position

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;

0	Nothing, with the save information being discarded.
1	The cursor position is restored.
2	The buffer is restored, with the cursor located in the current window at its previous position.
3	Reserved.
4	The previous buffer and window are restored, with the cursor located at its previous position.

Parameters

what	Optional integer states the what elements of the position state to be restored.

Returns

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

Portability

n/a

return

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

expression

Optional value to be returned, which should match the return type of the associated macro.

Returns

nothing

returns

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.

Note:

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

Note:

This primitive is not strictly compatible with the returns macro of BRIEF and is not generally recommended as statements following may have side effects.

Parameters

expression

Value to be returned, which should match the return type of the associated macro.

Returns

nothing

right

int right( [int columns = 1],
[int wrap = TRUE] )

Move position right one character.

Description

The right() primitive moves the cursor right one column retaining the current line.

Parameters

columns	Optional number of columns to move the cursor; negative in which case the cursor movement is reversed behaving like left.
wrap	Optional boolean value controlling whether the cursor wraps when positioned at the beginning of line. If FALSE line wrapping shall be disabled, see left.

Returns

The right() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

Unlike BRIEF, if the cursor is moved past the beginning of the current line, then the cursor wraps around to the end of the previous line.

wrap is a GriefEdit extension.

rindex

int rindex( string str,
int ch|string s )

Search string for a rightmost sub-string or character.

Description

The rindex() primitive returns the offset to the last (in otherwords the right) occurrence of the character ch or the string s in the string str.

Parameters

str	String object to be searched.
ch\|s	Object to be matched against.

Returns

The rindex() primitives returns the starting offset or 0 if the character or string was not found.

Portability

The character needle form is a GriefEdit extension.

rmdir

int rmdir( string path )

Remove directory.

Description

The rmdir() primitive removes (deletes) the specified directory. The directory must not contain any files or directories. The path can be either relative to the current working directory or it can be an absolute path name.

Returns

The rmdir() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

rtrim

string rtrim( string str,
string chars = \\t \\r \\n )

Chomp characters from the end of a string.

Description

The rtrim() primitive removes trailing (or right) characters from the specified string.

The default is to remove all tabs, spaces and newline characters. If chars is specified, then all characters within the trimchar string are removed from the end of the string.

Returns

Returns a copy of string with all trailing white space characters removed. (spaces, tabs and newlines by default).

Portability

A GriefEdit extension; this is a replacement of the original trim() function.

save_keystroke_macro

int save_keystroke_macro( string filename )

Save the current keystroke macro.

Description

The save_keystroke_macro() primitive saves the current remembered keystrokes macro to the specified file filename.

Parameters

filename

String containing the name of the destination file to which the keystroke macro is to be saved. If no file extension is stated, the extension .km shall be used.

Returns

The save_keystroke_macro() primitive returns greater than zero on success, otherwise -1 on error.

save_position

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.

Note:

That the position stack is an independent of any buffer permitting restore_position to be called to pop off the top entry of the stack even when the current buffer is not the same as buffer referenced by the top of the saved position stack.

Parameters

none

Returns

nothing

Portability

n/a

screen_dump

int screen_dump( string filename )

Dump an image of the screen.

Description

The screen_dump() primitive dumps a text representation of the current screen image to the specified file. The resulting image omits both attribute and character-map associations with the view, with frame characters mapped to their ASCII equivalent.

Parameters

filename

Optional string containing the full path of the output filename, if omitted the path /tmp/griefscreen.### shall be used; where ### represents the next available sequential filename.

Returns

Returns 0 on success, otherwise -1 on error. When an error has occurred, errno contains a value indicating the type of error that has been detected.

Portability

n/a

search_back

int search_back( string pattern,
[int re],
[int case],
[int block],
[int length] )

Backwards buffer search.

Description

The search_back() primitive searches backwards within the active buffer from the current cursor position to the buffer top (or block) against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and case folding based on case.

Note:

The search_back primitive is provided primary for BRIEF compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.

Parameters

pattern	A string containing the pattern to be matched.
re	Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information.
case	Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced.
block	Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region.
length	Optional inter flag. If length is specified and is non-zero, indicates that the total length of the text should be returned; regardless of any \\c anchors in the pattern.

Returns

The search_back() primitive returns the length of the matched text plus one otherwise zero or less if no match was found.

Alternatively, if length is specified the total length of the matched text is returned. Otherwise if a \\c anchor was encountered within the pattern, it returns the length of the text from the position of the marker to the end of the matched text plus one.

Portability

n/a

search_case

int search_case( [int case] )

Set the search pattern case mode.

Description

The search_case() primitive sets or toggles the global search case mode, if omitted the current mode is toggled.

On completion the resulting mode is echo on the command prompt, either as

Case sensitivity on

Case sensitivity off

By default all searches are case sensitive, that is A and a are not equivalent, by setting the case mode to a zero value, case sensitivity will be ignored when performing matches.

search_case affects the default case sensitivity of the follow primitives.

search_string
search_list
search_fwd and search_back
translate

Parameters

case	Optional integer value, specifying the new state of the case mode. If case is omitted, the current value is toggled.

Returns

The search_case() primitive returns the previous value of the case mode.

Portability

n/a

search_fwd

int search_fwd( string pattern,
[int re],
[int case],
[int block],
[int length] )

Buffer search.

Description

The search_fwd() primitive searches forward within the active buffer from the current cursor position to the buffer end (or block) against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and case folding based on case.

Note:

The search_fwd primitive is provided primary for BRIEF compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.

Parameters

pattern	A string containing the pattern to be matched.
re	Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information.
case	Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced.
block	Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region.
length	Optional inter flag. If length is specified and is non-zero, indicates that the total length of the text should be returned; regardless of any \\c anchors in the pattern.

Returns

The search_fwd() primitive returns the length of the matched text plus one otherwise zero or less if no match was found.

Portability

n/a

search_list

int search_list( [int start],
string pattern,
list expr,
[int re],
[int case] )

Search list contents.

Description

The search_list() primitive searches the list expr against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and case folding based on case.

Note:

The search_string primitive is provided primary for Crisp compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.

Parameters

start	Optional integer index, states the element offset at which search operation shall start. If omitted, the search is started from the beginning of the list.
pattern	A string containing the pattern to be matched.
expr	A list expression containing the list to be search for the specified pattern.
re	Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information.
case	Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced.

Returns

The search_list() primitive returns the index of the matched element, otherwise -1 if no match.

Portability

n/a

search_string

int search_string( string pattern,
string text,
[int &length],
[int re],
[int case] )

Searches for a pattern in a string.

Description

The search_string() primitive searches the string text against the expression pattern. The treatment of the matched pattern may either be a regular-expression or constant string dependent on re and with case folding based on case.

Note:

The search_string primitive is provided primary for BRIEF compatibility. Since re and case can reference the current global search states, inconsistent and/or unexpected results may result between usage; as such it is advised that the state-less re_search primitive is used by new macros.

Parameters

pattern	A string containing the pattern to be matched.
text	A string containing the text to be search for the specified pattern.
length	Optional integer variable reference. If ths search is successful and specified is populated with the length of the matched text.
re	Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information.
case	Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced.

Returns

The search_string() primitive returns the starting character in string where the match was found, or zero if the match failed.

Alternatively, if a \\c anchor was encountered within the pattern, it returns the length of the text from the position of the marker to the end of the matched text plus one.

Portability

n/a

searchpath

int searchpath( [string path],
string filename,
[string extension],
string & result,
[int mode],
[int expand = FALSE] )

Searches for a given file in a specified path.

Description

The searchpath() primitives searches the directory path path for a instance of the file name file. path is a list of delimiter separated directory names, with the same syntax as the shell variable GRPATH.

Parameters

path	Optional string containing the path to be searched for the file. If omitted the system PATH specification shall be referenced.
filename	String containing the name of the file for which to search.
extension	Optional string containing the file extension to be added to the file name when searching for the file. The first character of the file name extension must be a period (.). The extension is added only if the specified file name does not end with an extension. If a file name extension is not required or if the file name contains an extension, this parameter can be NULL.
result	String variable reference to be populated with the first instance of the file resolved along the given search path.

Returns

The expandsearch() primitive returns the length of the string that is copied to the buffer result; otherwise on failure returns a value of zero.

Portability

A GriefEdit extension.

self_insert

void self_insert( [int character] )

Insert a character as if it was typed.

Description

The self_insert() primitive insert a character into the current buffer. If character is specified, then the character whose ASCII value is character is inserted into the current buffer instead of the last character typed.

The majority of characters are directly inserted yet the following infer special processing.

tab	Cursor is moved the next tab stop, and space backfilled if at the end of the line.
newlines	Cursor is repositioned on the next line.

This primitive is normally used in conjunction with assign_to_key to unassign an ASCII key by making it a normal, typeable character.

Parameters

character

Optional integer character code to be inserted. If omitted, the value of the last key typed is inserted into the buffer.

Returns

nothing

Portability

n/a

send_signal

int send_signal( int signal )

Send signal to a process buffer.

Description

The send_signal() primitive send a signal to a process or a group of processes attached to the current buffer. The signal to be sent is specified by signo and is either one from the list given in Signals or 0.

If signo is 0 or omitted, then the null signal is sent, error checking is performed but no signal is actually sent.

See the unix kill system function is more details.

Parameters

signo

Optional integer signal number, if omitted defaults to the null signal.

Returns

The send_signal() primitive upon successful completion returns 0 and 1 when no buffer is attached. Otherwise -1 shall be returned and errno set to indicate the error.

Portability

n/a

set_attribute

int set_attribute( [int|string text],
[int|string normal],
[int bufnum] )

Set the color attributes.

Description

The set_attribute() primitive set the text and/or normal attributes for the specified buffer bufnum.

Parameters

text	Optional text attribute either by value or name.
normal	Optional clear/normal attribute either by value or name.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The set_attribute() primitive returns the previous text attribute, otherwise -1 on error.

Portability

A GriefEdit extension.

set_backup

int set_backup( int mode,
[int bufnum] )

Set backup creation mode.

Description

The set_backup() primitive either toggles, set or retrieves the current backup flag of the associated object. If bufnum is specified, then the stated buffer is effected, otherwise upon being omitted the global (default) backup mode shall be effected.

The backup flag is tested each time a buffer is written to its underlying storage (See: write_buffer). The flag maybe one of two states, either off or on; when on, then a backup files shall be created.

If mode is not specified, then the value of the associated backup flag is toggled from on to off or off to no. If given as zero backups shall be disabled, with a positive non-zero value enabling backups.

The set_backup() primitive may also be used to inquire the value of the associated backup flag. If the specified mode is -1 then the current flag value of the associated object shall be returned without any other effects.

When invoked from the command, one of the following messages shall be echoed

   "Backups will be created".
or "Backups will not be created."

   "Backups will be created for the buffer".
or "Backups will not be created for the buffer."

Returns

The set_backup() primitive returns the previous value of the backup flag.

Portability

n/a

set_backup_option

int set_backup_option( int what,
[int bufnum],
parameter )

Set backup options.

Description

The set_backup_option() primitive sets the value of the backup option what for the associated object. backup mode. If bufnum is specified, then the value of the stated buffer is modified, otherwise upon being omitted the global (default) backup mode shall be modified.

parameter shall be what specific, with the following options available;

BK_MODE - Backup creation mode, see set_backup and inq_backup. A zero integer parameter shall disable backups, with a non-zero value enabling backups.
BK_AUTOSAVE - Buffer autosave flag. A zero integer parameter shall disable auto-backups, with a non-zero value enabling auto-backups.
BK_DIR - Backup directory. parameter should a string containing the backup directory path.
BK_DIRMODE - Directory creation mode. parameter should be a integer value specifying the file creation umask.
BK_VERSIONS - Number of versions to be maintained. parameter should be an integer value specifying the number of backup versions to be kept in the range [1 .. 99]; values outside shall set the versions to the lower/upper bounds.
BK_PREFIX - Backup filename prefix. parameter should be a string containing the prefix, an empty string shall clear the current suffix.
BK_SUFFIX - Backup filename suffix/extension. parameter should be a string containing the suffix, an empty string shall clear the current prefix.
BK_ONESUFFIX - Whether only a single suffix to used replacing any existing, otherwise append the suffix shall be appended. parameter should be integer, with a non-zero enabling or zero disabling one-suffix filtering on backup filenames.
BK_ASK - Filesize watermark at which point backups shall be prompted before created a backup image. parameter should be a positive integer value being the watermark filesize in bytes, with a value of zero disabling any prompts.
BK_DONT - Filesize watermark at which point backups shall not be created regardless of the current backup mode. parameter should be a positive integer value being the watermark filesize in bytes, with a value of zero disabling any affected.

Returns

The set_backup_option() on success returns zero, otherwise -1 on error.

Portability

A GriefEdit extension.

set_binary_size

int set_binary_size( [int size] )

Set binary chunk size.

Description

The set_binary_size() primitive sets the chunk or block size utilised when loading binary file images. Each chunk shall be represented within the buffer as a single line.

Note:! If the specified value is equal or less-then zero (<= 0), then files shall never be interpreted as binary when read; instead the default system specific type as be applied.

Parameters

size	Optional integer number, if omitted the current size is not changed.

Returns

The set_binary_size() primitive returns the previous chunk size.

Portability

n/a

set_btn2_action

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

action

Optional integer, the new Quick-Menu button action.

Returns

Returns the previous action button status.

Portability

n/a

set_buffer

int set_buffer( int bufnum )

Set the current buffer.

Description

The set_buffer() primitive makes the buffer identifier specified by bufnum the current buffer, without effecting the current window. The current is the one referenced by all buffer operations which are not given an explicit buffer identifier.

Generally set_buffer is utilised in one of two ways;

Temporarily changing the buffer so to perform specific buffer processing, for example searching for text, and on completion the previous is then restored to the current.
Changing the active buffer, which should also involve changing the current window using set_window or associating the new buffer with the current window using attach_buffer.

The set_buffer() primitive unlike edit_file does not cause any registered macros to be executed.

Warning:

The referenced buffer does not always need to be attached to a window nor the one currently associated with the current window set_window, yet upon macro exit the current buffer and current window should be attached otherwise the side-effects may be disastrous.

Parameters

bufnum

Buffer identifier to be selected.

Returns

The set_buffer() primitive returns the identifier of the previous current buffer otherwise -1 if an invalid buffer identifier was stated.

On failure the following diagnostics message shall be echoed on the command prompt.

'set_buffer': no such buffer

Portability

n/a

set_buffer_cmap

int set_buffer_cmap( [int mapid|string name],
[int bufnum] )

Set a buffers character-map.

Description

The set_buffer_cmap() primitive attachs the specified character-map to a given buffer. A single character-map can be attached to any number of buffers.

Note that this association shall have precedence over the windows view of a buffer set_window_cmap.

Parameters

mapid, name	Character-map reference, being either an integer map identifier or the associated map name as a string. If omitted the default character-map shall be attached.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The set_buffer_cmap() primitive returns the identifier of the resolved character-map otherwise -1 if the specified character map does not exist.

Portability

n/a

set_buffer_flags

void set_buffer_flags( [int bufnum],
[string|int or_mask],
[string|int and_mask],
[int set = 1] )

Set buffer flags.

Description

The set_buffer_flags() primitive modifies the internal flags associated with the specified buffer, see Buffer Flags.

If specified one or more flags shall be cleared using the and_mask, in additional one or more flags are set using the or_mask.

Each buffer maintains several sets of integer flags which can be modified. Against the selected flag set the optional and_mask (clear) and then the optional or_mask (set) is applied.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
set_mask	Optional mask of flags to set. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.
clear_mask	Optional mask of flags to clear. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.
set	Optional integer stating the flag set to be modified, if omitted defaults to the primary set(1).

Returns

nothing

Portability

The string mask variants and set parameter are GRIEF extension.

Many of the flags are GRIEF specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.

set_buffer_title

int set_buffer_title( [int bufnum],
[string title] )

Set a buffers title.

Description

The set_buffer_title() primitive sets the buffer title of the stated buffer otherwise the current buffer when omitted. The specified title is displayed on the top edge of the buffers associated window.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
title	Optional string value of the title to associated. If omitted specified, then the buffer title is remove with the buffers underlying filename being used.

Returns

The set_buffer_title() primitives return zero on success, otherwise -1 if the specified buffer does not exist.

Portability

n/a

set_buffer_type

int set_buffer_type( [int bufnum],
[int type = NULL],
[string encoding = NULL] )

Set the buffer storage type.

Description

The set_buffer_type() primitive optionally set the buffer type and/or the character encoding associated with the specified buffer.

Note that the specified encoding has priority over the buffer type, in that an incompatible encoding with the stated type or pre-existing buffer type shall imply the default buffer type associated with the encoding. The inq_buffer_type() primitive should be used to determine the resulting buffer type on completion.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
type	Optional integer buffer type which states the basic buffer encoding include an implied line termination.
encoding	Optional string which sets the specific buffer encoding beyond the buffer type, for example the page code utilized by a BFTYPE_DOS buffer.

Buffer Types

The following manifest constants define the available Buffer Types.

Constant	Description
BFTYP_UNKNOWN	Unknown buffer type.
BFTYP_UNIX	Unix, LF line termination.
BFTYP_DOS	DOS, CF/LF line termination.
BFTYP_MAC	Old style MAX, CR termination.
BFTYP_BINARY	Binary.
BFTYP_ANSI	ANSI.
BFTYP_EBCDIC	EBCDIC.
BFTYP_UTF8	UTF8.
BFTYP_UTF16	UTF16/USC2.
BFTYP_UTF32	UTF32/USC4.
BFTYP_UTFEBCDIC	UTF8/EBCDIC.
BFTYP_BOCU1	Binary Ordered Compression for Unicode.
BFTYP_SCSU	Standard Compression Scheme for Unicode.
BFTYP_UTF7	7-bit Unicode Transformation Format.
BFTYP_GB	GB.
BFTYP_BIG5	BIG5.
BFTYP_ISO2022	ISO-2022.
BFTYP_SBCS	Single Byte.
BFTYP_DBCS	Double Byte.
BFTYP_MBCS	Multi-Byte (Non Unicode).
BFTYP_OTHER	Other supported.
BFTYP_UNSUPPORTED	Known file-type, yet no internal support.

Returns

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

Portability

A GriefEdit extension.

set_calling_name

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

set_char_timeout

void set_char_timeout( [int timeout] )

Set the escape delay.

Description

The set_char_timeout() primitive sets the length of time to wait before timing out and treating the ESC keystroke as the ESC character rather than combining it with other characters in the buffer to create a key sequence.

The most common instance where you may wish to change this value is to work with slow hosts, e.g., running on a network. If the host cannot read characters rapidly enough, it will have the same effect as if the terminal did not send characters rapidly enough. The library will still see a timeout.

The escape-delay value defaults to 750 milliseconds, but this shall be overridden by the ESCDELAY environment variable or the --escdelay command line option.

The ESCDELAY environment is defined specifies the default timeout interval, which is generally measured in millisecond. If ESCDELAY is 0, the system immediately composes the ESCAPE response without waiting for more information from the buffer. The user may choose any value between 0 and 9999, inclusive.

Note:

The ESCDELAY value is generally measured in milliseconds under most unix environments, but under AIX this value is measured in fifths of a milliseconds (200 microseconds) to be compatible with libcursor implementations; the default value is 500, or 0.1 second

Parameters

timeout

Optional character timeout is milliseconds, otherwise the current ESCDELAY shall be reapplied.

Returns

The set_char_timeout() primitive returns the previous character timeout.

Portability

n/a

set_color

int set_color( [list|string spec],
[int create = TRUE] )

Set screen colors.

Description

The set_color() primitive controls the colors that are utilised on a color display; the values are ignored for monochrome displays.

It is designed to compliment and enhance the functionality of the color primitive, with color() being a user level interface and set_color() being a script level interface.

Parameters

spec	Color specification, either a list or comma separated set of attributes. The specification may use one of two forms, firstly an explicit set of attributes pairs or secondary as an implicit list of colors, see below.
create	Optional boolean flag, if either omitted or true non-existent attributes shall be created.

Color Specification

The specification may take one of the following forms. For details on available attributes and possible colors, see the Color Attributes and Color Name sections below.

Explicit:

A list of strings containing attribute color pairs Simple attributes are assigned a color delimited by a = take the form:

"attribute=color"

For the highlight and syntax attributes an extended form permits explicit selection of the background over the implied default of background in additional to optional style settings, as follows:

"attr=color[:style][,background]"

Implicit:

An ordered list of strings corresponding to each color attribute to be set, using the form:

"color-name color-name ..."

A value of NULL in the list means to skip the assignment of the related attribute. An integer value within the list allows the index reference to be explicitly set for subsequent attribute assignment.

Note, provided primary for CRisP compatibility as the explicit interface is the recommended use of the set_color primitive to guard against future enhancements/color attributes.

Also note as the color interfaces have developed independently the COL enumeration values differ.

Scheme Specification

A special attribute scheme sets the default color scheme, taking the form:

scheme=d[ark]|l[ight]

Color Names

The following color names are recognised which are case-insensitive, with the color number used which are available on most systems. The first name listed shall be the primary name as returned from inquiry functions ((see get_color )) with the additional as aliases.

Color	Constant	Aliases
Black	BLACK
Blue	BLUE
green	GREEN
Cyan	CYAN
Red	RED
Magenta	MAGENTA
Brown	BROWN
White	WHITE
Grey	GREY	Gray
Light-blue	LTBLUE	LightBlue
Light-green	LTGREEN	LightGreen
Light-cyan	LTCYAN	LightCyan
Light-red	LTRED	LightRed
Light-magenta	LTMAGENTA	LightMagenta
Yellow	YELLOW
Light-white	LTWHITE	LightWhite
Bright-white	LTWHITE
Light-grey	LTWHITE	LightGrey
Light-gray	LTWHITE	LightGray
Dark-grey	DKGREY	DarkGrey
Dark-gray	DKGREY	DarkGray
Dark-blue	DKBLUE	DarkBlue
Dark-green	DKGREEN	DarkGreen
Dark-cyan	DKCYAN	Darkcyan
Dark-red	DKRED	DarkRed
Dark-magenta	DKMAGENTA	DarkMagenta
Dark-yellow	DKYELLOW	DarkYellow
Light-yellow	LTYELLOW	LightYellow

plus the following specials to support black-white and terminal features:

Color	Description
Normal	Normal terminal text.
Inverse	Inverse contrast.
Blink	Blinking text.
Reverse	Reverse contrast.
Standout	Stand-out terminal text.
Dim	Dim colors.

Color Codes

Under environments which support a larger color range, examples include xterm256 and WIN32+, the following additional system colors are available. Either by its color values (e.g. 0x32) or by its Red, Green and Blue (RGB) value.

The format is “#rrggbb” being hexadecimal value in range 00-ff, where:

rr	is the Red value.
gg	is the Green value.
bb	is the Blue value.

Color Attributes

There are a number of display attributes which can be assigned specific colors. These attributes represent a number of different display objects from basis editing, syntax hiliting and dialog.

The table below lists all the attributes, their manifest-constant within the set_color and get_color interface and description:

Name	Constant	Description
background	COL_BACKGROUND	Background color.
normal	COL_NORMAL_FG	Normal text.
select	COL_SELECT_FG	Title of selected window.
message	COL_MESSAGE_FG	Prompt, messages and status fields.
error	COL_ERROR_FG	Error messages.
hilite	COL_HILITE_BG	Highlighted/marked background.
hilite	COL_HILITE_FG	Highlighted foreground.
frame	COL_BORDERS	Window frame/borders.
cursor_insert	COL_INSERT_CURSOR	Insert mode cursor.
cursor_overtype	COL_OVERTYPE_CURSOR	Over-type mode cursor.
cursor	n/a
cursor_row	n/a
cursor_col	n/a
shadow	COL_SHADOW
prompt	COL_PROMPT
prompt_standout	n/a
prompt_complete	COL_COMPLETION
question	COL_QUESTION
echo_line	COL_ECHOLINE
standout	COL_STANDOUT
literalchar	n/a
whitespace	n/a	Highlighted white-space/tabs.
scrollbar	n/a
scrollbar_thumb	n/a
column_status	n/a
column_lineno	n/a	Line numbers.
nonbuffer	n/a
search	n/a
search_inc	n/a
search_match	n/a
ruler	n/a
ruler_margin	n/a
ruler_ident	n/a
ruler_mark	n/a
ruler_column	n/a
popup_normal	n/a
popup_hilite	n/a
popup_standout	n/a
popup_title	n/a
popop_frame	n/a
dialog_normal	n/a
dialog_focus	n/a
dialog_hilite	n/a
dialog_greyed	n/a
dialog_hotkey_normal	n/a
dialog_hotkey_focus	n/a
dialog_frame	n/a
dialog_title	n/a
dialog_scrollbar	n/a
dialog_thumb	n/a
dialog_but_greyed	n/a
dialog_but_normal	n/a
dialog_but_focus	n/a
dialog_but_key_normal	n/a
dialog_but_key_focus	n/a
dialog_edit_greyed	n/a
dialog_edit_normal	n/a
dialog_edit_focus	n/a
dialog_edit_complete	n/a
lsdirectory	n/a
lsexecute	n/a
lssymlink	n/a
lspipe	n/a
lsspecial	n/a
lserror	n/a
lsreadonly	n/a
lsnormal	n/a
lsattribute	n/a
lssize	n/a
modified	n/a
additional	n/a
difftext	n/a
diffdelete	n/a
match	n/a
link	n/a
tag	n/a
alert	n/a
ansi_bold	n/a
ansi_underline	n/a
spell	n/a
spell_local	n/a
spell_special	n/a
comment	n/a	Language comments.
comment_standout	n/a
todo	n/a
code	n/a
constant	n/a
constant_standout	n/a
string	n/a	Language string elements.
character	n/a
operator	n/a	Language operator elements.
number	n/a	Language numeric values.
float	n/a
delimiter	n/a	Language delimiter elements.
word	n/a
boolean	n/a
preprocessor	n/a	Language preprocesor elements.
preprocessor_define	n/a
preprocessor_include	n/a
preprocessor_conditional	n/a
preprocessor_keyword	n/a
preprocessor_word	n/a
keyword	n/a	Language keywords, primary.
keyword_function	n/a
keyword_extension	n/a
keyword_type	n/a
keyword_storageclass	n/a
keyword_definition	n/a
keyword_conditional	n/a
keyword_repeat	n/a
keyword_exception	n/a
keyword_debug	n/a
keyword_label	n/a
keyword_structure	n/a
keyword_typedef	n/a
user1	n/a	User specified 1
user2	n/a	User specified 2
user3	n/a	User specified 3
user4	n/a	User specified 4
user5	n/a	User specified 5
user6	n/a	User specified 6
user7	n/a	User specified 7
user8	n/a	User specified 8
user9	n/a	User specified 9
user10	n/a	User specified 10
window1	n/a
window2	n/a
window3	n/a
window4	n/a
window5	n/a
window6	n/a
window7	n/a
window8	n/a
window9	n/a
window10	n/a
window11	n/a
window12	n/a
window13	n/a
window14	n/a
window15	n/a
window16	n/a

Styles

The following styles are recognised which are case-insensitive.

Featuree	Description
Underline	Underlined text.
Italic	Italic typeface.
Bold	Bold typeface.
Italic	Italic typeface.
Underline	Under lined text.
Undercurl	Curly underline, generally underline.

Returns

The set_color() primitive returns 0 on success, otherwise -1 -1 on failure to set colors.

Portability

A GriefEdit extension.

set_color_pair

void set_color_pair( string|int ident,
[int|string fg],
[int|string bg],
[int|string sf] )

Set a specific color.

Description

The set_color_pair() primitive sets the pair of foreground and background colors associated with the color attribute indent.

The specified attribute shall be assigned the given foreground color fg, with an optional background bg and style sf. If the foreground is omitted the user shall be prompted.

Parameters

ident	Attribute identifier either using its their manifest integer constants or string aliases, with names being case-insensitive; see set_color for details.
fg	Optional foreground color. If omitted, then the foreground and (if required) background are prompted.
bg	Optional background color.
sf	Optional style and flags.

Returns

nothing

Portability

A GriefEdit extension.

set_ctrl_state

void set_ctrl_state( int ctrl,
int state,
[int winnum] )

Set the state of a window control.

Description

The set_ctrl_state() primitive sets the state of a window control of the specific window, if omitted the current window.

Parameters

ctrl	Control identifier.

WCTRLO_CLOSE_BTN	Close button.
WCTRLO_ZOOM_BTN	Zoom button.
WCTRLO_VERT_SCROLL	Vertical scroll.
WCTRLO_HORZ_SCROLL	Horizontal scroll.
WCTRLO_VERT_THUMB	Vertical thumb.
WCTRLO_HORZ_THUMB	Horizontal thumb.

stateAn integer specifying the desired state.

WCTRLS_ENABLE	Enable the control all windows.
WCTRLS_DISABLE	Disable the control all windows.
WCTRLS_HIDE	Used to temporarily hide object for either the specified window or all windows, if window is omitted.
WCTRLS_SHOW	Restore the show status of a hidden control. HIDE/SHOW calls nests, hence for a hidden object to be displayed the number of HIDE operations must be matched by the same number of SHOW operations.
WCTRLS_ZOOMED	Display the zoomed button.

winnumOptional window identifier, if omitted the current window shall be referenced.

Returns

nothing

Portability

n/a

set_echo_format

void set_echo_format( [string format = NULL] )

Set the echo line format.

Description

The set_echo_format() primitive sets or clears the current status area format specification. The format shall be applied to the echo-line overriding the fixed layout implied by echo_line

The following example specification

"grief %v: %b (%m) %l %c %t"

results in

grief v2.6.1: (-rw-rw-rw-rw) Line: 165 Col: 1 3:14pm

The echo-line format is applied when the E_FORMAT flag is enabled (See: echo_line). Setting an echo line format implies E_FORMAT similarly clearing the format disables E_FORMAT.

Note:

When errors are encountered while evaluating the format specification the incorrect section shall be simply echoed within the echo-line; otherwise screen updating would loop.

Parameters

format

Optional echo line format specified, if omitted the format is cleared the current echo_line shall take effect.

Format Specification

A format specification, which consists of optional and required fields, has the following form:

%[flags][modifier]<type>

Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %b). If a percent sign is followed by a character that has no meaning as a format field, the character is simply copied. For example, to print a percent-sign character, use %%.

The optional fields, which appear before the type character, control other aspects of the formatting, as follows:

type	Required character that determines whether the associated argument is interpreted as a character, a string, or a number.
flags	Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.
modifier	Optional number that specifies a format modifier, selected an alternative form of the associated type. If omitted the modifier assumes a value of 0.

Following is a description of the possible echo-line attributes. The second character in “item” is the type:

Type

Description

Buffer details.

Modifier	Value
0	Buffer title.
1	Buffer number as decimal.
2	Buffer number as hex.

Buffer flags.

Modifier	Value
0	Flags0
1	Flags1
2	Flags2
3	Flags3
4	Flags4

File name with directory.

File name without the directory.

Percent string.

Column number.

Modifier	Value
0	Col: xxx
1	xxx

Mode string (i.e. --rw-rw-rw).

Overwrite mode, “ OV” otherwise “”.

Overwrite/insert flag, like %o yet shows OV/RE.

Character value.

Virtual character indicator.

Remember flag.

Line number.

Modifier	Value
0	Line: xxx
1	xxx

Number of lines in the file.

Current time.

Modifier	Value
0	12 hour
1	24 hour

Current date.

Modifier	Value
0	yyyy-mm[m]-dd
1	yy-mm[m]-dd
2	dd-mm[m]-yyyy
3	mm[m]-dd-yyyy
4	dd-mm[m]-yy
5	mm[m]-dd-yy
6	dd-mm[m]
7	mm-dd

GRIEF Version.

Current Year.

Modifier	Value
0	YYYY
1	YY

Current month of the year.

Modifier	Value
0	MM
1	M[M]
2	Name
3	Abbrev

Current day of the month.

Modifier	Value
0	DD
1	D[D]
2	Name
3	Abbrev

The following flags are supported;

Flag	Description	Default
-	Left align the result within the given field width.	Right align.
+	Prefix the output value with a sign (+ or -) if the output value is of a signed type.	Sign appears only for negative signed values ().
0	If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored.	No padding.
<space>	Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.	No blank appears.

Parameters

format

Echo line format specification, if omitted or an empty string the specification is cleared.

Returns

nothing

Portability

A GriefEdit extension.

set_encoding

int set_encoding( [string encoding = NULL],
[int bufnum = NULL] )

Set a buffers character encoding.

Description

The set_encoding() primitive sets or clears the character encoding associated with the referenced buffer.

The following table lists the character encodes which maybe available dependent on build options and system support.

Name	Buffer Type	Code Page	Description
US-ASCII	BFTYP_SBCS	646	ANSI/ASCII
ISO-8859-1	BFTYP_SBCS	28591	Western Europe
ISO-8859-2	BFTYP_SBCS	28592	Western and Central Europe
ISO-8859-3	BFTYP_SBCS	28593	Western Europe and South European (Turkish, Maltese plus Esperanto)
ISO-8859-4	BFTYP_SBCS	28594	Western Europe and Baltic countries (Lithuania, Estonia and Lapp)
ISO-8859-5	BFTYP_SBCS	28595	Cyrillic alphabet
ISO-8859-6	BFTYP_SBCS	28596	Arabic
ISO-8859-7	BFTYP_SBCS	28597	Greek
ISO-8859-8	BFTYP_SBCS	28598	Hebrew
ISO-8859-9	BFTYP_SBCS	28599	Western Europe with amended Turkish character set
ISO-8859-10	BFTYP_SBCS		Western Europe with rationalised character set for Nordic languages
ISO-8859-13	BFTYP_SBCS	28603	Baltic languages plus Polish
ISO-8859-14	BFTYP_SBCS		Celtic languages (Irish Gaelic, Scottish, Welsh
ISO-8859-15	BFTYP_SBCS	28605	Euro sign and other rationalisations to ISO 8859-1
ISO-8859-16	BFTYP_SBCS		Central, Eastern and Southern European languages
CP037	BFTYP_EBCDIC	37	EBCDIC-US
CP038	BFTYP_EBCDIC	38	EBCDIC-INT
CP930	BFTYP_EBCDIC	930
CP1047	BFTYP_EBCDIC	1047
UTF-8	BFTYP_UTF8	65001
UTF-16	BFTYP_UTF16
UTF-16be	BFTYP_UTF16	1201
UTF-16le	BFTYP_UTF16	1200
UTF-32	BFTYP_UTF32
UTF-32be	BFTYP_UTF32
UTF-32le	BFTYP_UTF32
BOCU-1	BFTYP_BOCU1
SCSU	BFTYP_SCSU
UTF-7	BFTYP_UTF7	65002
UTF-2	BFTYP_UCS2		BFTYP_UTF16 aliases
UTF-2be	BFTYP_UCS2
UTF-2le	BFTYP_UCS2
UTF-4	BFTYP_UCS4		BFTYP_UTF32 aliases
UTF-4be	BFTYP_UCS4
UTF-4le	BFTYP_UCS4
cp437	BFTYP_SBCS	437	OEM/US, ASCII
cp737	BFTYP_SBCS	737	Greek, ISO-8859-7
cp775	BFTYP_SBCS	775	Baltic
cp850	BFTYP_SBCS	850	Like ISO-8859-4
cp852	BFTYP_SBCS	852	Like ISO-8859-1
cp855	BFTYP_SBCS	855	Like ISO-8859-2
cp857	BFTYP_SBCS	857	Like ISO-8859-5
cp860	BFTYP_SBCS	860	Like ISO-8859-9
cp861	BFTYP_SBCS	861	Like ISO-8859-1
cp862	BFTYP_SBCS	862	Like ISO-8859-1
cp863	BFTYP_SBCS	863	Like ISO-8859-8
cp865	BFTYP_SBCS	865	Like ISO-8859-1
cp866	BFTYP_SBCS	866	Like ISO-8859-5
cp869	BFTYP_SBCS	869	Greek, like ISO-8859-7
cp874	BFTYP_SBCS	874	Thai
cp1046	BFTYP_SBCS	1046	Arabic DOS code
windows-1250	BFTYP_SBCS	1250	Central European languages that use Latin script (Polish, Czech etc).
windows-1251	BFTYP_SBCS	1251	Cyrillic alphabets
windows-1252	BFTYP_SBCS	1252	Western languages
windows-1253	BFTYP_SBCS	1253	Greek
windows-1254	BFTYP_SBCS	1254	Turkish
windows-1255	BFTYP_SBCS	1255	Hebrew
windows-1256	BFTYP_SBCS	1256	Arabic
windows-1257	BFTYP_SBCS	1257	Baltic languages
windows-1258	BFTYP_SBCS	1258	Vietnamese
Mac-Arabic	BFTYP_SBCS
Mac-Celtic	BFTYP_SBCS
Mac-Centeuro	BFTYP_SBCS
Mac-Croatian	BFTYP_SBCS
Mac-Cyrillic	BFTYP_SBCS
Mac-Devanaga	BFTYP_SBCS
Mac-Dingbats	BFTYP_SBCS
Mac-Farsi	BFTYP_SBCS
Mac-Gaelic	BFTYP_SBCS
Mac-Greek	BFTYP_SBCS
Mac-Gujarati	BFTYP_SBCS
Mac-Gurmukhi	BFTYP_SBCS
Mac-Hebrew	BFTYP_SBCS
Mac-Iceland	BFTYP_SBCS
Mac-Inuit	BFTYP_SBCS
Mac-Roman	BFTYP_SBCS
Mac-Romanian	BFTYP_SBCS
Mac-Thai	BFTYP_SBCS
Mac-Turkish	BFTYP_SBCS
cp10000	BFTYP_SBCS	10000	MacRoman
cp10006	BFTYP_SBCS	10006	MacGreek
cp10007	BFTYP_SBCS	10007	MacCyrillic
cp10029	BFTYP_SBCS	10029	MacLatin2
cp10079	BFTYP_SBCS	10079	MacIcelandic
cp10081	BFTYP_SBCS	10081	MacTurkish
KOI8-R	BFTYP_SBCS	20866	Russian, using cynrillic alphabet.
KOI8-U	BFTYP_SBCS	21866	Ukrainian, using cynrillic alphabet.
KOI8-T	BFTYP_SBCS		Ukrainian
PT154	BFTYP_SBCS		Ukrainian
KOI7	BFTYP_SBCS		Ukrainian
MIK	BFTYP_SBCS	0	Bulgarian
ISCII	BFTYP_SBCS		Indian Script Code for Information Interchange.
TSCII	BFTYP_SBCS		Tamil Script Code for Information Interchange.
VSCII	BFTYP_SBCS		Vietnamese Standard Code for Information Interchange.
DEC-MCS	BFTYP_SBCS	-2
DEC-KANJI	BFTYP_SBCS	-2
DEC-HANYU	BFTYP_SBCS	-2
HP-Roman8	BFTYP_SBCS	-3
HP-Arabic8	BFTYP_SBCS	-3
HP-Greek8	BFTYP_SBCS	-3
HP-Hebrew8	BFTYP_SBCS	-3
HP-Turkish8	BFTYP_SBCS	-3
HP-Kana8	BFTYP_SBCS	-3
GB2312	BFTYP_GB		Guojia Biaozhun/Simplified Chinese.
GBK	BFTYP_GB	936	Chinese/GB (CP936).
GB18030	BFTYP_GB		Chinese National Standard/GB.
HZ	BFTYP_HZ		RFC1843, Arbitrarily Mixed Chinese and ASCII.
Big5	BFTYP_BIG5	950	Chinese/Big-5 (CP950).
Big5-5E	BFTYP_BIG5		Big-5.
Big5-2003	BFTYP_BIG5		Big-5.
Big5-HKSCS	BFTYP_BIG5		Big-5/Hong Kong Supplement.
Shift_JIS	BFTYP_MBCS		Shift JIS.
EUC-JP	BFTYP_MBCS		Japan/EUC.
CP932	BFTYP_MBCS	932	Windows-31J.
EUC-CN	BFTYP_MBCS		Chinese/EUC.
EUC-TW	BFTYP_MBCS		Tawian/EUC.
EUC-KR	BFTYP_MBCS	949	Korean/EUC (CP949).
ISO-2022-CN	BFTYP_ISO2022
ISO-2022-KK	BFTYP_ISO2022
ISO-2022-KP	BFTYP_ISO2022

Parameters

encoding	Optional encoding name, if omitted the encoding is derived from the buffer type (See: set_buffer_type).
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

nothing

Portability

A GriefEdit extension

set_feature

int set_feature( [int|string feature],
[string value] )

Config an editor feature.

Description

The set_feature() primitive sets the status of the specific feature feature.

Warning:

The set_feature() primitive is an experimental interface and may change without notice.

Parameters

feature	Name of the feature.
value	Configuration value.

Return

The set_feature() primitive returns non-zero on success, otherwise zero on error.

Macro Portability; A GriefEdit extension.

set_file_magic

int set_file_magic( [string encoding],
[int cost] )

Define the file type detection rules.

Description

The set_file_magic primitive configures the global file character encoding detection logic.

Parameters

spec	Optional file character encoding specification. If a non-empty string the detection rules shall be set to the given specification, whereas an empty string shall clear the current user specification, enabling the system default. If the specification is omitted the current rules remain unchanged.
cost	Optional integer, stating the character cost the detection logic is permitted to incur.

Detection Types

The order below is somewhat important as the MBCS checks can result in false positives, as such are generally last in line.

Name	Default	Description
mark	yes	Explicit “Encoding: <marker>” within the leading file content.
utf32bom	yes	UTF-32 BOM marker.
utf16bom	yes	UTF-16 BOM marker.
utf8	yes	UTF-8
bom	yes	Non UTF BOM markers.
udet	yes	Mozilla Universal Character Detector, see libcharudet.
magic	yes	File magic, see libmagic.
binary	yes	Possible binary image.
ascii	yes	ASCII only (7-bit).
latin1	yes	Latin-1 (ISO-8859-x) data.
big5	yes	Chinese Big5.
gb18030	yes	Chinese GB-18030.
shiftjis	yes	Shift-JIS.
xascii	yes	Extended ASCII.
charset	no	Explicit character-set.
guess	n/a	see libguess.

Without going into the full details of each search algorithms, several are summarised below.

mark

Markup languages have ways of specifying the encoding in a signature near the top of the file.

The following appears inside the <head> area of an HTML page.

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

In XML, the XML declaration specifies the encoding.

<?xml version="1.0" encoding="iso-8859-1"?>

Recognised formats are.

grief/vim	encoding:<xxx>
emacs	coding:<xxx>
html	charset=[“’]<xxx>[“’]

utf32bom, utf16bom

BOM stands for Byte Order Mark which literally is meant to distinguish between little-endian LE and big-endian BE byte order. For UTF-32 and UTF-16 the code point U+FEFF (“zero width no-break space”) are used.

UTF-32 Big Endian         0X00,0X00,0XFE,0XFF
UTF-32 Little Endian      0XFF,0XFE,0X00,0X00

UTF-16 Big Endian         0XFE,0XFF
UTF-16 Little Endian      0XFF,0XFE

uft8

UTF-8 auto-detection (when there is no UTF-8 BOM), performs UTF-8 decoding on the file looking for an invalid UTF-8 sequence; correct UTF-8 sequences look like this:

0xxxxxxx                              ASCII < 0x80 (128)
110xxxxx 10xxxxxx                     2-byte >= 0x80
1110xxxx 10xxxxxx 10xxxxxx            3-byte >= 0x400
11110xxx 10xxxxxx 10xxxxxx 10xxxxxx   4-byte >= 0x10000

bom

BOM stands for Byte Order Mark which literally is meant to distinguish between little-endian LE and big-endian BE byte order.

For Unicode files, the BOM (“Byte Order Mark” also called the signature or preamble) is a set of leading bytes at the beginning used to indicate the type of Unicode encoding.

The key to the BOM is that it is generally not included with the content of the file when the file’s text is loaded into memory, but it may be used to affect how the file is loaded into memory.

Recognised sequences include;

UTF-32 Big Endian         0X00,0X00,0XFE,0XFF
UTF-32 Little Endian      0XFF,0XFE,0X00,0X00

UTF-16 Big Endian         0XFE,0XFF
UTF-16 Little Endian      0XFF,0XFE

UTF-7                     0X2B,0X2F,0X76,0X38
UTF-7                     0X2B,0X2F,0X76,0X39
UTF-7                     0X2B,0X2F,0X76,0X2B
UTF-7                     0X2B,0X2F,0X76,0X2F

UTF-EBCDIC                0XDD,0X73,0X66,0X73
GB18030                   0X84,0X31,0X95,0X33
BOCU-1                    0XFB,0XEE,0X28,0xFF
BOCU-1                    0XFB,0XEE,0X28
SCSU                      0X0E,0XFE,0XFF
UTF-1                     0XF7,0X64,0X4C
UTF-8                     0XEF,0XBB,0XBF

udet

Mozilla Universal Character Detector employs a composite approach that utilizes Code Scheme, Character Distribution and 2-Char Sequence Distribution methods to identify language/encodings has been proven to be very effective and efficient in our environment; see libcharudet.

http://www-archive.mozilla.org- /projects- /intl- /UniversalCharsetDetection.html

big5

Performs Big5 decoding on the file looking for an invalid sequences.

Big5 does not conform to the ISO-2022 standard, but rather bears a certain similarity to Shift-JIS.

It is a double-byte character set with the following structure.

First Byte:         0xA1 - 0xf9 (non-user-defined characters)
                or  0x81 - 0xfe (extended range)
Second Byte:        0x40 - 0x7e or 0xa1 - 0xfe

gb18030

Performs GB18030 decoding on the file looking for an invalid sequences.

GB18030-2000 has the following significant properties;

It incorporates Unicode’s CJK Unified Ideographs Extension A completely.
It provides code space for all used and unused code points of Unicode’s plane 0 (BMP) and its 15 additional planes. While being a code- and character-compatible “superset” of GBK, GB18030-2000, at the same time, intends to provide space for all remaining code points of Unicode. Thus, it effectively creates a one-to-one relationship between parts of GB18030-2000 and Unicode’s complete encoding space.
In order to accomplish the Unihan incorporation and code space allocation for Unicode 3.0, GB18030-2000 defines and applies a four-byte encoding mechanism.

GB18030-2000 encodes characters in sequences of one, two, or four bytes. The following are valid byte sequences (byte values are hexadecimal):

Single-byte: 0x00-0x7f
Two-byte:    0x81-0xfe + 0x40-0x7e, 0x80-0xfe
Four-byte:   0x81-0xfe + 0x30-0x39 + 0x81-0xfe + 0x30-0x39

The single-byte portion applies the coding structure and principles of the standard GB 11383 (identical to ISO 4873:1986) by using the code points 0x00 through 0x7f.

The two-byte portion uses two eight-bit binary sequences to express a character. The code points of the first (leading) byte range from 0x81 through 0xfe. The code points of the second (trailing) byte ranges from 0x40 through 0x7e and 0x80 through 0xfe.

The four-byte portion uses the code points 0x30 through 0x39, which are vacant in GB 11383, as an additional means to extend the two-byte encodings, thus effectively increasing the number of four-byte codes to now include code points ranging from 0x81308130 through 0xfe39fe39.

GB18030-2000 has 1.6 million valid byte sequences, but there are only 1.1 million code points in Unicode, so there are about 500, 000 byte sequences in GB18030-2000 that are currently unassigned.

shiftjis

Performs Shift-JIS decoding on the file looking for an invalid sequences.

Single Byte

ASCII:                  0x21 - 0x7F (also allow control)
Katakana:               0xA1 - 0xDF

Multiple Byte

JIS X 0208 character
First byte:             0x81 - 0x9F or 0xE0 - 0xEF
Second byte (old 1st):  0x40 - 0x9E
Second byte (even 1st): 0xA0 - 0xFD

guess

libguess employs discrete-finite automata to deduce the character set of the input buffer. The advantage of this is that all character sets can be checked in parallel, and quickly. Right now, libguess passes a byte to each DFA on the same pass, meaning that the winning character set can be deduced as efficiently as possible; see libguess.

Returns

The set_file_magic() primitive returns a positive value on success, otherwise -1 on error.

Portability

A GriefEdit extension.

set_font

int set_font( [string normalfont],
[string italicfont] )

Set the current window fonts.

Description

The set_font() primitive configures the active normal and/or italic font of the current running GriefEdit image.

Note:

Only available when running under a suitable windowing system, otherwise this primitive is a no-op.

Parameters

normalfont	Optional string containing the normal text font.
italicfont	Optional italic font.

Returns

The set_font() primitive returns zero or greater on success, otherwise -1 on error.

Portability

GriefEdit extended.

set_idle_default

int set_idle_default( int internal = 0 )

Set idle interval.

Description

The set_idle_default() primitives set the keyboard idle interval as a measure of seconds betwen the last keystroke and when the REG_IDLE event is generated, see register_macro for details.

Parameters

interval

Integer idle interval in seconds, if omitted the system default shall be utilised.

Returns

The set_idle_default() primitives returns the previous value of the interval timer.

Portability

n/a

set_indent

int set_indent( [int indent],
[int bufnum] )

Set the buffers default indentation.

Description

The set_indent() primitive configures the indentation value for the specified buffer, representing the buffers default ruler. Indentation stops are set every indent stops after the last stop, with the first column within a line being column 1.

Indenting does not change the size represented by physical tabbing, it determines the buffers default indentation when a tab-character is self_inserted(), backfilling with either spaces and/or physical tabs dependent on whether or not hard=tabs are enabled (See: use_tab_char).

An indent value of 0, shall disable the buffers indentation setting defaulting to the current tab stop (See: tabs) unless a ruler is also in effect. If omitted the user shall be prompted for a new value as follows:

Enter indent amount:

Note that any user specified ruler (See: set_ruler) shall have priority over both this setting and the tabs configuration.

Parameters

indent	Optional buffer indentation, if omitted the user shall be prompted.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The set_indent() primitive returns the applied indentation value, otherwise if the user was prompted and they aborted -1 is returned.

Portability

A GriefEdit extension.

set_kbd_name

void set_kbd_name( string name,
[int kbdid] )

Set the keyboard name.

Description

The set_kbd_name() primitive assigned the label name as the name of the keyboard kbdid, allowing primitives to assign a descriptive or meaningful definition to a keyboard. These names or descriptions may then be utilised by macros.

Parameters

name	String containing the name to be assigned. If empty the current name shall be cleared.
kbdid	Optional integer keyboard identifier, if omitted the current keyboard shall be referenced.

Returns

nothing

Portability

n/a

set_line_flags

int set_line_flags( [int bufnum],
[int start],
[int end],
[int and_mask],
[int or_value] )

Associate line flags.

Description

The set_line_flags primitive allows the flags of one or more line within a specific buffer to be modified.

The buffer flags was a set of 32 bit values separated into two namespaces, with the upper 8 bits being defined for user/macro usage and lower bits for system user/macro usage. As such only the lower 16 bits maybe affected by this primitive.

The defines L_USER1 thru L_USER7 maybe used as manifest constants to access the user/macro area.

Parameters

bufnum	Buffer number, if omitted the current buffer is referenced.
start	Start line number of region within the selected buffer, otherwise if omitted the current line is referenced.
end	End of the region within the selected buffer, otherwise if omitted the current line is referenced as such one line shall be affected.
and_mask	Value AND’ed with the flags of matched lines.
or_value	Value OR’ed with the flags of matched lines.

Compatiblty

GriefEdit enforces two flag namespaces system and user each of 16 bits with only the lower user 16 bits being read-write, whereas CRiSP ™ allows read-write to all 32 bits.

Returns

The set_line_flags primitive returns the number at lines which were modified.

set_macro_history

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.

Note:

GRIEF maintains the history to the depth of 16.

Parameters

index

Optional int index.

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.

set_margins

int set_margins( [int bufnum],
[int left = NULL],
[int right = NULL],
[int style = NULL],
[int colorcolumn = NULL] )

Set buffer formatting margins.

Description

The set_margins() primitive configures one or more of the specified buffers bufnum margins.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced. A negative bufnum (e.g. -1) shall set the global margin parameters, which are applied when no buffer specific margin has been set.
left	Optional integer left margin. A non-positive value shall clear the buffer specific margin.
right	Optional integer right margin. A non-positive value shall clear the buffer speific margin.
style	Optional justification style.
colorcolumn	Optional colour column.

Returns

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

Portability

A GriefEdit extension.

set_mouse_action

int set_mouse_action( string name )

Set keyboard mouse handler.

Description

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

The set_mouse_action() primitive sets the name of the mouse action handler within the current keyboard.

Parameters

name	A string containing the name of the function to be associated with the current keyboard.

Returns

Returns the previous mouse action.

Portability

n/a

set_mouse_type

int set_mouse_type()

Sets the mouse type.

Description

The set_mouse_type() primitive sets the mouse type.

Parameters

type	Integer stating the current mouse type.

Value	Description
0	No mouse.
1	One-button mouse.
2	Two-button mouse.
3	Three-button mouse.

button1

Option integer indicates which button shall be treated as the first button. A value of zero indicates the left-most, with a value of one indicates the right-most button. By default the left-most button is the mouse button one.

Returns

none

Portability

n/a

set_msg_level

int set_msg_level( int level )

Set level of informational messages.

Description

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.

Parameters

level

Integer value specifying the new message level.

Returns

The set_msg_level() primitive returns the previous message level.

Portability

n/a

set_process_position

int set_process_position( [int line],
[int column] )

Set process insertion position.

Description

The set_process_position() primitive sets the line and/or column associated with the input from a subprocess.

Processes maintain their own independent input in the buffer so that it is easier to write macros which manipulate subprocesses.

Parameters

line	Optional integer specifying the line number, if positive the cursor is set to the specified line.
column	Optional integer specifying the column number, if positive the cursor is set to the specified column.

Returns

The set_process_position() primitive returns 0 on success, otherwise -1 if the current buffer is not attached to a process.

Portability

n/a

set_property

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

obj_id	Dictionary identifier.
key	Item key.
value	Item value.

Returns

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

Portability

A GriefEdit extension.

set_ruler

int set_ruler( [int bufnum],
[list|string|int ...] )

Configure the buffer ruler.

Description

The set_ruler() primitive configures the indentation ruler of the current buffer to the positions specified within ruler.

The primitive supports a number of alternative specification forms being either a set of integer parameters, a single string parameter containing space/comma separated numbers or a single list of integers. If omitted the ruler is cleared.

Regardless of the form each should be a sequence of columns in ascending order. The indentations for the reminder of the line are set using the difference between the last two stated positions, starting at the last specified.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
ruler	Optional ruler specification, being the sequence of columns in ascending order otherwise the ruler is cleared.

Returns

The set_ruler() primitive returns the number of applied ruler points, 0 is the ruler was cleared otherwise -1 on error.

Portability

A GriefEdit extension.

set_scrap_info

void set_scrap_info( [int last],
[int type],
[int bufnum] )

Set the scrap buffer details.

Description

The set_scrap_info() primitive specifies the mark type and newline handling to be applied against the scrap buffer.

Parameters

last	Not used; provided for BRIEF compatibility. If false the last newline in the scrap is not considered part of the scrap, otherwise true it is considered part of the scrap.
type	Optional integer value, specifies the mark-type to be applied to the scrap buffer.
bufnum	Optional integer buffer identifier, if stated changes the current scrap buffer to the specified buffer. The resulting buffer shall be marked with the buffer flag BF_SCRAPBUF.

Returns

The set_scrap_info() primitive returns 0 on success, otherwise -1 on error, for example in invalid buffer.

Portability

n/a

set_syntax_flags

int set_syntax_flags( int flags,
[int|string syntable] )

Set syntax flags.

Description

The set_syntax_flags() primitive sets the active flags for the specified syntax table.

Parameters

flags	Integer syntax flags, one or more of the following flags OR’ed together control the attributes of the reference syntax table.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Flags

Flag	Description
SYNF_CASEINSENSITIVE	Case insensitive language tokens.
SYNF_FORTRAN	FORTRAN style language.
SYNF_STRING_ONELINE	String definitions dont continue over line breaks.
SYNF_LITERAL_NOQUOTES	Literals dont quote.
SYNF_COMMENTS_LEADINGWS	Dont hilite leading white-space.
SYNF_COMMENTS_TRAILINGWS	Dont hilite trailing white-space.
SYNF_COMMENTS_QUOTE	Allow comment charcter to be quoted.
SYNF_COMMENTS_CSTYLE	C-style comments.
SYNF_PREPROCESSOR_WS	Dont hilite leading white-space.
SYNF_LINECONT_WS	Allow white-space after cont token.
SYNF_HILITE_WS	Hilite white-space.
SYNF_HILITE_LINECONT	Hilite line continuations.
SYNF_HILITE_PREPROCESSOR	Hilite preprocessor directives.
SYNF_SPELL_WORD	Enable word spell check.
SYNF_SPELL_COMMENT	Enable comment spell check.

Returns

The set_syntax_flags() primitive returns the value of the resulting flags, otherwise -1 on error.

Portability

A GriefEdit extension.

set_tab

int set_tab( [int increment],
[int bufnum] )

Derive the buffer tab stops.

Description

The set_tab() primitive derives a tabs configuration from the specified tab increment increment. If omitted the user shall be prompted for the tab increment.

Enter tab amount:

Parameters

increment	Optional positive integer, stating the tab increment if omitted the user shall be prompted.
bufnum	Optional buffer number, if omitted the current buffer shall be referenced.

Returns

Returns the applied tab increment, otherwise -1 on error.

Portability

A GriefEdit extension.

set_term_characters

int set_term_characters( int value0,
.... )

Set terminal special characters.

Description

The set_term_characters() primitive is one of a set of functions which value add to the console interface specification. Under Unix™ console attributes are derived from the system termcap or terminfo databases or similar interfaces under non-console and non-unix systems.

The set_term_characters() primitive configures the set of characters which are utilised by the tty console driver to represent window borders.

Each of the character parameters listed below may be either an integer or string expression representing the character value. An integer value (including character constants) are treated as a single character whilst running within graphics-mode, whereas a string shall be interpreted as an escape sequence. Values can be omitted by supplying a NULL parameter against the associated character index.

This function should generally be invoked prior to the display being enabled (See: display_windows), otherwise a redraw is required.

Index	Name	Description
0	top_left	Top left of a window.
1	top_right	Right right of a window.
2	bottom_left	Bottom left of a window.
3	bottom_right	Bottom right of a window.
4	vertical	Vertical window sides.
5	horizontal	Horizontal window sides.
5	top_join	Top intersection of window corners.
6	bottom_join	Bottom intersection of window corners.
7	cross	Intersection of window corners.
8	left_join	Left Window intersection.
9	right_join	Right window intersection.
10	scroll	Scroll bar arena.
11	thumb	Scroll bar thumb.

Parameters

...	Integer character value or string escape sequence, one for each character within the set.

Example

The following configures a terminal to use simple non-graphical characters to represent window borders.

set_term_characters(
    '+',    // 0.  Top left of window.
    '+',    // 1.  Top right of window.
    '+',    // 2.  Bottom left of window.
    '+',    // 3.  Bottom right of window.
    '|',    // 4.  Vertical bar for window sides.
    '-',    // 5.  Top and bottom horizontal bar for window.
    '+',    // 6.  Top join.
    '+',    // 7.  Bottom join.
    '+',    // 8.  Window 4-way intersection.
    '+',    // 9.  Left hand join.
    '+',    // 10. Right hand join.
    '*'     // 11. Thumb wheel.
    );

Note:

For further examples refer to the tty macros, which setup the terminal interface for many well known environments.

Returns

nothing

Portability

n/a

set_term_feature

int set_term_feature( int|string ident,
[string|int value] )

Set a terminal attribute.

Description

The set_term_feature() primitive is one of a set of functions which value add to the console interface specification. Under Unix™ console attributes are derived from the system termcap or terminfo databases or similar interfaces under non-console and non-unix systems.

The set_term_feature() primitive allows certain attributes about the current display to be modified; for example features which are not adequately handled by termcap or terminfo. The attribute identified by ident shall be set to value.

Parameters

ident	Either the integer identifier or a string containing the name of the terminal attribute to be modified.
value	Value to be applied against the attribute, if omitted or NULL the current value is cleared. The type of the value is specific to the attribute being modified, either in string or integer form.

Types

Each of the attributes are defined using one of four data types.

Escape	Terminal specific escape sequence being a series of characters that shall be written to the attached terminal. Controls supporting parameters should use printf style %d as the place holders for parameters; allowing terminfo/termcap independent macro development. Most of the sequence attributes are no longer required since the current generation of curses/ncurses terminfo or terminfo databases are complete. Supplied values shall only be utilised in the event these are missing from the current terminal description.
Boolean	Boolean flag, which can be stated as either a numeric zero/non-zero value or a string value yes/no.
Integer	Numeric value, either stated as an integer value or string containing a decimal value.
String	String value.

Attributes

The following terminal attributes are exposed

Constant

Name

Type

Description

TF_PRINT_SPACE

repeat_space

Escape

Control sequence to print a space n times.

TF_PRINT_BITEIGHT

print_character

Escape

Control sequence to print eight bit characters.

TF_INSERT_CURSOR

insert_cursor

Escape

Control sequence which modifies the cursor looks, utilised when GriefEdit has insert-mode enabled.

TF_OVERWRITE_CURSOR

overwrite_cursor

Escape

Control sequence which modifies the cursor looks, utilised when GriefEdit has overwrite-mode enabled.

TF_VINSERT_CURSOR

virt_insert_cursor

Escape

Control sequence which modifies the cursor looks, utilised when GriefEdit has insert-mode enabled and is positioned over a virtual-space.

TF_VOVERWRITE_CURSOR

virt_overwrite_cursor

Escape

Control sequence which modifies the cursor looks, utilised when GriefEdit has overwrite-mode enabled an is positioned over a virtual-space.

TF_PRINT_ESCAPE

print_escape

Escape

Control sequence which prints an ESC character graphically.

TF_REPEAT_LAST

repeat_last

Escape

Control sequence for repeating the previous character printed n times.

TF_0M_RESETS_COLOR

0m_resets_color

Boolean

When non-zero, then whenever an ESC[0m is printed, it is assumed that the background and foreground colours are reset (defunct).

TF_COLOR

color

Boolean

When non-zero, the terminal is assumed to support color.

TF_CURSOR_RIGHT

parm_cursor_right

Escape

Control sequence for move the cursor n characters within on the same line.

TF_CLEAR_IS_BLACK

clear_is_black

Boolean

When true states that area erase commands set the background of the erased line to black, otherwise the current background is assumed.

TF_DISABLE_INSDEL

noinsdel

Boolean

When true disables the use of window scrolling when attempting to optimise output; on several displays its faster to rewrite the window.

TF_GRAPHIC_MODE

graphics_mode

Escape

Control sequence to send when sending graphics (line drawing) characters.

TF_TEXT_MODE

text_mode

Escape

Control sequence to send when exiting graphics mode and going back to normal character set.

TF_RESET

reset

Escape

Control sequence to be executed during terminal initialisation operations.

TF_INIT

init

Escape

Control sequence to be executed during terminal reset operations.

TF_COLORSETFGBG

colorset_fgbg

Escape

Control sequence when executed sets both the foreground and backgrounds colours.

TF_COLORSET_FG

colorset_fg

Escape

Control sequence when executed sets the foreground colour.

TF_COLORSET_BG

colorset_bg

Escape

Control sequence when executed sets the background colour.

TF_COLORDEPTH

color_depth

Integer

Colour depth.

TF_DEFAULT_FG

default_fg_color

Integer

Terminals default foreground color.

TF_DEFAULT_BG

default_bg_color

Integer

Terminals default background color.

TF_SCHEMEDARK

scheme_dark

Boolean

When true the dark colour scheme variant shall be select over the light; if available.

TF_COLORMAP

color_map

String

Xterm colour map specification; a comma separated list of colours defining the colour palette.

TF_COLORPALETTE

color_palette

String

User defined palette.

TF_EIGHT_BIT

eight_bit

Boolean

When true the console supports the display of eight bit characters.

TF_MOUSE

mouse

String

Mouse device.

TF_MOUSECLKMS

mouse_clickms

Integer

Mouse click time in milliseconds.

TF_WINDOW_SETSIZE

winsetsize

Escape

Control sequence to set the window size to x by y.

TF_WINDOW_SETPOS

winsetpost

Escape

Control sequence to set the window position at x by y.

TF_CODEPAGE

codepage

Integer

Character code page.

TF_DISABLE_SCROLL

scroll_disable

Boolean

When true disables use of scroll region commands.

TF_SCROLL_MAX

scroll_max

Integer

Upper size of window to be scrolled permitting use of scroll region commands.

TF_NOALTSCREEN

noaltscreen

Boolean

When true denotes no alternative screen selection is available.

TF_LAZYUPDATE

lazy_update

Integer

When set to a positive value, indicates lazy screen updates are enabled. Screen updates are delayed until the keyboard becomes idle upto the stated number of lines.

TF_ATTRIBUTES

attributes

Integer

Terminal attribute bitmap; see the table below.

TF_NAME

name

String

Name of the terminal.

TF_TTY_FAST

tty_fast

Integer

When true disables use of pad characters.

TF_TTY_GRAPHICSBOX

tty_graphicsbox

Integer

When true enables use of graphic box characters.

TF_SCREEN_ROWS

screen_rows

Integer

Number of screen rows.

TF_SCREEN_COLS

screen_cols

Integer

Number of screen columns.

TF_LINENO_COLUMNS

lineno_columns

Integer

Terminal specific number of columns allocated for the display of buffer number lines.

TF_WINDOW_MINROWS

window_minrows

Integer

Minimum vertical size of a window.

TF_WINDOW_MINCOLS

window_mincols

Integer

Minimum horizontal size of a window.

TF_XTERM_COMPAT

xterm_compat

Integer

When true terminal to treated like an xterm.

TF_XTERM_CURSOR

xterm_cursor

Integer

When true terminal supports xterm cursor control commands.

TF_XTERM_TITLE

xterm_title

Integer

Control sequence when executed set the console title.

TF_XTERM_PALETTE

xterm_palette

Integer

Xterm palette selector.

TF_VT_DATYPE

vt_datype

Integer

Terminal type; xterm device attribute, known values are.

0	xterm.
77	mintty.
83	screen.
82	rxvt.
85	rxvt unicode.

TF_VT_DAVERSION

vt_daversion

Integer

Terminal version.

TF_ENCODING

encoding

String

Terminal character encoding.

TF_UNICODE_VERSION

unicode_version

String

UNICODE interface version, for example “6.0.1”.

TF_ATTRIBUTE

The reported TF_ATTRIBUTE attribute represents special terminal features mined during terminal initialisation. The flag argument can contain none or more of the following symbols bitwise OR’ed together.

Constant	Description
TF_AGRAPHICCHARACTERS	Graphic characters (ACS defined)
TF_AFUNCTIONKEYS	F1-F10 function keys.
TF_ACYGWIN	Cygwin native console.
TF_AUTF8ENCODING	UTF8 character encoding, Unicode implied.
TF_AUNICODEENCODING	Unicode character encoding.
TF_AMETAKEY	Meta keys.

Note:

Many of the exposed attributes are specific to the underlying terminal, a well known is the Xterm Control Sequences available on http://invisible-island.net.

Returns

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

Portability

A GriefEdit extension.

set_term_features

int set_term_features( list features )

Define terminal attributes.

Description

The set_term_features() primitive is one of a set of functions which value add to the console interface specification. Under Unix™ console attributes are derived from the system termcap or terminfo databases or similar interfaces under non-console and non-unix systems.

Similar to the set_term_feature, set_term_features allows attributes about the current display to be modifed; for example features which are not adequately handled by termcap or terminfo.

set_term_features utilises a list interface with elements within the list implied by the TF_XXXX enumeration. This permits bulk attribute initialisation at the expense of visibility. See set_term_feature for further details on the exposed attributes.

Parameters

list

Terminal attributes one or each attribute in the order implied by the TF_XXXX enumeration.
Each parameter may be either an integer or string expression representing the character value. An integer value (including character constants) are treated as a single character whilst within graphics-mode, whereas a string shall be interpreted as an escape sequence. Values can be omitted by supplying a NULL parameter against the associated character index.

Returns

nothing

Example

set_term_features(
    NULL,           // TF_PRINT_SPACE
    NULL,           // TF_PRINT_BITEIGHT
    NULL,           // TF_INSERT_CURSOR
    NULL,           // TF_OVERWRITE_CURSOR
    NULL,           // TF_VINSERT_CURSOR
    NULL,           // TF_VOVERWRITE_CURSOR
    NULL,           // TF_PRINT_ESCAPE
    NULL,           // TF_REPEAT_LAST
    FALSE,          // TF_0M_RESETS_COLOR
    FALSE,          // TF_COLOR
    "\x1B[%dC",     // TF_CURSOR_RIGHT
    TRUE,           // TF_CLEAR_IS_BLACK
    FALSE,          // TF_DISABLE_INSDEL
    "\x1B(0",       // TF_GRAPHIC_MODE
    "\x1B(B"        // TF_TEXT_MODE
    );

Portability

Many of the return values are only meaningful on systems that use a tty based console interface.

set_term_keyboard

int set_term_keyboard( list kbd )

Define terminal keyboard definitions.

Description

The set_term_keyboard() primitive is one of a set of functions which value add to the console interface specification. Under Unix™ console attributes are derived from the system termcap or terminfo databases or similar interfaces under non-unix systems.

The set_term_keyboard function manages the keyboard scan-code (terminal escape sequence) to key-code mapping table. For each key definition set_term_keyboard expects a pair of arguments, the first being Griefs internal key-code (See: key_to_int) with the second stating the associated escape sequence.

The mapped escape sequence shall be treated as unique; in what only the last instance shall be retained. Whereas key-codes can be associated with multiple escape sequences. For example, a generic Xterm mapping could support alternative function key reports.

The second argument may takes one of two forms. The first being a single string containing the escape sequence, the second being a key-list permitting a range of keys to be bound.

Example simple key associates including non-unique key codes.

set_term_keyboard(
        :

    KEY_PAGEUP,     "\x1b[5~",  // vt220 mode
    KEY_PAGEDOWN,   "\x1b[6~",
    KEY_INS,        "\x1b[2~",
    KEY_DEL,        "\x7f",

    KEY_PAGEUP,     "\x1b[5z",  // sunFunctionKeys mode
    KEY_PAGEDOWN,   "\x1b[6z",
    KEY_INS,        "\x1b[2z",

        :
    );

Character Ranges

The key-lists are simply a list of strings describing each consecutive key within a set or range of keys. A constant set of keys can be simply quoted using the quote_list function, alternatively the list can be constructed with the other list primitives.

The following character definitions are generally defined using a consecutive set of keys.

F1_F12
SHIFT_F1_F12
CTRL_A_Z
CTRL_F1_F12
CTRLSHIFT_F1_F12
ALT_F1_F12
ALT_A_Z
ALT_0_9
KEYPAD_0_9
CTRL_KEYPAD_0_9
SHIFT_KEYPAD_0_9
ALT_KEYPAD_0_9

Example of a consecutive definition against a constant set of sequences.

set_term_keyboard(
    F1_F12, quote_list(
        "\x1bOP",     "\x1bOQ",     "\x1bOR",     "\x1bOS",
        "\x1b[15~",   "\x1b[17~",   "\x1b[18~",   "\x1b[19~",
        "\x1b[20~",   "\x1b[21~",   "\x1b[23~",   "\x1b[24~" )
    );

Ambiguous

Due to the complex nature of terminal escape sequences, many key definitions result in ambiguous mappings; for example two or more mappings starting with the same sequence of characters. The mapping of ambiguous sequences to their associated key-code utilise a scan delay mechanism. When an ambiguous sequence is detected the driver waits several milliseconds before selecting the longest matching sequence, see set_char_timeout for details.

Note:

Many of the reported escapes are specific to the underlying terminal, a well known is the Xterm Control Sequences available on http://invisible-island.net.

Parameters

none

Returns

nothing

Example

The following is an example from the Linux terminal definition.

set_term_keyboard(

        :

    F1_F12,         quote_list(
        "\x1bOP",     "\x1bOQ",     "\x1bOR",     "\x1bOS",
        "\x1b[15~",   "\x1b[17~",   "\x1b[18~",   "\x1b[19~",
        "\x1b[20~",   "\x1b[21~",   "\x1b[23~",   "\x1b[24~"    ),

    SHIFT_F1_F12,   quote_list(
        NULL,         NULL,         "\x1b[25~",   "\x1b[26~",
        "\x1b[28~",   "\x1b[29~",   "\x1b[31~",   "\x1b[32~",
        "\x1b[33~",   "\x1b[34~",   "\x1b[23;2~", "\x1b[24;2~"  ),

    CTRL_F1_F12,    quote_list(
        "\x1bO5P",    "\x1bO5Q",    "\x1bO5R",    "\x1bO5S",
        "\x1b[15;5~", "\x1b[17;5~", "\x1b[18;5~", "\x1b[19;5~",
        "\x1b[20;5~", "\x1b[21;5~", "\x1b[23;5~", "\x1b[24;5~"  ),

        :
    );

Note:

For further examples refer to the tty macros, which setup the terminal interface for many well known environments.

Portability

n/a

set_terminator

int set_terminator( [int bufnum],
int|string term )

Set a buffers line terminator.

Description

The set_terminator() primitive retrieves the line terminator of the specified buffer bufnum.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
term	Either the integer enumeration or string description of the line terminator to be assigned.

Enumerations

Constant	Description
LTERM_UNDEFINED	Unknown/default.
LTERM_NONE	<none> (i.e. binary)
LTERM_UNIX	CR/LF
LTERM_DOS	LF
LTERM_MAC	CR
LTERM_NEL	NEL
LTERM_UCSNL	Unicode next line
LTERM_USER	User defined

Returns

The set_terminator() primitive returns 1 is the line terminator was modified, 0 when no change occured, otherwise -1 on error.

Portability

A GriefEdit extension.

set_top_left

int set_top_left( [int line],
[int column],
[int winnum],
[int csrline],
[int csrcolumn],
[int bufnum] )

Manages window view port coordinates.

Description

The set_top_left() primitive manages the view port coordinates, setting up the window and buffer positional relationship.

The window effected can be referenced by one of three means. Directly, winnum if specifies states the window identifier used. Indirectly, if winnum is omitted the window referenced shall be the one attached to the specified buffer identifier bufnum. If neither are specified then the current window is assumed.

The arguments line and column set the buffer coordinates displayed at the top left corner of the window.

csrline and csrcolumn set the buffers cursor position.

Parameters

line	Optional integer, specifies the line within the buffer which should be at the top of the window.
column	Optional integer, specifies the column within the buffer which should be at the top of the window
winnum	Optional window identifier, if omitted the current window shall be referenced.
csrline	Optional integer states the cursor position, if stated specifies the line within the buffer on which the cursor shall be positioned.
csrcolumn	Optional integer states the cursor position, if stated specifies the column within the buffer on which the cursor shall be positioned.
bufnum	Optional buffer identifier can be used to define a window indirectly, if winnum is omitted the window referenced shall be the one attached to the specified buffer identifier.

Returns

The effected window identifier, otherwise -1 on error.

Portability

n/a

set_window

int set_window( int winnum )

Set the active window.

Description

The set_window() primitive set the current window to the specified window identifier.

Parameters

winnum

Optional window identifier, if omitted the current window shall be referenced.

Returns

Returns non-zero if the window was changed, otherwise zero if specified window was already the current and no change occurred.

Portability

Unlike BRIEF the current buffer is not affected, which changed the buffer to the one associated with the specified window.

set_window_cmap

int set_window_cmap( [int mapid|string name],
[int winnum] )

Set a windows character-map.

Description

The set_window_cmap() primitive attachs the specified character-map to a given window. A single character-map can be attached to any number of windows.

By default two system predefined character-map’s are available known by the names “normal” and “binary”, these are in addition to the number managed by the view’s package.

Note that any buffer level association set_buffer_cmap shall have precedence over the windows view of a buffer.

Parameters

mapid, name	Character-map reference, being either an integer map identifier or the associated map name as a string. If omitted the default character-map shall be attached.
winnum	Optional window identifier, if omitted the current window shall be referenced.

Returns

The set_window_cmap() primitive returns the identifier of the resolved character-map otherwise -1 if the specified character map does not exist.

Portability

n/a

set_window_flags

void set_window_flags( [int winnum],
[string set|int or_mask],
[string clear|int and_mask] )

Set window flags.

Description

The set_window_flags() primitive modifies the window flags of the specified window winnum otherwise if omitted the current window.

If specified one or more flags shall be cleared using the and_mask, in additional one or more flags are set using the or_mask.

Note that and_mask (clear) is applied prior to the application of the or_mask (set).

Window Flags

Available window flags.

Constant	Name	Description
WF_HIDDEN	hidden	Hide the window from view, used to hide nested popup’s/boss mode etc.
WF_NO_SHADOW	no_shadow	Turn off the popup window shadows’
WF_NO_BORDER	no_border	Turn off borders, regardless of the borders() setting.
WF_SYSTEM	system	Window is a system window (e.g. menu).
WF_SHOWANCHOR	showanchor	Show anchor regardless of selection status.
WF_SELECTED	selected	Highlight the title regardless of selection status.
WF_LAZYUPDATE	lazyupdate	Delay any updates until next refresh().
WF_LINE_NUMBERS	line_numbers	Line numbers.
WF_LINE_STATUS	line_status	Line status.
WF_EOF_DISPLAY	eof_display	Show <EOF> marker.
WF_TILDE_DISPLAY	tilde_display	Show ~ marker as EOF marker.
WF_HIMODIFIED	himodified	Highlight modified lines.
WF_HIADDITIONAL	hiadditional	Highlight additional lines.
WF_HICHANGES	hichanges	Highlight in-line changes.
WF_EOL_HILITE	eol_hilite	Limit highlight to EOL.
WF_EOL_CURSOR	eol_cursor	Limit cursor to EOL.

Parameters

winnum	Optional window identifier, if omitted the current window shall be referenced.
set_mask	Optional mask of flags to set. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.
clear_mask	Optional mask of flags to clear. May either be an integer of AND’ed together flag constants, or alternatively a string of comma separated flag names.

Returns

nothing

Portability

The feature set exposed differs from CRiSP ™. It is therefore advised that the symbolic constants are using within a #ifdef construct.

String flag forms are GriefEdit extensions.

set_window_priority

int set_window_priority( int priority,
[int winnum] )

Set the window display priority.

Description

The set_window_priority() primitive sets the display priority of the specified window, if omitted the current window. The priority controls the display order of pop-up windows.

Parameters

priority	Window priority between the range of 0 .. 127.
winnum	Optional window identifier, if omitted the current window shall be referenced.

Returns

Returns the previous window priority, otherwise -1 on error.

Portability

A GriefEdit extension.

set_wm_name

void set_wm_name( [string wname],
[string iname] )

Set the window and/or icon name.

Description

The set_wm_name() primitive configures the window and/or the minimised icon name of the current running GriefEdit image.

Note:

Only available when running under a suitable windowing system, otherwise this primitive is a no-op.

Parameterss

wname	Optional string containing the window name.
iname	Optional icon name.

Returns

The set_wm_name() primitive returns zero or greater on success, otherwise -1 on error.

Portability

GriefEdit extended.

shell

int shell( [string cmd],
[int use_shell],
[string completion],
[string stdin],
[string stdout],
[string stderr],
[int mode],
[string spec] )

Spawn a sub-shell process.

Description

The shell primitive performs executes a command specified in cmd by creating a system dependent shell, and returns after the command has been completed.

The shell primitive can be used to create a subshell without exiting the current GriefEdit session; placing GriefEdit into the background. Without any arguments an interactive shell is created. The user terminates the sub-shell by typing the usual ^D or exit.

shell()

Alternatively the shell primitive can be used to execute an explicit command, as in the following examples.

The following example performs a uname(1) command redirecting into a output in a temporary working file for use on completion; the TRUE informs GriefEdit not to bother repainting the screen.

shell("uname 2>&1 >/tmp/uname.tmp", TRUE);

The following example performs a gmake command redirecting output plus registers the macro gmake_complete to be executed on completion.

shell("gmake 2>&1 >/tmp/gmake.tmp", TRUE, "gmake_completion");

associated completion macro.

void
gmake_completion(int status)
{
    message("gmake done, status = %d", status);
}

Meta Characters

As the command is passed on to a command processor care should be taken with special characters (including $, ?, *, [ and ;) since the command wild-card and environment expansion will occur.

Although there is no definite syntax for wildcard operations, common features include:

Wildcard	Description
?	Matches any single character.
*	Matches none or more characters.
[seq]	Matches any one of the characters within the sequence. Sequences generally support ranges; two characters separated by - denote a range. (e.g. [A-Fa-f0-9] is equivalent to [ABCDEFabcdef0123456789].)
[!seq]	Matches any one of the characters not contained within the sequence.

Redirection

In addition input/output redirection is system dependent and/or shell command interpreter specific. Despite this fact the following are normally supported across all supported GriefEdit targets.

Redirection	Description
>	Writes the command output to a file or a device, such as a printer, instead of the Command Prompt window.
<	Reads the command input from a file, instead of reading input from the keyboard.
>>	Appends the command output to the end of a file without deleting the information that is already in the file.
>&	Writes the output from one handle to the input of another handle; the standard handle assignments are 0=stdin, 1=stdout and 2=stderr.
<&	Reads the input from one handle and writes it to the output of another handle.

Note:

If there is any doubt regarding portability of redirection operators it is advised to use the explicit stdin, stdout and stderr arguments.

Parameters

cmd	Optional string containing the command to be passed to the host environment to be executed by a command processor in an implementation-dependent manner. If omitted a interactive sub-shell is created.
use_shell	Optional boolean value, if true forces the original display and terminal settings to the restored, and than initialised on completion of the sub-process.
completion	Optional string containing the name of macro to be executed on the termination of the sub-process. The completion routine is called with the first parameter set to the return status from the underlying process. Any other positional parameters are shifted up one.
stdin	Option string, specifies the name of the file/device from which standard input shall be source. If omitted the sub-shell standard input remains unchanged.
stdout	Option string, specifies the name of the file/device to which standard output shall be redirected. If omitted the sub-shell standard output remains unchanged.
stderr	Option string, specifies the name of the file/device to which standard error shall be redirected. If omitted the sub-shell standard error remains unchanged.
mode	Optional mode flags, specifies the creation mode to be utilised during stream creation. If omitted 0644 is applied.
spec	Optional string, reserved for future use.

Returns

The shell primitive returns the exit status from the executed command (0 .. 256), otherwise -1 on error and sets errno to indicate the error.

Constant	Description
E2BIG	Combined Size of environment and argument list is too large.
EACCES	Search permission is denied on a component of the path prefix of filename or the name of a script interpreter.
EACCES	The file or a script interpreter is not a regular file.
EACCES	Execute permission is denied.
EIO	An I/O error occurred.
ENAMETOOLONG	Path is too long.
ENOENT	The command or one of its components does not exist.
ENOEXEC	An executable is not in a recognized format, is for the wrong architecture, or has some other format error that means it cannot be executed.
ENOMEM	Insufficient kernel memory was available.

Portability

A arguments differ from the original implementation.

shift

declare shift( list lst )

Shift the first list element.

Description

The shift() primitive removes (shifts) the first value of the list lst off and returns its, shortening the list by 1 and moving everything down.

If there are no elements in the list, the following is echoed onthe command promot and shift returns the null value.

shift: empty list.

Parameters

lst	List expression.

Returns

The shift() primitive returns the first element on the list.

Examples

Iterator the list from the front, removing and then printing each element in the process;

list l = {"one", "two", "three", "four"};

while (length_of_list(l)) {
    message("%s", shift(l));
}

the resulting output

one
two
three
four

Portability

A GriefEdit extension

sin

float sin( float val )

Sine function.

Description

The sin() primitive computes the sine of the argument ‘val, measured in radians.

Returns

Upon successful completion, shall return the sine of x.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

sinh

float sinh( float val )

Hyperbolic sine function.

Description

The sinh() primitive computes the hyperbolic sine of the argument val.

Returns

Upon successful completion, shall return the hyperbolic sine of x.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

sleep

void sleep( [int seconds = 1],
[int milliseconds = 0] )

Suspend execution for an interval of time.

Description

The sleep() primitive causes the caller to be suspended from execution until either the specified interval specified by seconds and milliseconds has elapsed.

Note:

The suspension time may be longer than requested due to the scheduling of other activity by the system.

Parameters

seconds	Optional positive integer stating the time-out interval seconds component, if omitted defaults to 1 second.
milliseconds	Option positive integer stating the time-out interval milliseconds component.

Returns

nothing

Portability

n/a

sort_buffer

int sort_buffer( [int bufnum],
[string|int comparator = 0],
[int start],
[int end],
[int type = 3] )

Sort buffer content.

Description

The sort_buffer() primitive sorts the lines in the current buffer or the buffer specified by bufnum. If the buffer specified has a region marked, then only those lines within the region are sorted.

By default lines are sorted alphabetically yet the sort can be modified using the user specified macro or using one of the predefined system sort macros.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
comparator	Optional string comparison macro or integer direction. A string value states the comparison macro to be executed. Whereas an integer value states the direction, with zero selecting the built “sort_buffer::forward” comparator and a non-zero value selecting “sort_buffer::backwards”. If omitted the comparator defaults to forward.
start	Optional integer line number stating the start of the region to be sorted, if omitted the buffer top is used unless a marked region is active.
end	Optional integer line number stating the end of the region to be sorted, if omitted the buffer end is used unless a marked region is active.
type	Optional integer stating the sort type, being

1	quicksort.
2	mergesort
3	heapsort (default).

Returns

The sort_buffer() primitive returns the number of lines sorted, otherwise a negative value on error.

Portability

Second argument allowing either a sort-order or user specified callback plus type selection are GriefEdit extensions.

Description

The sort_list() primitive sorts the list and returns the sorted array value.

By default elements are sorted alphabetically yet the sort can be modified using the user specified macro or using one of the predefined system sort macros.

Sort Method

GriefEdit 2.5.4 and earlier bindly utlilised the system supplied quicksort algorithm to implement sort. The characteristics of the algorithm could not defined as such was normally unstable, plus may have gone quadratic. (Although quicksort’s run time is O(NlogN) when averaged over all arrays of length N, the time can be O(N**2), quadratic behavior, for some inputs.

Following Perl and Java in 2.5.5 the default sort implementation was replaced with a stable mergesort algorithm whose worst-case behavior is O(NlogN). In addition quicksort defends against quadratic behaviour by shuffling large arrays before sorting.

A stable sort means that for records that compare equal, the original input ordering is preserved. Mergesort is stable, quicksort is not. Stability will matter only if elements that compare equal can be distinguished in some other way. That means that simple numerical and lexical sorts do not profit from stability, since equal elements are indistinguishable. However, with a comparison such as

int
mysort(string a, string b)
{
    return (substr(a, 0, 3) <=> substr(b, 0, 3));
}

stability might matter because elements that compare equal on the first 3 characters may be distinguished based on subsequent characters. In Perl 5.8 and later, quicksort can be stabilized, but doing so will add overhead, so it should only be done if it matters.

The best algorithm depends on many things. On average, mergesort does fewer comparisons than quicksort, so it may be better when complicated comparison routines are used. Mergesort also takes advantage of pre-existing order, so it would be favored for using sort() to merge several sorted arrays. On the other hand, quicksort is often faster for small arrays, and on arrays of a few distinct values, repeated many times. You can force the choice of algorithm with the specification of the third argument. The default algorithm is mergesort, which will be stable even if you do not explicitly demand it. The stability of the default sort is a side-effect that could change in later versions.

int
mycmp(string a, string b)
{
    return (a <=> b);
}

Note:

In the interests of efficiency the normal calling code for subroutines is bypassed, with the following effects: elements to be compared are passed into a and b, are passed by reference as such do not modify a and b.

Parameters

list	List to be sorted.
comparator	Optional string comparison macro or integer direction. A string value states the comparison macro to be executed. Whereas an integer value states the direction, with zero selecting the built “sort_list::backward” comparator and a non-zero value selecting “sort_list::forward. If omitted the comparator defaults to forward.
type	Optional integer stating the sort type, being

1	quicksort.
2	mergesort
3	heapsort (default).

Returns

Sorted list.

Portability

Second argument allowing either a sort-order or user specified callback plus type selection are GriefEdit extensions.

spell_buffer

list spell_buffer( int start_line,
[int end_line],
[int tokenize = 1],
[int suggest] )

Spell the specified buffer.

Description

The spell_buffer() primitive spell checks the specified lines within the current buffer.

The string passed in should only be split on white space characters.

Furthermore, between calls to reset each string should be passed in exactly once and in the order they appeared in the document. Passing in stings out of order, skipping strings or passing them in more than once may lead to undefined results.

Parameters

start_line	Integer line number, being the first line at which spell
end_line	Optional integer line number, denoting the line at which spell check shall complete. If omitted checks are performed until the end-of-buffer.
tokenize	Optional integer flag, if specified as zero the buffer content shall not be split into tokens during parsing.
suggest	Optional integer flag, if specified as non-zero spelling suggestions shall be returned against each misspelt word.

Returns

The spell_buffer() primitive returns a list of possible spelling errors in the form.

[<word>, <suggest-list|NULL>, <offset>, <column>, <line> [, <count>]]

Portability

A GriefEdit extension.

spell_control

declare spell_control( int action,
... )

Spell control.

Description

The spell_control() primitive manipulates the spell engine attribute associated with the specified action. Additional arguments are specific to the action or attribute being modified.

Parameters

action	Integer identifier of the engine attribute to be manipulated.
...	Action specific value.

Modes

Action	Description
SPELL_DESCRIPTION	Spell implementation description, returns a string containing the name of the current speller.
SPELL_DICTIONARIES	List of available dictionaries, retrieves a list of string each the name of a available dictionary.
SPELL_LOAD	Load a personal dictionary.
SPELL_SAVE	Save to a personal dictionary.
SPELL_ADD	Add to the personal dictionary.
SPELL_IGNORE	Add to the spell ignore list.
SPELL_REPLACE	Add to the spell replacement list.
SPELL_LANG_ADD	n/a
SPELL_LANG_PRIMARY	n/a
SPELL_LANG_REMOVE	n/a

Returns

The spell_control() primitive usually, on success returns zero, otherwise -1 on error.

A few spell_control requests return non-integer values, either a string or list, based on the attribute that was manipulated by the specified action, see table above.

Portability

A GriefEdit extension.

spell_dictionary

int spell_dictionary( int,
string|list )

Spell dictionary modifications.

Description

The spell_dictionary() primitive is reserved.

Parameters

n/a

Returns

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

Portability

A GriefEdit extension.

spell_distance

int spell_distance( string a,
string b )

Edit distance.

Description

The spell_distance() primitive computes the “distance” between two words by counting the number of insert, replace, and delete operations required to permute one word into another.

In general the fewer operations required, the closer the match. Some implementations assign varying scores to the insert, replace, and delete operations. Another common variation varies which operations are considered when computing the distance; for example, the replace operation may not be considered, thereby defining the edit distance solely in terms of insert and delete options.

This algorithm uses one of the more popular algorithms in the edit distance known as the “Levenshtein distance”.

The costs assigned to each move are equal, that is of the following operations have a cost of 1.

Delete a character
Insert a character
Character substitution.

Parameters

s1	String one.
s2	Second string.

Returns

The spell_distance() primitive returns the edit distance between the two words.

Portability

A GriefEdit extension.

spell_string

int spell_string( string word,
[int length],
[int tokenize = 0],
[int suggest = FALSE] )

Spell the specified word or line.

Description

The spell_string() primitive spell checks the specified string word

The string passed in should only be split on white space characters.

Parameters

word	String containing the text to be checked.
length	Optional integer, stating the number of characters within the string to be parsed.
tokenize	Optional integer flag, if specified as non-zero the string content shall be split into tokens during parsing.
suggest	Optional integer flag, if specified as non-zero spelling suggestions shall be returned against each misspelt word.

Returns

The spell_string() primitive returns a value dependent on the input mode.

For word checks, 0 on success, other non-zero.

For string or line checks, list of possible incorrect words offset/line + length pairs with optional suggestion list, with offsets starting from 1.

[<word>, <suggest-list|NULL>, <offset>, <column>]

Portability

A GriefEdit extension.

spell_suggest

list spell_suggest( string word,
[int length] )

Suggest spelling of the the specified word.

Description

The spell_distance() primitive spell checks the specified word building a list of possible suggestions.

Parameters

word	xxx
length	xxx

Returns

The spell_suggest() primitive returns a list of possible suggestions, otherwise null.

Portability

A GriefEdit extension.

splice

int splice( list lst,
int offset = 0,
[int length],
[declare value]    )

Splice a list, removing and/or adding elements.

Description

The splice() primitive removes the elements designated by offset and length from an list, and replaces them with the elements of value, if any.

If offset is negative then it starts that far from the end of the list.

If length is negative, removes the elements from offset onward except for -length elements at the end of the list.

If length is omitted, removes everything from offset onward. If both offset and length are omitted, removes everything.

If offset is past the end of the list, warning is issued and splices at the end of the list.

Parameters

lst	List expression.
offset	Non-negative list offset from the front at which element are to be removed, when negative then it starts from the end. If omitted removes from the head of the list.
length	Optional number of elements to be remove.
value	Optional value to be inserted at the deletion point.

Examples

Equivalent

The splice primitive provides a general purpose list manipulation tool, which can be as a alternative to a number of specialise primitives.

The following macro primitives push, <+=>, pop, cdr, unshift use on the left are equivalent to right splice usage.

push(lst, x)
or lst += x         splice(lst, length_of_list(a), 0, x)
pop(lst)            splice(lst, -1)
cdr(lst)            splice(lst, 0, 1)
unshift(lst, x)     splice(lst, 0, 0, x)
lst[i] = y          splice(lst, i, 1, y)

Flatten mode

Splice usage implies the non-flatting of a source list when appending into another, whereas list append operations shall flatten the source list at level 0, as such when used in the following context the result is;

list lst = make_list("a", "b");
lst += lst;
// result = "a", "b", "a", "b"

The alternative splice usage which shall place a list reference within the list.

splice(lst, length_of_list(lst), 0, lst);

Returns

nothing

Portability

A GriefEdit extension.

split

list split( string expr,
string|integer delims,
[int numeric = FALSE],
[int noquoting = FALSE],
[int empties = FALSE],
[int limit = NULL] )

Split a string into tokens.

Description

The split() primitive splits the string expr into a list of strings and returns the resulting list.

split provides simple field processing, compared to the tokenize primitive which offers greater functionality.

Parameters

expr	String to be parsed.
delims	Specifies either a string containing the characters used to split the token, alternative an integer character value of a single character.
numeric	If specified and is true(1), then all tokens which start with a digit are converted to a number, rather than a string. Alternative when given as two (2) then values are converted using strtol(), allowing support leading base specifications hexidecimal (0x), octal (0) and binary (0b).
nonquoting	Upon the delim parameter containing a double quote character then it is assumed that any entries inside double quotes should have any embedded characters preserved. When specified the noquote optional allows explicit control enabling and disabling of this feature.
empties	Upon the delim character being given as a integer value empty split column are not returned witnin the list. When specified the empties optional allows explicit control enabling (non-zero) and disabling (zero) to whether empties are returned.
limit	Limit the split to limit elements, returning remaining content in the last element; not implemented at this time.

Results

List of strings where each string is a token from the string parameter.

Portability

The options empties and limit are GriefEdit extensions.

Examples

Using | was a delimiter and empties being returned.

''         ==> ''
'a'        ==> 'a'
'|b'       ==> '', 'b'
'|'        ==> '', ''
'a|b'      ==> 'a', 'b'
'a|b|'     ==> 'a', 'b', ''
'a|b|c'    ==> 'a', 'b', 'c'
'a||b'     ==> 'a', '', 'b'

the same without empties

''          ==>
'a'         ==> 'a'
'|b'        ==> 'b'
'|'         ==>
'a|b'       ==> 'a', 'b'
'a|b|'      ==> 'a', 'b'
'a||b'      ==> 'a', 'b'

split_arguments

list split_arguments( string arguments )

Argument split.

Description

The split_arguments() primitive splits argument into list of words. As it parses the command line, split_arguments looks for command separators, white space (spaces and tabs). Normally, these special characters cannot be passed to a command as part of an argument. However, special characters in an argument by enclosing the entire argument in double quotes [“]. The [“] themselves will not be passed to the command as part of the argument. Within a double quoted string the [“] character and [\] character can be represented as [\”] and [\\].

Parameters

argument

String containing the argument buffer.

Return

The split_argument returns a list of words encountered within the argument buffer.

Portability

A GriefEdit extension.

sprintf

int sprintf( string & buffer,
string format,
... )

Formatted printing to a string.

Description

The sprintf() primitive produces formatted output according to the format specification format into the given string buffer. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.

The format primitive is similar to the C sprintf() primitive, exporting the formatted result into the destination buffer.

This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.

Parameters

buffer	String which shall be populated with the result.
format	String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested.
...	Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive.

Returns

The sprintf() primitive returns the number of charaters stored within the result string buffer.

Portability

See message

sqrt

float sqrt( float val )

Square root function.

Description

The sqrt() primitive computes the square root of the argument val.

Returns

Upon successful completion, shall return the square root of val.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

srand

int srand( [int seed = time()],
[int depth] )

Seed the random number generator.

Description

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.

Parameters

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.

Returns

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

sscanf

int sscanf( string str,
string format,
... )

Read formatted data from string.

Description

The sscanf() primitive reads data from the string buffer str. Data input are stored in the locations specified by argument according to the format string format.

The additional arguments should be objects of the type specified by their corresponding format specifier within the format string.

Parameters

str	Source buffer.
format	String that contains a format string, see below.
...	Additional arguments; depending on the format string, the function may expect a sequence of additional arguments, each containing a reference to a variable where the interpretation of the extracted characters is stored with the appropriate type. There should be at least as many of these arguments as the number of values stored by the format specifiers. Additional arguments are ignored by the function.

Return Value

The sscanf() primitive returns the number of input fields that were successfully converted. An EOF (-1) is returned if an error is encountered.

Portability

A GriefEdit extension.

Format Specification

The format may be composed of one or more whitespace characters, non whitespace characters, and format specifications.

The format string is read from left to right. Characters that are not part of the format specifications must match characters in the input stream. These characters are read from the input stream but are discarded and not stored. If a character in the input stream conflicts with the format string, scanf terminates. Any conflicting characters remain in the input stream.

whitespace characters - blank (‘ ‘), tab (\t), or newline (\n), cause scanf to skip whitespace characters in the input stream. A single whitespace character in the format string matches 0 or more whitespace characters in the input stream.
non whitespace characters - with the exception of the percent sign (%), cause scanf to read but not store a matching character from the input stream. The scanf function terminates if the next character in the input stream does not match the specified non-whitespace character.
format specifications - begin with a percent sign (%) and cause scanf to read and convert characters from the input stream to the specified type values. The converted value is stored to an argument from the parameter list. Characters following a percent sign that are not recognized as a format specification are treated as ordinary characters. For example, %% matches a single percent sign in the input stream.

Format Specification

The first format specification encountered in the format string references the first argument after format. The scanf function converts input characters and stores the value using the format specification. The second format specification accesses the second argument after format, and so on. If there are more arguments than format specifications, the extra arguments are ignored. Results are unpredictable if there are not enough arguments for the format specifications.

Values in the input stream are called input fields and are delimited by whitespace characters. When converting input fields, scanf ends a conversion for an argument when a whitespace character or another unrecognized character is encountered.

Format specifications have the following format

% [*] [width] type

Each field in the format specification can be a single character or a number which specifies a particular format option.

The type field is where a single character specifies whether input characters are interpreted as a character, string, or number. This field can be any one of the characters in the following table.

scanf types
Character	Argument Type	Input Format
d	int &	Signed decimal number.
i	int &	Signed decimal, hexadecimal, or octal integer.
u	int &	Unsigned decimal number.
o	int &	Unsigned octal number.
x	int &	Unsigned hexadecimal number.
e	float &	Floating-point number.
f	float &	Floating-point number.
g	float &	Floating-point number.
c	int &	A single character.
s	string &	A string of characters terminated by whitespace.
\[	string &	A string not to be delimited by space characters.

Type Specifiers

An asterisk (*) as the first character of a format specification causes the input field to be scanned but not stored. The asterisk suppresses assignment of the format specification.

The width field is a non-negative number that specifies the maximum number of characters read from the input stream. No more than width characters are read and converted for the corresponding argument. However, fewer than width characters may be read if a whitespace or other unrecognized character is encountered first.

Character Set

[ indicates a string not to be delimited by space characters.

The conversion specification includes all subsequent characters in the format string up to and including the matching right square bracket (]).

The characters between the square brackets comprise the scanset, unless the character after the left square bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right square bracket.

If the conversion specification begins with “[]” or “[^]”, the right square bracket is included in the scanlist and the next right square bracket is the matching right square bracket that ends the conversion specification; otherwise the first right square bracket is the one that ends the conversion specification.

If a hyphen character (-) is in the scanlist and is not the first character, nor the second where the first character is a circumflex (^), nor the last character, it indicates a range of characters to be matched. To include a hyphen, make it the last character before the final close bracket. For instance, `[^]0-9-]’ means the set `everything except close bracket, zero through nine, and hyphen’.

Character classes

Within a bracket expression, the name of a character class enclosed in [: and :] stands for the list of all characters (not all collating elements!) belonging to that class.

Types
Identifier	Description
alpha	A letter.
upper	An upper-case letter.
lower	A lower-case letter.
blank	A space or tab character.
digit	A decimal digit.
xdigit	A hexadecimal digit.
alnum	An alphanumeric (letter or digit).
print	An alphanumeric (same as alnum).
blank	A space or tab character.
space	A character producing white space in displayed text.
punct	A punctuation character.
graph	A character with a visible representation.
cntrl	A control character.
word	A “word” character (alphanumeric plus “_”).

Type Specifiers

stat

int stat( [string path],
[int size],
[int mtime],
[int ctime],
[int atime],
[int mode],
[int uid],
[string uid2name],
[int gid],
[string gid2name],
[int nlink],
[int inode] )

Obtain file information.

Description

The stat() primitive obtain information about the file or directory referenced in path.

This information is returned in the parameters following the path parameter (if supported by the underlying filesystem).

size - Total file size, in bytes.
mode - File mode ((see File Modes )).
mtime - The files “last modified” time (See: time).
atime - Time the file was “last accessed”.
ctime - Time of the files “last status change”.
uid - User identifier.
uid2name - User name associated with the file uid.
gid - Group identifier.
gid2name - Group name associated with the file gid.
nlink - Number of hard links.
inode - File-system internal node number.

Parameters

For regular files, the file size in bytes.

path	String containing the file path. If omitted the statistics of the current buffer shall be retrieved.
size	Optional integer, if specified is populated with the size of the related file in bytes.

For symbolic links, the length in bytes of the path-name contained in the symbolic link.

For a shared memory object, the length in bytes.

For a typed memory object, the length in bytes.

For other file types, the use of this field is unspecified.

mtime	Optional integer, populated with the files modification time (See: time).
ctime	Optional integer, populated with the time of the last status change.
atime	Optional integer, populated with the last access time.
mode	Optional integer, mode of file ((see File Modes )).
uid	Optional integer, user identifier of the file.
uid2name	User name associated with the file uid.
gid	Optional integer, group identifier of the file.
gid2name	Group name associated with the file gid.
nlink	Optional integer, number of hard links to the file.
inode	Optional integer, populated with the file-system internal node number.

Returns

The stat() primitive returns zero if successful, and a non-zero value (-1) otherwise. When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

n/a

static

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");

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

Returns

nothing

Portability

Module static declarations are a GRIEF extension.

strcasecmp

int strcasecmp( string s1,
string s2,
[int length] )

String case insensitive compare.

Description

The strcmp() primitive shall compare the string s1 to the string s2, ignoring case.

Parameters

s1	First string.
s2	Second string to compare against.
length	Optional, when specified only the first length characters of both string shall be compared.

Return

strcasecmp() shall return an integer greater than, equal to, or less than 0, if the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2, respectively; when ignoring case.

Portability

A GriefEdit extension.

strcasestr

sub-string. int strcasestr(
string haystack,
string needle
)

Locate first occurrence of a case insensitive.

Description

The strcasestr() primitive finds the first occurrence of the case insensitive sub-string needle in the string haystack.

Parameters

haystack	String object to be searched.
needle	String to be matched.

Return

Index of first matching character starting at the index one, otherwise zero if no match.

Portability

A GriefEdit extension.

strcmp

int strcmp( string s1,
string s2,
[ int length] )

String compare.

Description

The strcmp() primitive shall compare the string s1 to the string s2 not ignoring case.

Parameters

s1	First string.
s2	Second string to compare against.
length	Optional, when specified only the first length characters of both string shall be compared.

Return

strcmp() shall return an integer greater than, equal to, or less than 0, if the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2, respectively.

Portability

A GriefEdit extension.

strerror

string strerror( [int errnum = errno],
[string &manifest],
[int multi = FALSE] )

String error.

Description

The strerror() primitive maps the error number in errnum to a locale-dependent error message and returns a string containing the mapped condition.

Parameters

errnum	Integer value of the error condition to be decoded, if omitted the current system errno is decoded.
manifest	Optional string variable which is specified shall be populated with the signal manifest.

Returns

The strerror function returns a string descripting the error value, otherwise an empty string if undefined.

Portability

The manifest and multi options are GriefEdit extensions.

strfilecmp

int strfilecmp( string file1,
string file2,
[int length] )

Filename comparison.

Description

The strfilecmp() primitive lexicographically compares the filenames name1 and name2 and returns a value indicating their relationship, taking into account any filesystem implementation specifics.

If specified length defines the number of significant characters of each path which shall be compared, ignoring any characters after the length characters of each.

Notes

Under DOS, Windows and OS/2 this primitive is case insensitive and permits the intermixing of both back(\) and forward(/) slashes as directory delimiters.

Under Unix™ this primitive is the same as an equality (==) operation between two strings.

Returns

The return indicates the lexicographic relation of name1 and name2.

<0 - name1 less than name2.
 0 - name1 identical to name2.
>0 - name1 greater than name2.

Portability

A GriefEdit extenions.

strftime

string strftime( [string format = NULL],
[int time = NULL] )

Format time and date.

Description

The strftime() primitive is an interface to the system library function strftime. Unless time is specified, the current time shall be formatted otherwise the stated time shall be formatted.

The format specification is a string and may contain special character sequences called conversion specifications, each of which is introduced by a % character and terminated by some other character known as a conversion specifier character. All other character sequences are ordinary character sequences.

Conversion specifications

Most implementations support the following conversion specifications.

%a	is replaced by the locale’s abbreviated weekday name.
%A	is replaced by the locale’s full weekday name.
%b	is replaced by the locale’s abbreviated month name.
%B	is replaced by the locale’s full month name.
%c	is replaced by the locale’s appropriate date and time representation.
%C	is replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99].
%d	is replaced by the day of the month as a decimal number [01,31].
%D	same as %m/%d/%y.
%e	is replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.
%h	same as %b.
%H	is replaced by the hour (24-hour clock) as a decimal number [00,23].
%I	is replaced by the hour (12-hour clock) as a decimal number [01,12].
%j	is replaced by the day of the year as a decimal number [001,366].
%m	is replaced by the month as a decimal number [01,12].
%M	is replaced by the minute as a decimal number [00,59].
%n	is replaced by a newline character.
%p	is replaced by the locale’s equivalent of either a.m. or p.m.
%r	is replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p.
%R	is replaced by the time in 24 hour notation (%H:%M).
%S	is replaced by the second as a decimal number [00,61].
%t	is replaced by a tab character.
%T	is replaced by the time (%H:%M:%S).
%u	is replaced by the weekday as a decimal number [1, 7], with 1 representing Monday.
%U	is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
%V	is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01, 53]. If the week containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1.
%w	is replaced by the weekday as a decimal number [0, 6], with 0 representing Sunday.
%W	is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00, 53]. All days in a new year preceding the first Monday are considered to be in week 0.
%x	is replaced by the locale’s appropriate date representation.
%X	is replaced by the locale’s appropriate time representation.
%y	is replaced by the year without century as a decimal number [00,99].
%Y	is replaced by the year with century as a decimal number.
%Z	is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
%%	is replaced by %.

Returns

The strftime function returns a string containing the formatted time and date.

Portability

A GriefEdit extension.

string

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

string_count

int string_count( string haystack,
int needle|string needles )

Count occurrences of characters in a string.

Description

The string_count() primitive computes the number of occurrences of the character(s) within needles in the string haystack.

Parameters

haystack	String to be searched.
needle	Elements to the counted, each character shall be accumulated.

Returns

Returns the number of times the characters in needle occur in the string parameter.

Portability

The integer needle form is a GriefEdit extension.

strlen

int strlen( string|list arg,
[int step = 1] )

String length.

Description

The strlen() primitive computes the length of arg.

For string arguments, computes the length of the string in character.

In the case arg is a list, computes the length of the longest string element contained within the list. Non-string elements shall be omitted. If specified and positive, iteration through the list shall only inspect each step element, starting with the first element within the list.

Parameters

arg	String or list.
step	Optional integer, stating the list iterator step value 1 or greater.

Returns

The strlen() primitive returns the number of characters contained within the string.

strnlen

int strnlen( string|list arg,
int maxlen,
[int step = 1] )

String length limited to an explicit maximum.

Description

The strnlen() primitive computes the length of arg limited to maxlen.

For string arguments, computes the length of the string in character.

In the case arg is a list, computes the length of the longest string element contained within the list in characters. Non-string elements shall be omitted. If specified and positive, iteration through the list shall only inspect each step element, starting with the first element within the list.

Parameters

arg	String or list.
maxlen	Upper limit to be applied to the length.
step	Optional integer, stating the iterator step value.

Returns

The strnlen() primitive returns either the same result as strlen() or maxlen, whichever is smaller.

Portability

A GriefEdit extension.

strpbrk

int strpbrk( string str,
string characters )

Search a string for any of a set of characters.

Description

The strpbrk() primitive returns the index of the first character in str which matches any character from the string characters.

This function is like index() and rindex() yet these only matches a single character string rather than a complete sub-string.

Return

Index of first matching character starting at the index one, otherwise zero if no match.

Portability

A GriefEdit extension.

strpop

string strpop( string str,
[int length = 1] )

Pop the leading character(s).

Description

The strpop() primitive is equivalent to substr(sym, 1, length) with the additional functionality that the returned character is removed from the specified string str.

Portability

length is a GriefEdit extension.

Return

String value containing the first character(s) of the original value of sym.

strrstr

int strrstr( string haystack,
string needle )

Locate last occurrence of a sub-string.

Description

The strrstr() primitive finds the last occurrence of the sub-string needle in the string haystack.

Parameters

haystack	String object to be searched.
needle	String to be matched.

Return

Index of last matching character starting at the index one, otherwise zero if no match.

Portability

A GriefEdit extension.

strsignal

int strsignal( int signo,
[string &manifest],
[int multi = FALSE] )

Return string describing signal.

Description

The strsignal() primitive returns a string describing the signal number passed in the argument signo.

Parameters

signo	Integer value of the signal number to be decoded.
manifest	Optional string variable which is specified shall be populated with the signal manifest.

Returns

The strsignal() primitive returns the appropriate description string, or an unknown signal message if the signal number is invalid.

Portability

A GriefEdit extension.

strstr

int strstr( string haystack,
string needle )

Locate first occurrence of a sub-string.

Description

The strstr() primitive finds the first occurrence of the sub-string needle in the string haystack.

Parameters

haystack	String object to be searched.
needle	String to be matched.

Return

Index of first matching character starting at the index one, otherwise zero if no match.

Portability

A GriefEdit extension.

strtod

int strtod( string str,
[int &endofoffset] )

String to double.

Description

The strtod() primitive converts the initial portion of the string str to a floating point double representation; it is an interface to the standard library function of the same name.

Returns

Upon successful completion, strtod() returns the converted value, if any, and (if supplied) an index (base of 1) to the first unprocessed character within the string is stored in the integer object endoffset.

If no conversion could be performed, strtod() returns 0 and errno may be set to EINVAL. The subject sequence contains no characters and index of 0 is stored in endoffset.

If the correct value is outside the range of representable values, strtod() returns HUGE_MAX or HUGE_MIN and errno is set to ERANGE.

Portability

A GriefEdit extension.

strtof

int strtof( string str,
[int &endofoffset] )

String to float.

Description

The strtof() primitive converts the initial portion of the string str to a floating point representation; it is an interface to the standard library function of the same name.

Returns

Upon successful completion, strtof() returns the converted value, if any, and (if supplied) an index (base of 1) to the first unprocessed character within the string is stored in the integer object endoffset.

If no conversion could be performed, strtof() returns 0 and errno may be set to EINVAL. The subject sequence contains no characters and index of 0 is stored in endoffset.

If the correct value is outside the range of representable values, strtod() returns FLT_MAX or FLT_MIN and errno is set to ERANGE.

Portability

A GriefEdit extension

strtol

int strtol( string str,
[int &endoffset],
[int base] )

Convert a string into its numeric value.

Description

The strtol() primitive converts the initial portion of the string str to a type integer representation; it is an interface to the standard library function of the same name.

If the value of base is 0 (or if not supplied), the expected form of the subject sequence is that of a decimal constant, octal constant or hexadecimal constant, any of which may be preceded by a ‘+ ‘or ‘- ‘sign. A decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal constant consists of the prefix 0 optionally followed by a sequence of the digits ‘0 ‘to ‘7 ‘only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the decimal digits and letters a (or A) to f (or F) with values 10 to 15 respectively.

If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base, optionally preceded by a + or - sign. The letters from a (or A) to z (or Z) inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and digits, following the sign if present.

The subject sequence is defined as the longest initial subsequence of the input string, starting with the first non-white-space character, that is of the expected form. The subject sequence contains no characters if the input string is empty or consists entirely of white-space characters, or if the first non-white-space character is other than a sign or a permissible letter or digit.

If the subject sequence has the expected form and the value of base is 0, the sequence of characters starting with the first digit is interpreted as an integer constant. If the subject sequence has the expected form and the value of base is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated.

Returns

Upon successful completion, strtol() returns the converted value, if any, and (if supplied) an index (base of 1) to the first unprocessed character within the string is stored in the integer object endoffset.

If no conversion could be performed, strtol() returns 0 and errno may be set to EINVAL. The subject sequence contains no characters and index of 0 is stored in endoffset.

If the correct value is outside the range of representable values, strtol() returns LONG_MAX or LONG_MIN and errno is set to ERANGE.

Portability

A GriefEdit extension.

strverscmp

int strverscmp( string s1,
string s2 )

Version string compare.

Description

strverscmp(3)/versionsort(3) style version comparison function.

Often one has files jan1, jan2, ..., jan9, jan10, ... and it feels wrong when ls orders them jan1, jan10, ..., jan2, ..., jan9. In order to rectify this, GNU introduced the -v option to ls(1), which is implemented using versionsort(3), which again uses strverscmp.

Thus, the task of strverscmp is to compare two strings and find the “right” order, while strcmp only finds the lexicographic order.

Return

The strverscmp() primitive returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be earlier than, equal to, or later than s2.

Portability

A GriefEdit extension.

substr

string substr( string str,
[int offset],
[int length] )

Extract a sub-string.

Description

The substr() primitive extracts parts of a string, beginning at the character at the specified position, and returns the specified number of characters.

The substr() primitive does not change the original string.

Parameters

offset	The position where to start the extraction. First character is at index 1.
length	Optional, the number of characters to extract.

Returns

Returns the sub-string of string which starts at start, and goes on for length characters, or the end of the string if length is omitted.

suspend

void suspend()

Suspend current process.

Description

The suspend() primitive pretends user typed ctrl-z by sending a SIGTSTP to the controlled processing, effectively suspending GriefEdit by placing it in the background.

Note:

This primitive shall only function on systems which support job control, for example unix.

Parameters

none

Returns

nothing

Portability

n/a

swap_anchor

int swap_anchor()

Swaps the mark with the current position.

Description

The swap_anchor() primitive swaps the current cursor position with the start of the marked region, without changing the mark type.

Parameters

none

Returns

Returns true on success, otherwise false.

Portability

n/a

switch

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

expr	Switch value, which can be an integer, float or string expression.

Returns

nothing

Portability

n/a

symlink

int symlink( string path1,
string path2 )

Create a symbolic link.

Description

The symlink() primitive shall create a symbolic link called path2 that contains the string path1.

In other words, path2 is the name of the symbolic link created, path1 is the string contained in the symbolic link.

If the symlink() primitive fails for any reason other than any file named by path2 shall be unaffected.

Returns

Upon successful completion, symlink() shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

syntax_build

void syntax_build( [int timestamp],
[string cache],
[int|string syntable] )

Build a syntax hiliting engine.

Description

The syntax_build() primitive constructs the underlying Deterministic Finite Automata (DFA) from the current set of defined rule via the syntax_rule primitive.

Parameters

timestamp	Optional numeric time reference, utilised to time-stamp the cache (See: time); should be modified upon each change to the DFA scheme.
cache	Optional name of the cache file image.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

nothing

Portability

A GriefEdit extension.

syntax_column_ruler

int syntax_column_ruler( list ruler,
[string attribute],
[int|string syntable] )

Column syntax coloriser.

Description

The syntax_column_ruler() primitive sets the column originated syntax coloriser.

Parameters

ruler	Ruler specification, represented by a set of increasing integer columns plus an optional string containing an attribute name (See: set_color). If a columns trailing attribute is omitted then the default_attr argument is applied. A NULL ruler clears the current ruler.
default_attr	Optional default attribute specification, if omitted “hilite” is assumed.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The syntax_column_ruler() primitive returns the length of the resulting ruler, otherwise -1 on error.

Portability

A GriefEdit extension.

syntax_rule

void syntax_rule( string pattern,
string attribute,
[int|string syntable] )

Define a syntax hilite rule.

Description

The syntax_rule() primitive pushes a Deterministic Finite Automata (DFA) rule into the enhanced highlighting definition for the syntax table specified by syntable.

The rule is described by the regular expression contained within the string rule, and the associated attribute is then applied against any matched constructs.

These rules work alongside the basic syntax elements declared by syntax_token against the same syntax table.

For example, the rules to highlight floating point numbers could be encoding as;

syntax_rule("[0-9]+\\.[0-9]*([Ee][-+]?[0-9]*)?[fFlL]?[iIjJ]?", "float");
syntax_rule("[0-9]+[Ee][-+]?[0-9]*[fFlL]?[iIjJ]?", "float");

Note:

Consult the numerous bundled language mode definitions for working examples.

Parameters

pattern	Rule regular expression.
attribute	Attribute specification.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Attribute Specification

The attribute specification takes the following form. None or comma separated options plus the associated colour attribute (See: set_color).

[<option>[="....."] [, <option> ...] :] <attribute>

Options

word - possible word.
keyword - possible keyword.
tags - possible symbol within tagdb.
directive - possible preprocessor directive.
preproc/pp - enter preprocessor mode.
quick - quick expression evaluation. marks the regular expression for minimal closure, by default evaluation matches against the longest possible rule, quick short-circuits expression execution upon being matched, reducing the greedy nature of DFA regular expressions.
spell - apply spell checks.
todo - apply TODO checks.
markup - apply markup checks.
silent - silent regarding issues, for example non-existent children.
name=<name> - rule name.
group=<grpname> - group name, implied sub-rule.
color=<spec> - color specification, implies the creation of the attribute if it does not exist.
contains=<rule> - contains one or more rules.
contained - is contained within another rule.

Examples

Comment block, with both spelling and TODO token processing enabled.

"spell,todo:comment"

Normal text, yet token may be either a keyword or directive.

"keyword,directive:normal"

Rule Regular Expression

A regular expression is a pattern that the regular expression engine attempts to match in input text. A pattern consists of one or more character literals, operators, or constructs. For a brief introduction, see .NET Framework Regular Expressions.

Each section in this quick reference lists a particular category of characters, operators, and constructs that you can use to define regular expressions:

Character Escapes

The backslash character (\) in a regular expression indicates that the character that follows it either is a special character (as shown in the following table), or should be interpreted literally.

Escape	Description
\t	Tab.
\n	Newline.
\r	Return.
\f	Formfeed.
\a	Alarm (bell, beep, etc).
\e	Escape (\027).
\\	This escapes the meaning of a special.

Character Classes

A character class matches any one of a set of characters. Character classes include the language elements listed in the following table.

Escape	Description
[...]	Matches any one character contained within the character sequence.
.	Match any single character except newline.
\d	Same as [0-9].
\x	Same as [a-fA-f0-9].
\s	Same as [ \\t\\f].
\w	Same as [a-zA-Z_0-9].

Character Sequences

The conversion specification includes all subsequent characters in the format string up to and including the matching right square bracket (]).

The characters between the square brackets (the scanlist) comprise the scanset, unless the character after the left square bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right square bracket.

Within a bracket expression, the name of a character class enclosed in [: and :] stands for the list of all characters (not all collating elements!) belonging to that class.

alnum	An alphanumeric (letter or digit).
alpha	A letter.
blank	A space, tab or form-feed character.
cntrl	A control character.
digit	A decimal digit.
graph	A character with a visible representation.
lower	A lower-case letter.
print	An alphanumeric (same as alnum).
punct	A punctuation character.
space	A character producing white space in displayed text.
upper	An upper-case letter.
word	”word” character (alphanumeric plus “_”).
xdigit	A hexadecimal digit.

Anchors

Anchors, or atomic zero-width assertions, cause a match to succeed or fail depending on the current position in the string, but they do not cause the engine to advance through the string or consume characters. The metacharacters listed in the following table are anchors.

Anchor	Description
^	If this is the first character of the regular expression, it matches the beginning of the line.
$	If this is the last character of the regular expression, it matches the end of the line.
\c	Anchor start of the matched text to the proceeding token.

Quantifiers

A quantifier specifies how many instances of the previous element must be present in the input string for a match to occur.

Anchor	Description
*	Match the preceding character or range of characters 0 or more times.
+	Match the preceding character or range of characters 1 or more times.
?	Match the preceding character or range of characters 0 or 1 times.

Specials

Grouping constructs delineate subexpressions of a regular expression and typically capture substrings of an input string.

Anchor	Description
\|	This symbol is used to indicate where to separate two sub regular expressions for a logical OR operation.
(..)	Group boundaries.
\\Q..\\E	A section enclosed in these symbols it taken literally. In side these sections, meta characters and special symbols have no meaning. If a \\E needs to appear in one of these sections, the \\ must be escaped with \\.

Returns

nothing

Portability

A GriefEdit extension.

syntax_token

void syntax_token( int type,
[<type1> param1],
[<type2> param2],
[int|string syntable] )

Define a syntax token.

Description

The syntax_token() primitive adds and/or modifies a syntax tokeniser element of the table specified by the first parameter table. The actual type and number of parameters vary according to the second parameter type.

Parameters

type	Table attribute.
param1	First parameter.
param2	Optional second parameter.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Table Attributes

The following SYNT table attribute are available;

SYNT_COMMENT	<COMMENT>, <open-string> [, <close>-string>] Comment syntax definition, defining either a block comment or an end-of-line comment. Block comments are specified as token pair, being an <open> and non new-line <close> strings, with end-of-line comments being a single <open> token.
SYNT_CSTYLE	<CSTYLE>, <character>\|<character-set>
SYNT_PREPROCESSOR	<PRE-PROCESSOR>, <character-set>
SYNT_STRING	<STRING>, <character-set>
SYNT_LITERAL	<LITERAL>, <character-set>
SYNT_LINECONT	<LINECONT>, <character>
SYNT_LINEJOIN	<LINEJOIN>, <character>
SYNT_QUOTE	<QUOTE>, <character-set>
SYNT_CHARACTER	<CHARACTER>, <character-set>
SYNT_BRACKET	<BRACKET>, <open> [, <close>]
SYNT_HTML	<HTML>, <open>, <close>
SYNT_TAG	<TAG>, <type>, <word,word...>
SYNT_WORD	<WORD>, <character-set> Defines the character-set which represent a single word.
SYNT_KEYWORD	<KEYWORD>, <character-set> Defines the character-set which represent a single keyword.
SYNT_NUMERIC	<NUMERIC>, <primary-set> [, <secondary-set>]
SYNT_OPERATOR	<OPERATOR>, <character>
SYNT_DELIMITER	<DELIMITER>, <character-set>
SYNT_FORTRAN	<FORTRAN>, <character-set>, <[left-margin], code [,comment-margin]>

Returns

nothing

Portability

A GriefEdit extension.

tabs

int tabs( [string tabs | list tabs | int tab, ...] )

Set buffer tab stops.

Description

The tabs() primitive configures the tabs of the current buffer to the positions specified within tabs.

The primitive supports a number of alternative specification forms being a set of integer parameters, a single string parameter containing space/comma separated numbers or a single list of integers. If omitted the user shall be prompted for each of the tab points, with an empty reply terminating the sequence as follows:

Enter tab stop (return terminates):

Regardless of the form each should be a sequence of columns in ascending order. Tabs for the reminder of the line are set using the difference between the last two tabs stated, starting at the last specified.

Example

The following sets the first tab at four spaces and all sequence tabs to three resulting in the tabs at (5, 8, 11, 14 ...)

tabs(5, 8);

As the tab primitive allows a number of specification forms, all the following are equivalent;

tabs("5 8");
tabs("5,8");
list ttabs = {5, 8};
tabs(ttabs);

Parameters

’tabs’

Optional tabs specification, being the sequence of columns in ascending order otherwise the user is prompted.

Returns

The tabs() primitive returns the number of applied tab points otherwise if the user was prompted and they aborted -1 is returned.

Portability

BRIEF limited the number of unique tab stops at 8, under GriefEdit this limit is 80.

tagdb_close

int tagdb_close( int handle )

Tag database close.

Description

The tagdb_close() primitive closes a tag database handle, so that it no longer refers to any resources and may be reused.

Parameters

handle

Tag database handle.

Returns

nothing

Portability

A GriefEdit extension.

tagdb_open

int tagdb_open( string file,
[int options],
[int background] )

Tag database open.

Description

The tagdb_open() primitive given a pathname for a ctags database, returns a handle being a non-negative integer for use in subsequent database search operations using tagdb_search. The tag database handle shall remain open until <tagtb_close> is executed against the handle.

ctags is a tool which permit easy navigation thru a large set of source files. ctags supports many languages including c, c++ and Java just to name a few.

Note:

GriefEdit relies on an external tag file generator. There are many versions of ctags; however, the recommended version is “Exuberant Ctags” available from

http://ctags.sourceforge.net/.

GriefEdit is generally bundled with a recent version within the bin installation folder as extags. Therefore, you would not need to download/install a tag binary to use this feature.

Parameters

TAG_ETAGS

TAG_CTAGS

file	tag database path.
options	Optional integer flags, being one or more of the following constants OR’ed together forming open options.
background	Optional integer boolean value, if true the database loading shall be moved into the background.

Returns

The tagdb_open() primitive returns the new database descriptor, otherwise -1 if an error occurred.

Portability

A GriefEdit extension.

tagdb_search

int tagdb_search( int handle,
string word,
[int flags] )

Tag database search.

Description

The tagdb_search() primitive searches the tag database for symbols matching pattern.

Note:

Consult the tags macro source for an example.

Parameters

handle	Tag database handle.
pattern	String containing the search pattern.
flags	Optional integer flags.

Returns

The tagdb_search returns a list containing the search results, otherwise a NULL list on error or no match was found.

Portability

A GriefEdit extension.

tan

float tan( float val )

Tangent function.

Description

The tan() primitive computes the tangent of the argument val, measured in radians.

Returns

Upon successful completion, shall return the tangent of val.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

tanh

float tanh( float val )

Hyperbolic tangent function.

Description

The tanh() primitive computes the hyperbolic tangent of the argument val.

Returns

Upon successful completion, shall return the hyperbolic tangent of x.

Portability

Result on error are system dependent; where supported errno shall be set to a non-zero manifest constant describing the error.

throw

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

expr	Exception value.

Returns

nothing

Portability

A GriefEdit extension.

time

int time( [int &hour],
[int &min],
[int &sec],
[int &msec] )

Get the current system time.

Description

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]

Returns

The time() primitive returns the value of time in seconds since the Epoch (1970/1/1).

Example

Displays the current date

int hour, min, sec, msec;

time(hour, min, sec, msec);
message ("time, %d:%d:%d.%d", hour, min, sec, msec);

Portability

The msec parameter is a GriefEdit extension; the BRIEF version returned only hundredths of seconds.

tokenize

list tokenize( string expr,
string delims,
int flags,
[string whitespace = "\t\n\r"] )

Tokenize a string into token elements.

Description

The tokenize() primitive tokenizes the string expr into a list of strings and returns the list in list context.

tokenize() provides greater field processing then the simpler split primitive and should be used by new macros.

Parameters

expr	String to be tokenize.
delims	is a string consisting of one or more characters which indicate the delimiter characters.
flags	is an integer containing a set of flags which indicate how the input string is to be tokenized. Flags consist of one or more the tokenize flags detailed below OR’ed together.
whitespace	Optional set of characters to be treated as whitespace.

Tokenize flags

General

TOK_COLLAPSE_MULTIPLE - Splits the string expr into a list of strings and returns the list in list context. Collapses occurrences of the repeated delimiter characters treating them as single delimiter, in other words empty elements with the delimited text shall not be returned.

Numeric field conversion

TOK_NUMERIC - Fields which begin with a digit are converted into their decimal numeric value and returned as integer element rather than a string.
TOK_NUMERIC_STRTOL - Numeric fields are converted using strtol allowing support leading base specifications hexadecimal (0x), octal (0) and binary (0b).
TOK_NUMERIC_STRICT - Strict conversion of numeric fields where by any invalid values, for example trailing non-numeric characters, result in the the field being returned as a string element and not a integer element.

Parsing options

TOK_WHITESPACE - Allow leading and trailing whitespace around quoted and numeric element.
TOK_BACKSLASHES - Allow backslahes to escape the meaning of any delimiter characters and both single and double.
TOK_ESCAPE - Enable backslash escape sequence processing.
TOK_ESCAPEALL - Control the behaviour of TOK_ESCAPE to escape all characters preceded with a backslashes, otherwise by default unknown escape sequences are ignored.

Quote options

TOK_DOUBLE_QUOTES - Enables double quote support where all characters enclosed within a pair of matching quotes are treated as a single element including any embedded delimiters.
TOK_DOUBLE_QUOTES - Same as TOK_DOUBLE_QUOTES but enables single quote support.
TOK_QUOTE_STRINGS - When single or double quoted support is enabled allow the element is be enclosed within a extra pair of quotes, for example

""hello world""

TOK_PRESERVE_QUOTES - When an element is enclosed in quotes and the quote character is specified in delims then the returned element shall also be enclosed within the encountered quotes.

Field Processing Options

TOK_TRIM_LEADING - Remove any leading whitespace from non-quoted string elements. Whitespace is defined as any space, tab or newline character unless they exist within the set of specified delimiters.
TOK_TRIM_TRAILING - Remove any trailing whitespace from string elements.
TOK_TRIM - Remove any leading and trailing whitespace characters.
TOK_TRIM_QUOTED - Apply trim logic to quoted strings.

Return

The tokensize() primitive returns a list of the words and/or numeric values as encountered within the string str.

Portability

Many of the features are GriefEdit specific; CRiSP ™ has a similar primitive yet as the two were developed independently features differ.

top_of_buffer

int top_of_buffer()

Move cursor to start of current buffer.

Description

The top_of_buffer() primitive moves the buffer cursor to the start of the first line of the current buffer; this is eqivalent to using move_abs as follows.

move_abs(1,1);

Parameters

none

Returns

The top_of_buffer() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

top_of_window

int top_of_window()

Goto top of the current window.

Description

The top_of_window() primitive moves the buffer cursor to the first line of the current window.

Parameters

none

Returns

Returns non-zero if the current cursor position moved, otherwise zero if already positioned at the top of the window.

Portability

n/a

transfer

int transfer( int bufnum,
int sline,
[int scolumn],
int eline,
[int ecolumn] )

Buffer to buffer transfer.

Description

The transfer() primitive moves the specified region from the buffer bufnum into the current buffer.

All characters in the source buffer between the start and end positions inclusive are included in the block.

The primitive has two forms determined by the number of coordinates arguments being either four or two, as followings:

start line/column sline, scol and end line/column eline and ecol.
start line sline and end line eline.

Unlike the original BRIEF implementation, this version is more forgiving and is provided for compatibility; it is usually far easier to use the region macros.

Parameters

bufnum	Buffer identifier of the source.
sline	Starting line.
scolumn	Starting column.
eline	Ending line.
ecolumn	Ending column.

Returns

The transfer() primitive returns non-zero on success, otherwise zero or less on error.

Portability

The short form of transfer is an extension yet less error prone and more convenient interface.

translate

int translate( string pattern,
string replacement,
[int global],
[int re],
[int case],
[int block],
[int forward] )

Buffer search and replace.

Description

The translate() primitive perform string translations within the current buffer. The translate starting at the current cursor position, continuing until the end of the buffer or optionally terminated by the end user.

If either the pattern or replacement is not specified, then the user is prompted for the change.

Unless global is specified, during translate operations the user to informed on the first match and prompted for the desired action.

Change [Yes|No|Global|One|Entire|Abort,Top|Center]?

the actions being

Yes	Replace current match with the pattern and continue searching.
No	Do not replace current match with the pattern and continue searching.
Global	Replace all matches from cursor to end of file.
Entire	Replace all matches in the file.
Abort	Stop the translation.
Top	Moves cursor and the associated text for better visibility to top of page and re-prompts.
Center	Centers the cursor and the associated text for better visibility and re-prompts.

Note:

The translate primitive is provided primary for BRIEF compatibility. As the values of re and case can reference the current global state resulting in possible inconsistent results between usage, it is advised that the state-less re_translate primitive is used by new macros.

Parameters

pattern	String containing the pattern to translate.
replacement	String containing the replacement expression for each matched pattern. It may contain references to the pattern’s capture groups by special variables using one of three forms GRIEF, AWK or Perl, see below.
global	Optional integer flag controls user prompts. If specified as non-zero every occurence of the pattern is replaced, otherwise only the first occurance is translated. If global is omitted the user is prompted on each match.
re	Optional integer value. If re is specified and is zero, then pattern is treated as a literal string not as a regular expression; behaviour being the same as index. Otherwise the string shall be treated as a regular expression using the current global syntax, see re_syntax and search_back for additional information.
case	Optional integer value specifying whether case folding should occur. If case is specified and is zero, then the search is done with case insensitive. If omitted the current global setting is referenced.
block	Optional integer flag. If block is specified and is non-zero, the search operations are limited to the current marked region.
forward	Optional integer flag specifying the search direction. If forward is specified as non-zero or omitted, the translation operation moves forward. Otherwise the translation moves backwards until the top of buffer.

Returns

The translate() primitive returns the number of translations which occurred, otherwise -1 on error.

Portability

n/a

translate_pos

int translate_pos( int x,
int y,
[int &winnum],
[int &line],
[int &col] )

Convert window coordinates.

Description

The translate_pos() primitive translates the physical screen position (x, y) into a window and logical line/col position.

Parameters

x, y	Screen coordinates to be translate.
winnum	Optional an integer variable which shall be populated with the window identifier within which the (x, y) position falls, otherwise -1 if no window was mapped.
line, col	Optional integer variables which shall be populated with the translated window coordinates, otherwise -1 if no window was mapped.

Returns

The translate_pos() primitive returns where the mouse cursor is located.

Value	Definition
MOBJ_NOWHERE	Not in any window.
MOBJ_LEFT_EDGE	Left bar of window.
MOBJ_RIGHT_EDGE	Right bar of window.
MOBJ_TOP_EDGE	Top line of window.
MOBJ_BOTTOM_EDGE	Bottom line of window.
MOBJ_INSIDE	Mouse inside window.
MOBJ_TITLE	On title.
MOBJ_VSCROLL	Vertical scroll area.
MOBJ_VTHUMB	Vertical scroll area.
MOBJ_HSCROLL	Horz scroll area.
MOBJ_HTHUMB	Horz scroll area.
MOBJ_ZOOM	Zoom button,
MOBJ_CLOSE	Close.
MOBJ_SYSMENU	System Menu.

Portability

n/a

trim

string trim( string str,
[string chars = " \\t\\r\\n"] )

Chomp characters from a string.

Description

The trim() primitive removes leading and trailing characters from the specified string.

The default is to remove all tabs, spaces and newline characters. If chars is specified, then all characters within the trimchar string are removed from the beginning and end of the string.

Parameters

str	String object to be trimmed.
chars	Optional string defining the set to characters to be removed.

Returns

Returns a copy of string with all leading and trailing white space characters removed. (spaces, tabs and newlines by default).

Portability

The chars and removal of trailing characters in addition to leading is a GriefEdit extension (See: rtrim).

typeof

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

umask

int umask( int cmask = NULL )

Set and get the file mode creation mask.

Description

The umask() primitive shall set the processes file mode creation mask to cmask and return the previous value of the mask.

Only the file permission bits of cmask are used; the meaning of the other bits is implementation-defined.

The process’ file mode creation mask is used to turn off permission bits in the mode argument supplied during calls to the following functions:

fopen
create_buffer
mkdir

Returns

The file permission bits in the value returned by umask() shall be the previous value of the file mode creation mask.

uname

int uname( [string &sysname],
[string &nodename],
[string &version],
[string &release],
[string &machine] )

Retrieve system information.

Description

The uname() primitive retrieves the strings corresponding to the result of a uname system call. On non-POSIX systems, these strings maybe blank unless there is an equilvent value available.

Parameters

sysname	System name.
nodename	Network node name.
version	Kernel version
release	Kernel release.
machine	Machine type.

Returns

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

Portability

A GriefEdit extension.

undo

int undo( [int move],
[int pastwrite = -1],
[int redo = FALSE] )

Undo previous edit operations.

Description

The undo() primitive undoes buffer modifications on the current buffer.

Executing without arguments undoes the last operation performed on the buffer, including cursor movement, any text modification and marked region modification. If the previous operation on the buffer was a macro, or a complex operation, e.g. global translate, then all the buffer modifications performed are undone in one step.

The move option limits the undo operation to the last buffer modification, restoring the cursor to the its location where the buffer was actually modified.

Each buffer maintains their own undo stack, unless disabled (See: set_buffer_flags). Under BRIEF the undo stack for a particular buffer was cleared when the buffer is written to disk, as such it was not possible to undo any operations performed on the buffer before the last write_buffer.

Under GriefEdit the undo stack is retained for the duration of the editor lifetime. If pastwrite is specified as positive value, the undo shall perform undo’s beyond the last write_buffer; by default the user is prompted as follows

Undo past saved file mark?

Note:

Unlike BRIEF, it is possible to call undo from within a macro, but this use is highly dubious. It is normally called by the user directly from one of the key assignments.

Parameters

move	Optional boolean value, if true then all buffer operations up the last buffer modification are undone.
pastwrite	Option integer stating the write_buffer undo logic. Zero (0) disables undo’s past the last write, a negative value (-1) prompts the user whether to continue otherwise and a postive value (1) permits undo’s without prompt.
redo	Optional boolean value, if true the previous undo action shall be undone.

Returns

The undo() primitive returns the number of operations undo; this is GriefEdit extension.

Portability

n/a

unlink

int unlink( string path )

Unlink a file.

Description

The unlink() primitive is reserved for future use.

The unlink() primitive shall remove a link to a file. If path names a symbolic link, unlink() shall remove the symbolic link named by path and shall not affect any file or directory named by the contents of the symbolic link. Otherwise, unlink() shall remove the link named by the pathname pointed to by path and shall decrement the link count of the file referenced by the link.

When the file’s link count becomes 0 and no process has the file open, the space occupied by the file shall be freed and the file shall no longer be accessible. If one or more processes have the file open when the last link is removed, the link shall be removed before unlink() returns, but the removal of the file contents shall be postponed until all references to the file are closed.

The path argument shall not name a directory unless the process has appropriate privileges and the implementation supports using unlink() on directories.

Returns

Upon successful completion, link shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

unregister_macro

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

type	Event type against which to unregister.
name	Name of the macro to be unregistered.
local	Optional int, Whether the trigger is of local or global scope. Note currently local is only effective on REG_TYPED.

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.

unshift

declare unshift( list lst,
declare value )

Shift the first list element.

Description

The unshift() primitive is reserved for future use.

The unshift() primitive performs the opposite action to that of a shift. It prepends value to the front of the list lst returns the resulting number of elements within the list.

Parameters

lst	List to be modified.
value	Value to be prepended.

Returns

The unshift() primitive returns the resulting number of list elements.

Portability

A GriefEdit extension.

up

int up( [int lines = 1] )

Move position up one line.

Description

The up() primitive moves the cursor up one line to the same column on the previous line.

Parameters

lines

Optional number of lines to move the cursor; may be negative in which case the cursor moves forward behaving like down.

Returns

The up() primitive returns non-zero on success denoting that the cursor moved, otherwise zero if the cursor remained unchanged.

Portability

n/a

upper

string|int upper( string str|int character )

Convert string or character to uppercase.

Description

The upper() primitive converts all alphabetic characters within the string object str or just the specified character ch to uppercase.

Returns

Returns the specified object with all alphabetic characters converted to uppercase.

If the argument is a string then a copy of the string is returned, otherwise the integer value of the converted character.

Portability

Character support is a GriefEdit extension.

use_local_keyboard

int use_local_keyboard( int kbdid )

Associate a keyboard with a buffer.

Description

The use_local_keyboard() primitive cause the current keyboard to be associated with the current buffer.

Parameters

kbdid

Keyboard identifier.

Returns

The use_local_keyboard primitive return 0 on success otherwise -1 on error.

Portability

n/a

use_tab_char

int use_tab_char( [int|string yesno],
[int global = FALSE] )

Configure use of hard/soft tabs.

Description

The use_tab_char() primitive controls whether hard or soft tabs shall be utilised within buffers. When enabled hard/physical tab characters shall be inserted into the buffer otherwise one or more space characters are inserted up-to the next indentation/tab stop.

The effected tabs setting shall either be the current buffer if global is given as FALSE or omitted, otherwise the global configuration setting which is referenced during buffer creation defining the default of subsequent buffers.

The argument yesno states the new tab setting value as either a string or an integer flag. If omitted the user shall be prompted as follows:

Fill with tab chars [yes,no]?

Parameters

yesno	Optional string or integer containing the required status. A string value of yes enables with no disabling. An integer of 1 enables, 0 disables and -1 returns the current with effecting any change.
global	Optional integer flag states the effected resource, if FALSE or omitted then the current buffer otherwise the global buffer default.

Returns

The use_tab_char() primitive returns the previous tab setting of the selected resource, either the current buffer or the global.

Portability

n/a

version

int version( [int major | string machtype],
[int min],
[int edit],
[int release],
[string machtype],
[string compile],
[int cmversion],
[string features],
[string build] )

Version information.

Description

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

Parameters

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.
machtype	Machine type labels, value include “DOS”, “OS/2”, “UNIX” and “VMS”.
release	Reserved for future use.
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.

Returns

The version() primitive returns the current version multiplied by 100, plus the minor; for example 301 represents version 3.1.

Portability

All the arguments are extensions.

vfs_mount

int vfs_mount( string mountpoint,
int flags = 0,
string vfsname,
[string arguments]    )

Mount a virtual file-system.

Description

The vfs_mount() primitive mounts a virtual file-system.

Parameters

mountpoint	String containing the mount point, being the logical path representing the root of the mounted resource.
flags	Integer mount flags.
vfsname	String containing the virtual file-system driver to be applied.
arguments	Optional string arguments to be passed upon the underlying vfs implementation; the format and values required are specific to the virtual file-system driver referenced within vfsname.

Returns

The vfs_mount() primitive returns 0 on success, otherwise -1 on error and errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

vfs_unmount

int vfs_unmount( string mountpoint,
int flags = 0 )

Unmount a virtual file-system.

Description

The vfs_unmount() primitive unmounts the specified virtual file-system referenced by mountpoint.

Parameters

mountpoint	String containing the mount point, being the logical path representing the root of the mounted resource.
flags	Optional integer unmount flags.

Returns

The vfs_unmount() primitive returns 0 on success, otherwise -1 on error and errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

view_screen

int view_screen()

View the content of underlying screen.

Description

The view_screen() primitive restores the original screen image visible prior to Grief’s execution, returning upon a key press.

Parameters

none

Returns

The view_screen() primitive returns zero on success otherwise -1 on error.

Portability

A GriefEdit extension.

wait

int wait( [int &status] )

Wait for attached process to terminate.

Description

The wait() primitive suspends execution until for the process attached to the current buffer terminates, returning status information for the terminated child, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.

This primitive may be aborted by pressing a space.

Parameters

status

Optional integer variable populated with the process status.

Returns

The wait() primitive returns 0 if the process has completed, -2 if the user aborted, otherwise -1 if no process was attached.

Portability

n/a

wait_for

int wait_for( [int timeout],
list|string pattern,
[int flags = 0] )

Wait for process output.

Description

The wait_for() primitive waits for a specific string of characters to be output by the current buffers attached sub-process for up to the specified time timeout.

The character sequence is in the form of regular expression pattern using the search flags flags. The pattern is either a single string expression or a list of string expressions. When a list is given, then a parallel match is performed as each character is read from the buffer.

Parameters

timeout	Optional integer timeout in seconds, if omitted or zero the primitive blocks indefinitely until the sequence is encountered or the sub-process terminates.
pattern	Character sequences to be matched, as either a single string containing a regular expression or a list of string expressions.
flags	Optional integer stating the search flags to be applied (See: re_search).

Returns

The wait_for() primitive returns a non-negative return on a success match, otherwise -1 if there is no process currently attached to the current buffer, or the user interrupted.

On a single string expression wait_for returns 1, otherwise upon a list of string expressions returns the matching index.

Portability

n/a

watch

void watch( string symbol )

Watch a symbol.

Description

The watch() primitive is reserved for future use.

Returns

n/a

Portability

n/a

while

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

widget_get

declare widget_get( [int dialog],
[int name|string name],
[int attr = DLGA_VALUE],
[int index = 0] )

Retrieve a widget attribute.

Description

The widget_get() primitive retrieves the value of a dialog resource.

Parameters

dialog	Optional dialog instance handle, if omitted the current dialog is referenced.
name	Resource identifier or name.
attr	Attribute, if omitted DLGA_VALUE is assumed.
index	Optional integer index, required for attributes with multiple elements.

Returns

The widget_get() primitive returns the assigned value, otherwise NULL on error.

Portability

A GriefEdit extension.

Description

The widget_set() primitive sets the value of a dialog resource.

Parameters

dialog	Optional dialog instance handle, if omitted the current dialog is referenced.
name	Resource identifier or name.
value	Value to assign.
attr	Attribute, if omitted DLGA_VALUE is assumed.
index	Optional integer index, required for attributes with mutliple elements.

Returns

The widget_set() primitive returns the assigned value, otherwise NULL on error.

Portability

A GriefEdit extension.

window_color

int window_color( [int color|string color],
[int winnum] )

Set the window attribute.

Description

The window_color() primitive sets the background of the specified window otherwise if omitted the current window to the stated color.

When borders are disabled, this color shall be used as the background of the associated window allowing one to distinguish between individual views.

Parameters

color	Can be either an integer containing the color numeric value or a string containing the color name. If omitted, the next color within the color index sequenence shall be assigned, see color_index for details.
winnum	Optional window identifier, if omitted the current window shall be referenced.

Returns

Returns non-zero if the color was changed successfully, otherwise zero.

Portability

n/a

write_block

int write_block( [string filename],
[int append = FALSE],
[int keep = FALSE],
[int pause = TRUE] )

Write selected region.

Description

The write_block() primitive writes out the currently marked region to the file filename. If filename is not specified, then it is prompted for as follows

Write marked area as:

The characters included in the mark depend on the its type, and once written the mark is removed unless keep is specified.

Writing out a marked region does not affect the backup flag or the undo information flag; see undo and set_backup.

On completion the following is echoed on the command prompt.

Write successful.

In the event of no active region the following is echoed.

No marked block.

File Name

Several special leading characters within the stated filename act as modifiers on the output mode of the file.

’\|’	data is written to a pipe instead of a file. The string content after the \| is passed as an argument to popen().
’>’, ‘>>’	data shall be appended to the specified file following the >; same effect as stated append.

Parameters

filename	Optional string value containing the path of the destination filename. If omitted the user shall be prompted.
append	Optional boolean value, if true the block is appended to the end of the file; otherwise the file content is replaced.
keep	Optional boolean value, if true the marked region is retainined, otherwise on completion the region is cleared.
pause	Optional boolean value control pipe completion handling. During pipe operations the command may destroy the screen. If omitted or is non-zero then the user is prompted to hit <Enter> before continuing.

Returns

The write_block() primitive returns one on success, otherwise zero on error.

Portability

The filename and append options are GriefEdit extensions to BRIEF.

write_buffer

int write_buffer( [string filename],
[int flags],
[string encoding] )

Write to buffer content.

Description

The write_buffer() primitive writes the content of the current buffer to its associated file.

Parameters

filename	Options string containing the name of the output filename. If omitted then the file is written to the name associated with the current buffer during creation using <<create_buffer>.
flags	Optional integer flags, one or more of the following flags OR’ed together control the functions of the write operation.
encoding	Optional string containing the character encoding to be utilised within the output file.

Flags

Constant	Description
WRITE_APPEND	Append, otherwise overwrite.
WRITE_NOTRIGGER	Do not generate buffer triggers.
WRITE_NOREGION	Ignore any selected region.
WRITE_FORCE	Force write, even if no change.
WRITE_BACKUP	Generate a backup image regardless whether already performed for this edit session.

Returns

Returns greater than zero on success.
Returns zero if file was not saved, eg. because the file has already been saved.
Returns less than zero if an error occurs.

Value	Description
-1	Disk space occurred.
-2	Output file could not be created.
-3	The output file was created with a different temporary name but could not be renamed to the target file due to permission errors.
-4	User aborted the attempt to save the file from one of the callback triggers.
-5	The output buffer does not have a valid filename.
-6	The originally loaded file has changed its permissions, size or status on disk. This option avoids potentially losing work when someone else has written to the file whilst we were editing it.
-7	The file is read-only, either due to file writes having been disabled by the command line switch (-R) or the current file permissions.

In many cases the underlying cause of the error condition can be derived from the system return code (See: errno), for example out of disk space.

Portability

Flags are incompatible with CrispEdit™

write_buffer([string filename], [int and_flags], [or_flags])

Functions

!

!expr

Not operator.

Description

The ! operator yields the logical not of the expression expr.

If the operand has the value zero, then the result value is 1.

If the operand has some other value, then the result is 0.

Parameters

expr	Expression.

Returns

Returns the logical not of the expression expr. expr must evaluate to an integer expression.

!=

expr1 != expr2

Non-equality operator.

Description

The != operator compares for inequality, yielding the value 1 if the relation is true, and 0 if the relation is false. The result type is int.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

Limitations

Lists can not be compared.

%

expr1 % expr2

Modulus operator.

Description

The % operator yields the remainder from the division of the first operand by the second operand. The operands of must have numeric types.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

%=

var %= expr1

Modulus assignment operator.

Description

The %= operator takes the modulus of the first operand var specified by the value of the second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

&

expr1 & expr2

Bitwise AND operator.

Description

The & operator yields the result is the bitwise AND of the two operands expr1 and expr2. That is, the bit in the result is set if and only if each of the corresponding bits in the operands are set.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

&&

expr1 && expr2

Logical AND operator.

Description

The && operator performs a logic AND between the two expressions expr1 and expr2.

Each of the operands must have scalar type. If both of the operands are not equal to zero, then the result is 1. Otherwise, the result is zero. The result type is int.

Short Circuit Evaluation

Logical operators are executed using short-circuit semantics whereby the second argument is only executed or evaluated if the first argument does not suffice to determine the value of the expression:

Logical ADD - If the first operand is zero, then the second operand is not evaluated. Any side effects that would have happened if the second operand had been executed do not happen. Any function calls encountered in the second operand do not take place.
Logical OR - If the first operand is not zero, then the second operand is not evaluated. Any side effects that would have happened if the second operand had been executed do not happen. Any function calls encountered in the second operand shall not take place.

&=

var &= expr1

Bitwise AND assignment operator.

Description

The &= operator obtains the bitwise AND of the first operand var and second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

*

exp1 * expr2

Multiplication operator.

Description

The * operator yields the product of its operands expr1 and expr2. The operands must have numeric types.

Parameters

expr1	Left numeric expression.
expr2	Right numeric expression.

Returns

The accumulator shall be set to the result of the computation.

Notes

If either number is NaN, the result is NaN. Multiplication of Infinity by zero gives a result of NaN, while multiplying Infinity by any non-zero number gives a result of Infinity.

*=

var *= expr1

Multiplication assignment operator.

Description

The *= operator multiplies the value of the first operand var by the value of the second operand expr1; store the result in the object specified by the first operand var.

Parameters

var	Any scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

+

expr1 + expr2

Addition operator.

Description

The + operator yields the sum of its operands resulting from the addition of the first operand with the second.

If ‘expr1 or expr2 is a list, then a new list is returned which is the concatenation of expr1 and expr2.

If expr1 or expr2 is a string, then the other operand is converted to a string, and a string is returned.

If either operand is a floating point number then the other the result is the sum of the two expressions.

Otherwise the integer value of the sum of the two expressions is returned.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

A list value if either operand is a list; a string if either operand is a string; a float if either operand is a float; otherwise an integer value.

++

++expr

Prefix Increment.

Description

The ++ operator increases the operand expr by 1, with the result of the operation returned.

Parameters

expr	An expression.

Returns

The accumulator shall be set to the result of the assignment.

+=

var += expr1

Addition assignment operator.

Description

The += operator adds the value of the second operand to the value of the first operand var, storing the result in the object specified by the first operand var.

Parameters

var	Any scalar type.
expr1	An expression resulting in value of the same type as the scalar type var.

Returns

The accumulator shall be set to the result of the assignment.

-

expr1 - expr2

Subtraction operator.

Description

The - operator yields the difference resulting from the subtraction of the second operand from the first.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

--

--expr

Prefix Decrement.

Description

The -- operator decreases the operand expr by 1, with the result of the operation returned.

Parameters

expr	An expression.

Returns

The accumulator shall be set to the result of the assignment.

-=

var -= expr1

Subtraction.

Description

The -= operator subtracts the value of the second operand expr1 from the value of the first operand var, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

/

expr1 / expr2

Division operator.

Description

The / operator yields the quotient from the division of the first operand by the second operand. The operands must have numeric types.

Parameters

expr1	Left numeric expression.
expr2	Right numeric expression.

Returns

The accumulator shall be set to the result of the computation.

Notes

If number1 is a finite, non-zero number, and number2 is zero, the result of the division is Infinity if the number1 is positive, and -Infinity if negative. If both number1 and number2 are zero, the result is NaN.

/=

var /= expr1

Division assignment operator.

Description

The /= operator divides the value of the first operand var by the value of the second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

<

expr1 < expr2

Less than comparison.

Description

The < operator performs less-then comparisons between the operands expr1 and expr2.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

<<

expr1 << expr2

Left-shift operator.

Description

The << operator shift the value of the first operand expr1 left the number of bits specified by the value of the second operand expr1.

Both operands must have an integral type, and the integral promotions are performed on them. The type of the result is the type of the promoted left operand.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

<<=

var <<= expr1

Left-shift assignment operator.

Description

The <<= operator shift the value of the first operand var left the number of bits specified by the value of the second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

<=

expr1 <= expr2

Less than or equal comparison.

Description

The <= operator performs less-then comparisons between the operands expr1 and expr2.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

<=>

expr1 <=> expr2

Comparison operator.

Description

The <=> operator yields the value -1 if the first expression is less then the second, 0 if the equals, and 1 the greater than; which are arithmetic and lexicographically comparisons respectively.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

Limitations

Lists can not be compared.

=

var = expr1

Assignment operator.

Description

The = operator applies simple assignment, in which the value of the second operand expr1 is stored in the object specified by the first operand var.

Parameters

var	Any scalar type.
expr1	An expression resulting in value of the same type as the scalar type var.

Returns

The accumulator shall be set to the result of the assignment.

==

expr1 == expr2

Equality operator.

Description

The == operator compares for equality, yielding the value 1 if the relation is true, and 0 if the relation is false. The result type is int.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

Limitations

Lists can not be compared.

>

expr1 > expr2

Greater than comparison.

Description

The > operator performs greater-then comparisons between the operands expr1 and expr2.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

>=

expr1 >= expr2

Greater than or equal comparison.

Description

The > operator performs greater-then-or-equal comparisons between the operands expr1 and expr2.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the comparison.

>>

expr1 >> expr2

Right-shift operator.

Description

The >> operator shift the value of the first operand expr1 right the number of bits specified by the value of the second operand expr1.

Both operands must have an integral type, and the integral promotions are performed on them. The type of the result is the type of the promoted left operand.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

>>=

var >>= expr1

Right-shift assignment operator.

Description

The >>= operator shift the value of the first operand var right the number of bits specified by the value of the second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

^

expr1 ^ expr2

Bitwise exclusive OR operator.

Description

The ^ operator yields the result is the bitwise exclusive OR of the two operands.

That is, the bit in the result is set if and only if exactly one of the corresponding bits in the operands are set.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

^=

var ^= expr1

Bitwise exclusive OR assignment operator.

Description

The ^= operator obtains the bitwise exclusive OR of the first operand var and second operand expr1, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

post++

expr++

Postfix Increment.

Description

The post++ operator increments the operand expr by 1, with the original value prior to the operation returned.

In other words, the original value of the operand is used in the expression, and then it is incremented.

Parameters

expr	An expression.

Returns

The accumulator shall be set to orginal value of expr prior to being incremented.

post--

expr--

Postfix Decrement.

Description

The post-- operator decrements the operand expr by 1, with the original value prior to the operation returned.

In other words, the original value of the operand is used in the expression, and then it is decremented.

Parameters

expr	An expression.

Returns

The accumulator shall be set to orginal value of expr prior to being decremented.

|

expr1 | expr2

Bitwise OR operator.

Description

The | operator yields the result is the bitwise inclusive OR of the two operands expr1 and expr2. That is, the bit in the result is set if at least one of the corresponding bits in the operands is set.

Parameters

expr1	Left expression.
expr2	Right expression.

Returns

The accumulator shall be set to the result of the computation.

|=

var |= expr1

Bitwise OR assignment operator.

Description

The |= operator obtains the bitwise inclusive OR of the first operand var and second operand var, storing the result in the object specified by the first operand var.

Parameters

var	A numeric scalar type.
expr1	A numeric expression.

Returns

The accumulator shall be set to the result of the assignment.

||

expr1 || expr2

Logical OR operator.

Description

The || operator performs a logic OR between the two expressions expr1 and expr2.

Each of the operands must have scalar type. If one or both of the operands is not equal to zero, then the result is 1. Otherwise, the result is zero (both operands are zero). The result type is int.

Short Circuit Evaluation

Logical ADD - If the first operand is zero, then the second operand is not evaluated. Any side effects that would have happened if the second operand had been executed do not happen. Any function calls encountered in the second operand do not take place.
Logical OR - If the first operand is not zero, then the second operand is not evaluated. Any side effects that would have happened if the second operand had been executed do not happen. Any function calls encountered in the second operand shall not take place.

~

~expr

Bitwise complement.

Description

The ^ operator yields the bitwise complement 1’s complement or bitwise not operator of expr.

The type of the operand must be an integral type, and integral promotion is performed on the operand. The type of the result is the type of the promoted operand.

Each bit of the result is the complement of the corresponding bit in the operand, effectively turning 0 bits to 1, and 1 bits to 0. The ! symbol is the logical not operator. Its operand must be a scalar type (not a structure, union or array). The result type is int.

If the operand has the value zero, then the result value is 1.

If the operand has some other value, then the result is 0.

Parameters

expr	Expression.

Returns

The accumulator shall be set to the result of the computation.

General Primitives

Macros

__breaksw

Description

Note:

Returns

See Also

__lexicalblock

Description

Note:

Returns

See Also

__regress_op

Description

Returns

Warning:

Portability

See Also

__regress_replacement

Description

Returns

Warning:

Portability

See Also

abort

Description

Parameters

Returns

Portability

See Also

above

Description

Parameters

Returns

Limitations

See Also

above_eq

Description

Parameters

Returns

See Also

abs

Description

Returns

See Also

access

Description

Returns

Portability

See Also

acos

Description

Returns

Portability

See Also

arg_list

Description

Parameters

Returns

Examples

Portability

See Also

asin

Description

Returns

Portability

See Also

assign_to_key

Description

Parameters

Key Sequences

Returns

Portability

See Also

atan

Description

Returns

Portability

See Also

atan2