Writing NCCL programs can save a lot of typing but another interesting feature is that an advanced user can write commands that can be reused in all the scripts. In other words, NCCL is extensible with plugins written in NCCL itself.
In this tutorial we will develop a custom command that will mill a while text file. NCCL doesn't have a dedicated function to do this, but all the stuff to get this job done is already there.
Let's start with a design outline of our custom command :
- We will call it with a name of our choice.
- It will accept three parameters : the name of the file to be milled and the coordinates of the starting point.
In NCCL, every command is seen as a function. The sintax of a function definiton is the following :
In this tutorial we will develop a custom command that will mill a while text file. NCCL doesn't have a dedicated function to do this, but all the stuff to get this job done is already there.
Let's start with a design outline of our custom command :
- We will call it with a name of our choice.
- It will accept three parameters : the name of the file to be milled and the coordinates of the starting point.
In NCCL, every command is seen as a function. The sintax of a function definiton is the following :
Adding custom commands to NCCL
The above example is a function definition. The function name is mill_file. This will be the name we will use to call our custon function in our programs.
The three name fname X Y and Z are are our parameters.
Although the above defnition is correct, it's not useful because between the function and end keywords there is nothing. In other words, our custom function simply does nothing.
To use it, just put it in a file called user.ini and place this file in the same folder where nccl.exe is. In every subsequent call to NCCL.exe, this file will be automatically loaded and one can use our new mill_file command in the same way like nccl native commands. Do it now if you want to try. It's time to add some code to our function :
The three name fname X Y and Z are are our parameters.
Although the above defnition is correct, it's not useful because between the function and end keywords there is nothing. In other words, our custom function simply does nothing.
To use it, just put it in a file called user.ini and place this file in the same folder where nccl.exe is. In every subsequent call to NCCL.exe, this file will be automatically loaded and one can use our new mill_file command in the same way like nccl native commands. Do it now if you want to try. It's time to add some code to our function :
--
-- Function definition
--
function milltext(fname, X,Y,Z)
end
-- Function definition
--
function milltext(fname, X,Y,Z)
end
--
-- Function definition
--
function mill_file(file,x,y,z)
local prev_height = TEXT_HEIGHT -- save current text height
local prev_font = TEXT_FONT -- save current font.
TEXT_HEIGHT = 10 -- set our text height
TEXT_FONT = "C:\\windows\\Fonts\\arial.ttf"
file = io.open(file,"r") -- open file
--
-- loop through all the lines of text
--
for line in file:lines() do
movetool(x,y,0)
milltext(line, 1)
y = y - (TEXT_HEIGHT * 1.8)
end
file:close() -- job done. Close the file
--
-- before exiting our function
-- restore previous values in both text height and fonts
TEXT_HEIGHT = prev_height
TEXT_FONT = prev_fonts
end
-- Function definition
--
function mill_file(file,x,y,z)
local prev_height = TEXT_HEIGHT -- save current text height
local prev_font = TEXT_FONT -- save current font.
TEXT_HEIGHT = 10 -- set our text height
TEXT_FONT = "C:\\windows\\Fonts\\arial.ttf"
file = io.open(file,"r") -- open file
--
-- loop through all the lines of text
--
for line in file:lines() do
movetool(x,y,0)
milltext(line, 1)
y = y - (TEXT_HEIGHT * 1.8)
end
file:close() -- job done. Close the file
--
-- before exiting our function
-- restore previous values in both text height and fonts
TEXT_HEIGHT = prev_height
TEXT_FONT = prev_fonts
end
Our example is simple but pretty complete. The first two lines save the values of a couple of system variables that we are going to use inside our function. Note that the old value is restored just before exiting our function. This way we will leave NCCL environment in the same state it was before the execution of our new command.
Then the function open the file passed ad first parameter. Being just an example of new command, the function simply trust that the first parameter is the name of a text file. A more robust function should check if the file exists taking appropriate actions.
Looping trough a text file is easy in NCCL bacause we use the for instruction. Remember that NCCL is based on Lua and we can use inside NCCL scripts every construct that is legal in Lua.
The loop logic is simple : every line of the text file will be milled using the native NCCL command milltext, and the line starting point is calculated inside the loop. The Y coordinate of the next line is below the current one by an amount of TEXT_HEIGHT multiplied by a distance factor that in our example is 1.8.
Then the file is closed and the two system variable that we used inside our script are restored to their previous value.
If we saved our new function in the user.ini file we can now use our new command inside every script. Be careful to always make a backup copy of your scripts.
To use our new command, type this in a test script :
Then the function open the file passed ad first parameter. Being just an example of new command, the function simply trust that the first parameter is the name of a text file. A more robust function should check if the file exists taking appropriate actions.
Looping trough a text file is easy in NCCL bacause we use the for instruction. Remember that NCCL is based on Lua and we can use inside NCCL scripts every construct that is legal in Lua.
The loop logic is simple : every line of the text file will be milled using the native NCCL command milltext, and the line starting point is calculated inside the loop. The Y coordinate of the next line is below the current one by an amount of TEXT_HEIGHT multiplied by a distance factor that in our example is 1.8.
Then the file is closed and the two system variable that we used inside our script are restored to their previous value.
If we saved our new function in the user.ini file we can now use our new command inside every script. Be careful to always make a backup copy of your scripts.
To use our new command, type this in a test script :
mill_file("user.ini",500,500,0)
post()
The above call will engrave the contents of user.ini file with the first line starting at point X = 500 Y = 500 Z = 0.
This plugin could be further improved before being used in production but the goal of this tutorial was to demonstrate how to extend NCCL.
This plugin could be further improved before being used in production but the goal of this tutorial was to demonstrate how to extend NCCL.