Vagrearg Logo  
 

gcmc - G-Code Meta Compiler

Function reference


Vector functions

integer count ( vector:arg )
integer count ( vectorlist:arg )
integer count ( string:arg )
arg vector   Vector coordinates to count.
arg vectorlist   Vectors to count.
arg string   String characters to count.
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.

vector delete ( vector:arg, scalar:idx )
vector delete ( vector:arg, scalar:idx, scalar:cnt )
vectorlist delete ( vectorlist:arg, scalar:idx )
vectorlist delete ( vectorlist:arg, scalar:idx, scalar:cnt )
string delete ( string:arg, scalar:idx )
string delete ( string:arg, scalar:idx, scalar:cnt )
arg vector   Vector coordinates from which to remove coordinates.
arg vectorlist   Vectorlist from which to remove vectors.
arg string   String from which to remove characters.
idx scalar [no unit] Index which entry to remove; valid range [-count(arg)...count(arg)-1].
cnt scalar [no unit] Number of entries to remove and must be ≥0 and defaults to 1 is not specified.
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.

vector insert ( vector:arg, scalar:val, scalar:idx )
vector insert ( vector:arg, vector:val, scalar:idx )
vectorlist insert ( vectorlist:arg, vector:val, scalar:idx )
vectorlist insert ( vectorlist:arg, vectorlist:val, scalar:idx )
string insert ( string:arg, string:val, scalar:idx )
arg vector   Vector to insert coordinate(s) into.
arg vectorlist   Vectorlist to insert vector(s) into.
arg string   String to insert character(s) into.
val scalar Scalar to insert into a vector.
val vector Vector coordinates to insert into a vector, or vector to insert into a vectorlist.
val vectorlist Vectors to insert into a vectorlist.
val string String (characters) to insert into a string.
idx scalar [no unit] Index at which to insert; valid range [-count(arg)-1...count(arg)].
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-1prepend
idx-ninsert
idx=-1append
idx=0prepend
idxn-1insert
idx= nappend
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.

float length ( vector:arg )
arg vector [distance] Vector for length determination.
Returns the length of arg calculated as sqrt(arg * arg).

vector normalize ( vector:arg )
arg vector [distance] Vector for normalization.
Returns the scaled version of arg such that length(normalize(arg)) equals 1.0. The resulting normalized vector has no units associated.

vector reverse ( vector:arg )
vectorlist reverse ( vectorlist:arg )
string reverse ( string:arg )
arg vector Vector to reverse coordinates.
arg vectorlist Vectorlist to reverse vectors.
arg string String to reverse characters.
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..

vector position ( )
vector position ( scalar:naxes )
naxes scalar Maximum number of axis to return. Must be ≥ 1 and less or equal the number of active axes (6 or 9).
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.

vector rotate_xy ( vector:arg, scalar:angle )
vector rotate_xz ( vector:arg, scalar:angle )
vector rotate_yz ( vector:arg, scalar:angle )
vectorlist rotate_xy ( vectorlist:arg, scalar:angle )
vectorlist rotate_xz ( vectorlist:arg, scalar:angle )
vectorlist rotate_yz ( vectorlist:arg, scalar:angle )
arg vector [distance] Vector to rotate.
arg vectorlist [distance] Vectors to rotate.
angle scalar [angular] Angle of rotation. Defaults to radians if no units are associated.
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.

vector scale ( vector:arg, vector:mult )
vectorlist scale ( vectorlist:arg, vector:mult )
arg vector   Vector to scale.
arg vectorlist   Vectors to scale.
mult vector   Multiplication factors.
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.

vector head ( vector:arg, scalar:nr )
vectorlist head ( vectorlist:arg, scalar:nr )
string head ( string:arg, scalar:nr )
arg vector   Vector to take coordinates from.
arg vectorlist   Vectorlist to take vectors from.
arg string   String to take characters from.
nr scalar [no unit] Number of elements to take if positive and number of elements to leave when negative.
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).

vector tail ( vector:arg, scalar:nr )
vectorlist tail ( vectorlist:arg, scalar:nr )
string tail ( string:arg, scalar:nr )
arg vector   Vector to take coordinates from.
arg vectorlist   Vectorlist to take vectors from.
arg string   String to take characters from.
nr scalar [no unit] Number of elements to take if positive and number of elements to leave when negative.
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).

Special functions

integer linecolor ( )
integer linecolor ( scalar:color )
integer linecolor ( string:color )
integer linecolor ( scalar:hue, scalar:saturation, scalar:value )
color integer [none] The color as an integer; usually specified as a hex number in 0xrrggbb.
color string   The color in standard "#rrggbb" format.
hue scalar [angular] The HSV angle in the color circle. Defaults to radians if no units are associated.
saturation scalar [none] The color saturation; valid range [0.0...1.0].
value scalar [none] The color value (intensity); valid range [0.0...1.0].
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.

float lineopacity ( )
float lineopacity ( scalar:level )
level scalar [none] The level of opacity; valid range [0.0...1.0].
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.

float linewidth ( )
float linewidth ( scalar:width )
width scalar [distance] The width of the lines; valid range [0.001mm...1000.0mm].
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.

undef relocate ( )
undef relocate ( vector:offs )
offs vector   Vector coordinates defining the current relative offset.
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.

vectorlist typeset ( string:text, integer:fontid )
text string   The text to typeset in UTF-8 format.
fontid integer [no unit] Reference ID of the font to use (see table below).
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-IDDescription
FONT_HSANS_1Sans-serif single-stroke font
FONT_HSANS_1_RSSans-serif single-stroke font with reduced strokes and pen-up/down
FONT_HSANS_2Sans-serif double-stroke font
FONT_HSCRIPT_1Script single-stroke font (handwriting)
FONT_HSCRIPT_2Script double-stroke font (semi-bold handwriting)
FONT_HTIMESSerif font
FONT_HTIMES_BOLDSerif boldface font
FONT_HTIMES_ITALICSerif italic font
FONT_HTIMES_ITALIC_BOLDSerif 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).

Math functions

scalar abs ( scalar:val )
val scalar   Any number.
Return the absolute value of val. Units are preserved.

float acos ( scalar:val )
val scalar [no unit] A number from -1.0 to 1.0.
Return the arc-cosine of val in radians.

float asin ( scalar:val )
val scalar [no unit] A number from -1.0 to 1.0.
Return the arc-sine of val in radians.

float atan ( scalar:y, scalar:x )
y scalar [distance] Any number.
x scalar [distance] Any number.
Return the arc-tangent of y/x in radians.

float atan_xy ( vector:v )
v vector [distance] Any vector with both X and Y coordinates.
Return the arc-tangent of v.y/v.x in radians.

float atan_xz ( vector:v )
v vector [distance] Any vector with both X and Z coordinates.
Return the arc-tangent of v.z/v.x in radians.

float atan_yz ( vector:v )
v vector [distance] Any vector with both Y and Z coordinates.
Return the arc-tangent of v.z/v.y in radians.

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

float cos ( scalar:angle )
angle scalar [angular] Any number. Defaults to radians if no units are associated.
Return the cosine of angle. The returned value has no units associated.

float exp ( scalar:val )
val scalar   Any number.
Return the exponentiation of val with base e. The returned value has no units associated.

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

float log10 ( scalar:val )
float log2 ( scalar:val )
float loge ( scalar:val )
val scalar   Any number greater than zero.
Return the logarithm of val with base 10, 2 and e respectively. The returned value has no units associated.

float pi ( )
Returns pi (3.141592.....).

float pow ( scalar:x, scalar:y )
x scalar   Any number.
y scalar [no unit] Any number.
Return the x raised to the power y. The returned value has no units associated.

float round ( scalar:val )
val scalar   Any number.
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

float sign ( scalar:val )
val scalar Any number.
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.

float sin ( scalar:angle )
angle scalar [angular] Any number. Defaults to radians if no units are associated.
Return the sine of angle. The returned value has no units associated.

float sqrt ( scalar:val )
val scalar   Any number greater or equal zero.
Return the square root of val. The returned value has no units associated.

float tan ( scalar:angle )
angle scalar [angular] Any number. Defaults to radians if no units are associated.
Return the tangent of angle. The returned value has no units associated.

undef undef ( )
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.

Conversion functions

scalar to_deg ( scalar:arg )
vector to_deg ( vector:arg )
vectorlist to_deg ( vectorlist:arg )
arg scalar [angular] Any number.
arg vector [angular]  
arg vectorlist [angular]  
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

scalar to_distance ( scalar:arg )
vector to_distance ( vector:arg )
vectorlist to_distance ( vectorlist:arg )
arg scalar   Any number.
arg vector    
arg vectorlist    
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.

scalar to_rad ( scalar:arg )
vector to_rad ( vector:arg )
vectorlist to_rad ( vectorlist:arg )
arg scalar [angular] Any number.
arg vector [angular]  
arg vectorlist [angular]  
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

scalar to_in ( scalar:arg )
vector to_in ( vector:arg )
vectorlist to_in ( vectorlist:arg )
scalar to_inch ( scalar:arg )
vector to_inch ( vector:arg )
vectorlist to_inch ( vectorlist:arg )
arg scalar [distance] Any number.
arg vector [distance]  
arg vectorlist [distance]  
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().

scalar to_mm ( scalar:arg )
vector to_mm ( vector:arg )
vectorlist to_mm ( vectorlist:arg )
arg scalar [distance] Any number.
arg vector [distance]  
arg vectorlist [distance]  
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

scalar to_native ( scalar:arg )
vector to_native ( vector:arg )
vectorlist to_native ( vectorlist:arg )
arg scalar   Any number.
arg vector    
arg vectorlist    
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.

scalar to_none ( scalar:arg )
vector to_none ( vector:arg )
vectorlist to_none ( vectorlist:arg )
arg scalar   Any number.
arg vector    
arg 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

string to_string ( arg, ... )
arg any type   Any value.
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.

string to_chr ( integer:arg )
arg integer none Value to convert to Unicode
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.

integer to_val ( string:arg )
arg string   String (character) to convert to Unicode value
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.

float to_float ( scalar:arg )
vector to_float ( vector:arg )
vectorlist to_float ( vectorlist:arg )
float to_float ( string:arg )
arg scalar   Any number.
arg vector    
arg vectorlist    
arg string    
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.

integer to_int ( scalar:arg )
vector to_int ( vector:arg )
vectorlist to_int ( vectorlist:arg )
integer to_int ( string:arg )
integer to_int ( string:arg, integer:base )
arg scalar   Any number.
arg vector    
arg vectorlist    
arg string    
base integer none Conversion base must be zero or [2..36]
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.51
-1.5-1
0.9999999999999991
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.

Output flow functions

undef literal ( ... )
...     Any type of argument
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.

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

undef message ( ... )
undef warning ( ... )
undef error ( ... )
...     Any type of argument
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.

Query functions

integer isfloat ( arg )
integer isint ( arg )
integer isscalar ( arg )
integer isstring ( arg )
integer isundef ( arg )
integer isvector ( arg )
integer isvectorlist ( arg )
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)".

integer isangle ( scalar:arg )
integer isdistance ( scalar:arg )
integer isdeg ( scalar:arg )
integer israd ( scalar:arg )
integer ismm ( scalar:arg )
integer isinch ( scalar:arg )
integer isnone ( scalar: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)".

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

integer isdefined ( string:var )
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.

integer|undef isconst ( string:var )
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.

integer ismodemm ( )
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).

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

Movement functions

vector arc_ccw ( vector:endpoint, scalar:radius )
vector arc_ccw ( vector:endpoint, scalar:radius, scalar:turns )
vector arc_ccw_r ( vector:endpoint, scalar:radius )
vector arc_ccw_r ( vector:endpoint, scalar:radius, scalar:turns )
vector arc_cw ( vector:endpoint, scalar:radius )
vector arc_cw ( vector:endpoint, scalar:radius, scalar:turns )
vector arc_cw_r ( vector:endpoint, scalar:radius )
vector arc_cw_r ( vector:endpoint, scalar:radius, scalar:turns )
endpoint vector [distance] Endpoint coordinate of the arc.
radius scalar [distance] Radius of the arc. Radius must not be zero.
turns scalar [no units] Number of turns to perform. Turns should be integer and must be larger than zero.
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.

undef circle_ccw ( vector:centerpoint )
undef circle_ccw ( vector:centerpoint, scalar:turns )
undef circle_ccw ( scalar:radius, scalar:angle )
undef circle_ccw_r ( vector:centerpoint )
undef circle_ccw_r ( vector:centerpoint, scalar:turns )
undef circle_cw ( vector:centerpoint )
undef circle_cw ( vector:centerpoint, scalar:turns )
undef circle_cw ( scalar:radius, scalar:angle, scalar:turns )
undef circle_cw_r ( vector:centerpoint )
undef circle_cw_r ( vector:centerpoint, scalar:turns )
centerpoint vector [distance] Coordinate of the center of the circle.
radius scalar [distance] Radius of the circle.
angle scalar [angular] Angle of the vector from the current point to the center of the circle. Defaults to radians if no units are associated.
turns scalar [no units] Number of turns to perform. Turns should be integer and must be larger than zero.
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.

undef drill ( vector:drillpoint, scalar:retract, scalar:increment )
undef drill ( vector:drillpoint, scalar:retract, scalar:increment, scalar:repeat )
drillpoint vector [distance] Endpoint of the drill-hole.
retract scalar [distance] Endpoint of the Z-axis after drilling.
increment scalar [distance] Increments of the Z-axis before retracting temporarily.
repeat scalar [no units] Number of repeats of the drill-cycle. Repeats must be larger the zero.
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.

vector goto ( vector:endpoint )
vector goto ( vectorlist:points )
vector goto_r ( vector:endpoint )
vector goto_r ( vectorlist:points )
endpoint vector [distance/anglular] Endpoint of the rapid
points vectorlist [distance/anglular] Points to visit using rapids
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.

integer layer ( )
integer layer ( integer:id )
integer layer ( string:name )
id integer [none] One-based index in the layer stack
name string Name of the layer to activate
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.

Note: Layer names are limited to characters [a-zA-Z0-9_]. Any other characters result in an error.

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

undef layerstack ( string:name1 [, string:name2 [, ...] ] )
name* string Name of the layers
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.

Note: Layer names are limited to characters [a-zA-Z0-9_]. Any other characters result in an error.

vector move ( vector:endpoint )
vector move ( vector:endpoint, scalar:rate )
vector move ( vectorlist:points )
vector move ( vectorlist:points, scalar:rate )
vector move_r ( vector:endpoint )
vector move_r ( vector:endpoint, scalar:rate )
vector move_r ( vectorlist:points )
vector move_r ( vectorlist:points, scalar:rate )
endpoint vector [distance/angular] Endpoint of the feed move
points vectorlist [distance/angular] A list of points to visit
rate scalar [distance] Maximum feed rate override; must be larger than zero.
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.

integer plane ( scalar:mode )
integer plane ( string:mode )
mode scalar [no units] Active cutting plane (see below).
mode string   Active cutting plane (see below). Mode is case-insensitive.
Set the current operational plane to mode or return the current active plane. Argument mode may be one of the following:
 scalar(value)stringDescription
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.

G-code functions

undef coolant ( scalar:state )
undef coolant ( string:state )
state scalar [no units] Coolant state (see below).
state string   Coolant state (see below). State is case-insensitive.
Enable/disable coolant (M7, M8, M9). Argument state must be one of:
 scalar(value)stringDescription
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

undef dwell ( scalar:time )
time scalar [no units] Time to stay at the current position. Time must be larger or equal zero.
Pause (G4) for time seconds.

undef feedmode ( scalar:mode )
undef feedmode ( string:mode )
mode scalar [no units] Feed mode (see below).
mode string   Feed mode (see below). Mode is case-insensitive.
Feed rate mode setting to one of the following:
 scalar(value)stringDescription
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).

undef feedrate ( scalar:rate )
rate scalar [distance] Feed rate; must be larger than zero.
Set feedrate (F) to rate. The rate is interpreted following the setting of the feedmode() function.

undef fixpos_restore ( scalar:g28g30 )
undef fixpos_restore ( scalar:g28g30, vector:rapid )
g28g30 scalar [none] Boolean to indicate which position storage to retrieve
rapid vector Rapid before restoring predefined position
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].

undef fixpos_set ( scalar:g28g30, vector:pos )
g28g30 scalar [none] Boolean to indicate which position storage to retrieve
pos vector Absolute position to set at stored entry
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.

undef fixpos_store ( scalar:g28g30 )
g28g30 scalar [none] Boolean to indicate which position storage to retrieve
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.

undef pathmode ( scalar:exact )
undef pathmode ( scalar:pathtol, scalar:colintol )
exact scalar [none] Boolean to indicate pathmode exact (true) or blend (false)
pathtol scalar [distance] Maximum path tolerance for any given path. Must be ≥0.0
colintol scalar [distance] Co-linearity tolerance to join paths. Must be ≥0.0
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.

undef pause ( )
undef pause ( scalar:optionalstop )
optionalstop scalar [none] Boolean to indicate optional/forced program pause
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.

undef spindle ( scalar:speed )
speed scalar [no units] Spindle speed (see below).
Enable/disable spindle turning and set the spindle's speed, where speed should be:
 scalarDescription
<0spindle counter clockwise (M4)
0spindle off (M5)
>0spindle clockwise (M3)
The spindle speed is set with an S command to abs(speed) before the spindle is enabled.

undef spindlespeed ( scalar:speed )
speed scalar [no units] Spindle speed. Speed must be larger or equal zero.
Set the spindle's speed (S) to speed.

undef toolchange ( scalar:toolnr )
undef toolchange ( scalar:toolnr, scalar:setoffs )
toolnr scalar [no units] Tool number to change to. Toolnr should be integer and must be larger or equal zero.
setoffs scalar [boolean] Set tool offset.
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.

SVG functions

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

DXF functions

No specific DXF functions yet.
 
 
Overengineering @ request