gcmc - G-Code Meta Compiler

Returns number of coordinates or the number of vectors in arg for argument types vector and vectorlist respectively.
Returns the number of bytes occupied by arg if it is of type string. No support is available for multi-byte charactersets to count the number of actual characters in the string.

Returns arg with the entry idx removed from the vector, vectorlist or string. The second form removes cnt entries. Argument idx may be positive to remove at the position counting from the start, or negative to start counting from the end (with -1 being the last entry of the vector/vectorlist/string). Argument cnt must be larger or equal to zero.

Returns arg with value val inserted into the vector/vectorlist/string at position idx. Inserting a scalar val into a vector or vector val into a vectorlist inserts one single entry. Inserting a vector val into a vector or vectorlist val into a vectorlist inserts all of the contained entries from val.
The idx argument specifies the location of insertion with following meaning (with n = count(arg)):

idx	=	-n-1	prepend
idx	≥	-n	insert
idx	=	-1	append
idx	=	0	prepend
idx	≤	n-1	insert
idx	=	n	append

Inserting an empty vector into a vector, an empty vectorlist into a vectorlist or an empty string into a string has no effect and the result is equal arg.

When using huge vectorlists: It should be noted that simple prepending a single vector to a vectorlist or appending a vectorlist to a vectorlist may use a faster alternative formulation. The same is true for strings:

veclst = {...many many vectors...};

veclst = insert(veclst, vec, -1);		// Slower
veclst += {vec};				// Fast append a vector

veclst = insert(veclst, {vec1, vec2}, -1);	// Slower
veclst += {vec1, vec2};				// Fast append multiple vectors at once

vectlst = insert(veclst, vec, 0);		// Slower
veclst >>= 1;					// Make room for prepend
veclst[0] = vec;				// Set prepended value

str = insert("string one", "string two", 0);	// Slow prepend
str = "string two" + "string one";		// Faster

str = insert("string one", "string two", -1);	// Slow append
str = "string one" + "string two";		// Faster

The intrinsic forms are faster because it does not require a copy of the veclst or strings to be created. This also goes for prepending a value to a vector. Appending values to vectors does not have a more efficient intrinsic equivalent, which is in contrast to strings, where the reversal of the arguments in intrinsic form is the most simple and efficient way.

Returns the length of arg calculated as sqrt(arg * arg).

Returns the scaled version of arg such that length(normalize(arg)) equals 1.0. The resulting normalized vector has no units associated.

Returns the reversed version of arg such that all coordinates of a vector, vectors of a vectorlist or characters of a string are reversed. I.e. the first becomes the last, etc..

Returns the current absolute position as a vector. The default number of coordinates returned is 3 (XYZ). The maximum number of coordinates returned is 6 or 9, depending whether 9-axis mode is enabled on the command-line. The optional argument naxes limits the number of axis returned.

Returns arg rotated by angle. The plane of rotation is XY, XZ or YZ for respective functions. If arg is of type vectorlist, then each containing vector is rotated and a vectorlist is returned.

Multiply arg with coefficients from mult. Where mult can be seen as the primary diagonal of a multiplication matrix. If the first argument is of type vectorlist, then each containing vector of arg is iterated and scaled separately.

Returns the first nr number of entries from arg as a vector, vectorlist or string. If arg is a vector and has fewer than nr entries, then the result is padded with undef until the result has nr entries.
If arg is a vectorlist or string and has fewer than nr entries, then only the available entries are returned.
If nr is negative then a vector/vectorlist/string is returned with |nr| fewer entries than count(arg).

Returns the last nr number of entries from arg as a vector, vectorlist or string. If arg is a vector and has fewer than nr entries, then the result is prepended with undef until the result has nr entries.
If arg is a vectorlist or string and has fewer than nr entries, then only the available entries are returned.
If nr is negative then a vector/vectorlist/string is returned with |nr| fewer entries than count(arg).

Set the color of the lines, arcs and circles generated by moves in SVG and DXF. The argument color may be an integer or a string using "#RRGGBB" format. You can also specify the color in the HSV colorspace. The angle is internally normalized using a modulo 360deg calculation and made positive. Calling linecolor() without arguments simply returns the current color. Otherwise it returns the previous color.

Sets the opacity of the lines drawn in SVG and DXF to level, where 1.0 is fully opaque and 0.0 is completely transparent. The current unitless opacity is returned if no argument is given. Otherwise it returns the unitless opacity before the call.

Sets the line width of the lines drawn in SVG and DXF to width. The width is specified as a distance parameter, which allows exact sizes to be created with any distance units. The current line width is returned in distance units if no argument is given. Otherwise it returns the line width in distance units before the call.

Sets a relative offset for any axis on all subsequent output of any path. The relative offset is applied to the coordinates just before they are output. The relative offset is independent of the offset set on the command-line. A program may set both, either or neither relative or global offsets for any coordinate. The generated output uses the sum of the global offset (command-line values) and the currently active relative offset, as set by the offs argument. Any coordinate not specified in the offs argument is set to zero (0.0). Not specifying an argument to the relocate() function zeros the relative offset for all axes.

The relocate() function is especially useful when several identical parts must be cut on one piece, but at different locations. The generating code can be simplified by producing the same path with different relative offsets, set before the call to generate the pattern. Note: proper parametrization of the generating code is better (creating a function with a specific offset argument). The relocate() function is an alternative to achieve a non-parametrized result quickly.

Returns a vectorlist with all strokes to write out text shaped using the font-face as defined by the fontid argument. The vectorlist includes pen-up and pen-down vectors so movement can be separated into engraving and non-engraving.

The fontid should be one of the following:

	Font-ID	Description
•	FONT_HSANS_1	Sans-serif single-stroke font
•	FONT_HSANS_1_RS	Sans-serif single-stroke font with reduced strokes and pen-up/down
•	FONT_HSANS_2	Sans-serif double-stroke font
•	FONT_HSCRIPT_1	Script single-stroke font (handwriting)
•	FONT_HSCRIPT_2	Script double-stroke font (semi-bold handwriting)
•	FONT_HTIMES	Serif font
•	FONT_HTIMES_BOLD	Serif boldface font
•	FONT_HTIMES_ITALIC	Serif italic font
•	FONT_HTIMES_ITALIC_BOLD	Serif italic boldface font

The fonts are derived from the Hershey fonts and linked to a corresponding visualisation in SVG format for all glyphs in the font-faces.

The returned vectorlist is constructed with two inital vectors. The first vector is always a pen-up movement specified as [-, -, 1.0]. The second vector is always a movement to the XY origin [0.0, 0.0, -]. The last two vectors in the vectorlist is the are always a pen-up movement followed by a XY movement to the end-position of the typeset string. The end-position is such that it can be used as an offset for subsequent strings. The setting can be illustrated as:

veclist[0]   = [-, -, 1.0];		/* Pen-up */
veclist[1]   = [0.0, 0.0, -];		/* Left-bottom corner of text */
/* Strokes of the glyphs follow */
veclist[2]   = [x, y, -];		/* Entry point for first stroke */
veclist[3]   = [-, -, 0.0];		/* Pen-down */
... lots of entries up to n-2 ...
veclist[n-1] = [-, -, 1.0];		/* Pen-up */
veclist[n]   = [end_x_pos, 0.0, -];	/* Final position would be start of next glyph */

A pen-down movement is defined as vector [-, -, 0.0]. This implies that the engraving plane is defined at Z-level 0.0 (down).

The font-height is by definition 1.0. All glyphs are scaled such that the upper case character 'X' has the exact height of 1.0. No units are associated with any value in the vectors. The caller may use the scale() function to scale the font to real-world sizes, as well as scaling the engraving plane to any level. Additionally, vector-additions may be used to relocate the typeset text to any position in space.

See also the library function engrave() for engraving the returned vectorlist and the examples in the distribution for outputting the vectorlist. You can alternatively use the path with move() and goto() calls manually (see engrave() source in the distribution for details).

Return the absolute value of val. Units are preserved.

Return the arc-cosine of val in radians.

Return the arc-sine of val in radians.

Return the arc-tangent of y/x in radians.

Return the arc-tangent of v.y/v.x in radians.

Return the arc-tangent of v.z/v.x in radians.

Return the arc-tangent of v.z/v.y in radians.

Return the smallest integral number not smaller than val. Units are preserved. Examples:
ceil(0.5) → 1.0
ceil(-0.5) → 0.0

Return the cosine of angle. The returned value has no units associated.

Return the exponentiation of val with base e. The returned value has no units associated.

Return the largest integral number not greater than val. Units are preserved. Examples:
floor(0.5) → 0.0
floor(-0.5) → -1.0

Return the logarithm of val with base 10, 2 and e respectively. The returned value has no units associated.

Returns pi (3.141592.....).

Return the x raised to the power y. The returned value has no units associated.

Return val rounded with half-way cases rounded away from zero. Units are preserved. Examples:
round(0.7) → 1.0
round(0.5) → 1.0
round(0.4) → 0.0
round(-0.4) → 0.0
round(-0.5) → -1.0
round(-0.7) → -1.0

Returns +1.0 if val is greater or equal 0.0 and -1.0 if val is negative. The returned value has no units associated.

Return the sine of angle. The returned value has no units associated.

Return the square root of val. The returned value has no units associated.

Return the tangent of angle. The returned value has no units associated.

Return an undef value. An undef value may also be written as [-][0] (see also Undef handling), but it is more readable to write it as a function.

Returns arg / pi() * 180.0 (deg) if arg has unit radians, returns arg otherwise. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Conversions:

1	→ 1deg
1mm	→ Warning, 1deg
1in	→ Warning, 1deg
1deg	→ 1deg
1rad	→ 57.29577951deg
undef	→ undef

Returns arg converting any value without distance units to have distance units. The units depend on the command-line setting whether metric or imperial is used according to following rules:
If gcmc is run in metric mode (default):

1	→ 1mm
1mm	→ 1mm
1in	→ 1in
1deg	→ Warning, 1mm
1rad	→ Warning, 1mm
undef	→ undef

If gcmc is run in imperial mode (-i/--imperial option set on command-line):

1	→ 1in
1mm	→ 1mm
1in	→ 1in
1deg	→ Warning, 1in
1rad	→ Warning, 1in
undef	→ undef

Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist.

Returns arg * pi() / 180.0 (rad) if arg has unit degrees, returns arg otherwise. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Conversions:

1	→ 1rad
1mm	→ Warning, 1rad
1in	→ Warning, 1rad
1deg	→ 0.01745329rad
1rad	→ 1rad
undef	→ undef

Returns arg coverted to inch. If arg has no units or already is in inch, then no conversion is performed. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Conversions:

1	→ 1in
1mm	→ 0.03937008in
1in	→ 1in
1deg	→ Warning, 1in
1rad	→ Warning, 1in
undef	→ undef

Function to_in() is an alias for to_inch().

Returns arg coverted to mm. If arg has no units or already is in mm, then no conversion is performed. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Conversions:

1	→ 1mm
1mm	→ 1mm
1in	→ 25.4mm
1deg	→ Warning, 1mm
1rad	→ Warning, 1mm
undef	→ undef

Returns arg converting any value to gcode native representation according to following rules:
If gcmc is run in metric mode (default):

1	→ 1
1mm	→ 1mm
1in	→ 25.4mm
1deg	→ 1deg
1rad	→ 57.2957795131deg
undef	→ undef

If gcmc is run in imperial mode (-i/--imperial option set on command-line):

1	→ 1
1mm	→ 0.0393700787402in
1in	→ 1in
1deg	→ 1deg
1rad	→ 57.2957795131deg
undef	→ undef

Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist.

Returns arg stripping any associated units. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Conversions:

1	→ 1
1mm	→ 1
1in	→ 1
1deg	→ 1
1rad	→ 1
undef	→ undef

Returns arg and any additional arguments converted and concatenated to a string. Scalar values, including those within vectors and vectorlists, have their units appended in the string. Floating point values are printed with the number of decimals as indicated on the command-line.

Returns arg converted to a string with one Unicode character with the value of arg. The argument must be integer and have no units attached or a warning wil be emitted. An additional warning is emitted in pedantic mode if arg is zero.

Returns the first Unicode character of arg converted to an integer value without units. Any additional characters in the argument are ignored. Zero is returned if the string is empty.

Convert arg to floating point. Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Undef is returned as undef and units are preserved.

Strings are converted into floating point numbers with optional units (mm, in, mil, rad, deg). A string that cannot be converted returns 0.0 and emits a warning. Both conversions to NaN (not a number) and Inf (infinity) result in a warning. The special string "<undef>" will result in an undef value.

Convert arg to integer. Floating point numbers are converted by truncation. However, values are subject to EPSILON calculation. Any floating point value within EPSILON of an integer value will be rounded to that value. Examples:

1.5	→	1
-1.5	→	-1
0.999999999999999	→	1

Vectors and vectorlists are iterated over all scalars contained in them and return vector or vectorlist. Undef is returned as undef and units are preserved.

String are converted to integer with optional units (mm, in, mil, rad, deg). A string that cannot be converted returns 0 and emits a warning. The integer number may be of octal, decimal or hexadecimal base using usual patterns.
Integer numbers for base zero can be described by the following regex:

Octal	[+-]?0[0-7]*(mm|in|mil|rad|deg)?
Decimal	[+-]1[0-9]*(mm|in|mil|rad|deg)?
Hexadecimal	[+-]?0[xX][0-9a-fA-F]*(mm|in|mil|rad|deg)?
undef	<undef>

The optional base argument may be used to specify a specific conversion base for the number. This may or may not play nice with attached units. The same problem exists for hexadecimal conversions and deg units.

Note 1: The variable base means that values with a leading zero are interpreted as octal numbers.
Note 2: Using 'mil' as unit may lead to loss of digits because the value is automatically converted to inch and remains integer. A warning is emitted if this happens. If you want the specific conversion, then you should use to_int(to_float(milvalue)) instead, which will perform the same function without the warning.

Outputs all arguments as text into the output. Note that the literal() function does not terminate the line with a newline and you must provide the newline as a string argument if the line must be terminated. The SVG and DXF backends ignore this function.

Do not use the literal() function lightly. It is extremely powerful but also very dangerous. It will make your source a lot more unreadable and may introduce side-effects that you did not intend.

If you simply want to embed a comment or a G-code debug statement, you should be using the comment() function instead because it is much safer to use.

Outputs all arguments as a G-code comment into the output. The comment() function will prepend a '(' and append a ')' including newline automatically.

Outputs all arguments as text to the console. Origin file and line number is prepended and a newline is appended if none in the last argument. The gcmc executable will return non-zero if error() is executed.

These functions return an integer (boolean) which is true (1) if arg is of tested type and false (0) otherwise.
Function isscalar(arg) equals "isint(arg) || isfloat(arg)".

These functions return an integer (boolean) which is true (1) if arg has the tested units and false (0) otherwise.
Function isangle(arg) equals "israd(arg) || isdeg(arg)".
Function isdistance(arg) equals "ismm(arg) || isinch(arg)".

These function return an integer (boolean) which is true (1) is the current output format is set as queried and false (0) otherwise.

Returns an integer (boolean) which is true (1) if a variable with name var is currently defined in either local or global scope and false (0) otherwise.

Returns an integer (boolean) which is true (1) if a variable with name var is constant and false (0) otherwise. The return value is undef if the variable is not defined in local or global scope.

Returns an integer (boolean) which is true (1) if gcmc is run in millimeter mode and false (0) if run in inch mode (option -i/--imperial).

Returns an integer (boolean) which is true (1) if the output is set to relative mode (-r option) and false (0) otherwise.

Perform a counter clockwise (ccw) or clockwise (cw) arc from the current position to endpoint with radius radius. The arc will be shortest angular movement with positive radius and largest angular movement with negative radius. Optional turns sets the number of turns to perform. Functions arc_ccw_r() and arc_cw_r() use relative addressing. The argument endpoint returned.

Perform a clockwise (cw) or counter clockwise (ccw) circle with radius length(centerpoint) for the circle_cw_r and circle_ccw_r functions and radius length(centerpoint-position()) for the circle_cw and circle_ccw functions and where centerpoint is the center point or the circle. Optional turns sets the number of turns to perform. The specified centerpoint is a relative position for the circle_cw_r and circle_ccw_r functions and an absolute coordinate for circle_cw and circle_ccw. The non-active plane coordinate may be used to create a helical movement.

The scalar form performs a clockwise (cw) or counter clockwise (ccw) circle with radius radius. The center point is located at a vector calculated from the current position of length radius and angled at angle. Optional turns sets the number of turns to perform. The circle is always performed within the active plane.

Perform a drill-cycle to drillpoint with retract denoting the retract (Z) position after the cycle, increment the Z-axis increments and optional repeat repeats.

Rapid move (G0) to position endpoint, or all position in vectorlist points. The endpoint/points position is an absolute position for goto() and a relative position for goto_r().
The endpoint vector and each vector in vectorlist points may consist of up to nine coordinates and are interpreted for axis XYZABCUVW respectively. Coordinates for axes XYZ and UVW are interpreted with distance units and axes ABC are interpreted with angular units. The absolute position before the movement is returned.

Set the active layer on which to output feed moves from the move(), move_r(), arc_*(), circle_*() and all other feed-move producing functions.

The id argument is an index in the set of layers defined by the layerstack() call. The index is one-based. Alternatively, the active layer can be set by specifying the name of the layer using the name argument. The name must have the same spelling as used in the layerstack() call or a warning will be issued.

Layers are transparent to the G-Code backend and are simply ignored. All rapid and feed movement is output regardless of the active layer. Currently, only SVG and DXF backends make use of the layer settings.


The function returns the currently active layer if called without arguments. The other two forms with one argument will return the previously active layer (before the call).

Example:

square = {[-1,-1], [-1,1], [1,1], [1,-1]};

/* Declare and set the order of the layers */
layerstack("layer1", "layer2", "layer3");

layer(2);		/* Set the active layer */
goto(square[-1] * 20.0mm);
move(square * 20.0mm);

layer(3);
goto(square[-1] * 30.0mm);
move(square * 30.0mm);

layer("layer1");	/* Can also be set by name */
goto(square[-1] * 10.0mm);
move(square * 10.0mm);

Declare the stack of layers to be used in DXF and SVG output. Each name argument is entered in the stack in the order in which they are specified. The output routine will output the layers in that order.

The layerstack() function automatically activates the first layer in the argument list after the call. A call to layer() must be used to change the active layer.

Feed move (G1) to position endpoint, or all position in vectorlist points. The endpoint/points position is an absolute position for move() and a relative position for move_r(). The optional rate argument sets the feed override (F-parameter) for this move and is interpreted in the context of the feedmode() setting.
The endpoint vector and each vector in vectorlist points may consist of up to nine coordinates and are interpreted for axis XYZABCUVW respectively. Coordinates for axes XYZ and UVW are interpreted with distance units and axes ABC are interpreted with angular units. The absolute position before the movement is returned.

Set the current operational plane to mode or return the current active plane. Argument mode may be one of the following:

	scalar	(value)	string	Description
•	PLANE_QUERY	(undef)		return current plane as integer
•	PLANE_XY	(0)	"XY"	set XY plane and return previous value (G17, default set in prologue)
•	PLANE_XZ	(1)	"XZ"	set XZ plane and return previous value (G18)
•	PLANE_YZ	(2)	"YZ"	set YZ plane and return previous value (G19)

The previously active plane is returned if the plane is set. The current plane of operation is returned as an integer if mode is undef.

Enable/disable coolant (M7, M8, M9). Argument state must be one of:

	scalar	(value)	string	Description
•	COOLANT_OFF	(0)	"off"	coolant off
•	COOLANT_MIST	(1)	"mist"	coolant mist
•	COOLANT_FLOOD	(2)	"flood"	coolant flood
•	COOLANT_ALL	(3)	"mist+flood"	coolant mist+flood

Pause (G4) for time seconds.

Feed rate mode setting to one of the following:

	scalar	(value)	string	Description
•	FEEDMODE_INVERSE	(0)	"inverse"	Inverse Time Mode (G93)
•	FEEDMODE_UPM	(1)	"upm"	Units Per Minute (G94) (default)
•	FEEDMODE_UPR	(2)	"upr"	Units Per Revolution (G95)

The time based units interpretation depend on the command-line setting whether metric (mm/s) or imperial (in/s).

Set feedrate (F) to rate. The rate is interpreted following the setting of the feedmode() function.

Sets the lathe X-axis mode of operation to radius (G8) or diameter (G7) according to following arguments:

	scalar	(value)	string	Description
•	LATHEMODE_RADIUS	(0)	"radius"	Move X-axis full distance, making the final part diameter double the indicated X-move (G8) (default)
•	LATHEMODE_DIAMETER	(1)	"diameter"	Move X-axis at 1/2 distance, making the final part diameter as indicated by the X-move. (G7)

Emit a G28 or G30 gcode (goto predefined position). If g28g30 evaluates to false then G28 is used, otherwise G30. The argument rapid defines a rapid move in absolute coordinates to perform before the rapid move to the indicated stored position is performed.
A warning is emitted if the position was never stored using fixpos_store or set using fixpos_set before restored and gcmc's internally tracked position is set to [0, 0, 0, 0, 0, 0, 0, 0, 0].

Set the position pos for use in use in G28 and G30. If g28g30 evaluates to false then G28's position is set, otherwise G30's position is set.
This function is an administrative function to allow fixpos_restore() to be called without emitting a warning. The G28/G30 positions are often machine dependent variables and gcmc has no means of knowing them unless set explicitly.

Emit a G28.1 or G30.1 gcode (store current absolute position). If g28g30 evaluates to false then G28.1 is used, otherwise G30.1.

The single argument form emits a G61 (exact path mode) gcode when exact is true and a G64 gcode (best possible speed) when exact is false.

The dual argument form emits a G64 with path tolerance (P-parameter) set to pathtol and the co-linearity tolerance (Q-parameter) to colintol. If you only intent to use/set the path tolerance, then you should set colintol to <undef> to suppress the Q-parameter or set both pathtol and colintol to the same value.

Emit an M0 gcode (forced pause) if optionalstop evaluates to false or is not specified. Otherwise, emit an M1 gcode (optional pause) if optionalstop evaluates to true.

Enable/disable spindle turning and set the spindle's speed, where speed should be:

	scalar	Description
•	<0	spindle counter clockwise (M4)
•	0	spindle off (M5)
•	>0	spindle clockwise (M3)

The spindle speed is set with an S command to abs(speed) before the spindle is enabled.

Set the spindle's speed (S) to speed.

Change tool (T) to toolnr. An M6 code is also emitted to perform the actual tool change. If setoffs evaluates to true, then a G43 code is also emitted to set the tool's offset.

Emits a close-path SVG command (Z) to the path being output, such that the current shape becomes closed.