LinuxCNC Documentation Wiki: Foreign Wizards

Wizards my be provided as any executable file. The file must be located in the directory containing the wizard and be named wizard.

The wizard will be executed in an environment where it is passed an argument list as if it were a gcode subroutine. Arguments may be normal gcode parameter values, or may be strings contained in quotes. For example, a wizard that generates text to be engraved might be invoked as:

  wizard this_wiz_123 15 200. 300. 'this is text to engrave'

Where: this_wiz_123 is a number associated with this instance of the wizard, 15 is the point size, 200. is the x location, and 300. is the y location.

Like any other wizard, the arguments are in order and the program must match the config file for the wizard.

The standard out for the program will contain the gcode to be executed when the wizard is invoked. This code must contain:

   o<this_wiz_123> sub
   ...
   o<this_wiz_123> endsub

The gcode may have other subroutines embedded within it, and it may set and use local or global parameters, and may use other o-words including o<this_wiz_123> return. If other subroutines are embedded within the file, they should make sure that they have uniq names by beginning with the prefix (this_wiz_123_).

The G-Wiz framework will store the generated subroutine in an appropriate place with the name O_this_wiz_123. This will cause it to be automatically loaded when it is invoked. Within the framework, the wizard line will be shown as:

   o<this_wiz_123> call (15 200. 300. 'this is text to engrave')

Note: Some of this might be a little awkward to use. Suppose you want a ' character within the text to engrave. Or, a left paren. The engrave wizard will have to be smart enough to allow octal or % or hex escapes within the text.

Note: It is necessary to have the line calling the wizard contain the argument list so that when editing the line, the wizard display can be populated with the present value of the parameters. Values can then be changed and the wizard executed again to generate the new subroutine.

Note: The framework will generate the new wizard with an extension of .new. It will then rename the old wizard with an extension of .old. Finally it will rename the .new file to the final name.

Note: The user may invoke the same wizard in multiple places by copying the invocation line. If one of them is changed, that will cause the wizard to be regenerated. We need to do something to cause the changed one to have a new suffix. It is not clear how to assign suffices in such a way that they will be different when we want them to be. Each application should be in its own directory. One effective way might be to hash the argument string and make that part of the file name. (Or, we could just append all of the arguments as part of the name.) -- That would either require a change to the interpreter, or require that the subroutine name include all of the arguments (or the hash).

Standard error for the wizard will be piped to an error handler. Each line on stderr should contain comments enclosed in "()". The contents of stderr will be written into the program prior to the call that invokes the wizard. This permits error notes to be added to the code. For the initial release, those notes will have to be manually deleted. (In the longer run, an error window can be popped up with the error notes.)