Cobra Inline Programs general functions

NAME

general utility functions

DESCRIPTION

Ten general utility functions, and one keyword, are: 
	assert(expr)
	fcts()
	global (keyword)
	marks(n)
	newtok()
	print ...
	reset()
	restore()
	save()
	set_ranges()
	src_ln()
	unset ...
The function 
	assert(expr)
Can be used to check the truth of an expression, which if false will terminate the program with an error message.

The function 

	fcts()
Can be used to place a mark at the function names in all C (or C++) function definitions.

The keyword 

	global
Normally, data objects do not need to be declared before their first use. If the first use of the object is in global scope, then that object will have global scope and persist throughout the remainder of the program execution, unless it is removed explicitly with an unset command.
Sometimes, though, the first use of the object will be inside a function, which by default would mean that the object disappears when the function terminates. If that is not desired, and the new object is meant to be global, then it can be declared as global at the point of first use. (see also variables and associative). For example 
	global A[];
declares associative array A with global scope when this declaration is encountered for the first time in an execution, also when it appears inside a function.
If now an unset A; statement is executed, anywhere, the array will not be removed but reset to empty, so that it remains a global object.

The function 

	marks(n)
Returns the number of marks in set n, as an integer value. The argument n must be in the range 0..3, with marks(0) referring to the current set of marks. The parameter values 1, 2, and 3 refer to stored sets of marks, as also discussed for the standard query commands save. The stored sets are not directly accessible from within inline programs, other than by calling the predefined save and restore functions.

The function 

	newtok()
The newtok function is useful to create a new placeholder token, without modifying any already existing token in the input stream.
All token attributes can be accessed and modified for the new token. For example: 
	%{
		if (. == Begin)
		{	q = newtok();
			q.lnr = 123;
			q.txt = "foobar";
			...
		}
		...
	%}
An additional example is shown at the description of the set_ranges() function.

The function 

	print args
The print function is used to print text and values on the standard output (which can be redirected with a track query command). The function can take any number of arguments, of any type, each of which is converted to string format before printing. There is no format string, like in C, and only two special symbol sequences are recognized to change the appearance of the output. They are the tab meta-character \t, and the newline character \n.
Even though all arguments to the print statement are interpreted as strings, there is no need to catenate them with + operators: the catenation is automatic. Note that if you print a token value, rather than a token field, the value printed will represent the unique address of that token, as in: 
	%{
		print . "\n";
		Stop;
	%}
	0x600010058
Function 
	reset()
is the equivalent of the query command by the same name. It resets all marks in the current set and all bounds to zero. (The query command resets all marks, but only resets the value of all .bound token attributes to zero if the all is added. The inline function has no parameters and will always assume all.

Functions 

	save(n, s)	# with n:1..3 and s: "", "|", "&", or "^"
	restore(n, s)	# with n:1..3 and s: "", "|", "&", or "^"
provide the equivalents of the query commands save and restore within inline functions.
Both functions expect an integer argument n in the range 1..3. The save command saves the current set of marks into that set, and restore restores marks from set n into the current set.
The second argument s is an optional single character that determines how the save or restore operation is performed. The default, with the second argument set to the empty string "", is to copy the set of marks as is from or to the current set of marks. It can also be one of "|" (union/add), "&" (intersect), "^" (exclusive or), matching the corresponding query commands.

Function 

	set_ranges(from,to)
can be used to (re)define the first and last token in the input stream, which should only rarely be needed.

In combination with the newtok() function, this new function allows us to write Cobra programs that can completely (re)define all or some of the input sequence.
For example 

	%{
		a = newtok(); a.txt = "2";
		b = newtok(); b.txt = "+"; a.typ = "oper";
		c = newtok(); c.txt = "2";
		a.nxt = b;
		b.nxt = c;
		set_ranges(a, c);
		Stop;
	%}
	%{
		print .txt "\n";
	%}
if executed on arbitrary input, will print: 
	2
	+
	2
Note that to be able to execute this program, the input sequence must contain at least one token. The program then starts executing for that token, replaces the input token sequence with its own, and stops. If there is no token at all, the program cannot execute.

Function 

	src_ln(f, n, m)
causes the lines n to m of the source_file named f to be printed on the standard output. Naturally, file f must exist, we must have n <= m and the file should have at least m lines for this function to execute as intended.

The final function unset allows us to delete either and entire array or specific elements of an array: 

	unset A[el]	-- remove associative array element A[el]
	unset A		-- remove variable or array A
This is often useful to do at the start of an inline program, to make sure no data from earlier invocations of the same program persist.
Inline Programs
Manual
Tutorial 		(Last Updated: 3 December 2024)