Here is the proposed README file for KCStack. I'm taking suggestions on the
program name and any comments or questions about anything in this README file,
especially from non-programmers about anything that doesn't make sense to you.
Is there anything I can make clearer?
KCStack - Kicad Command Stack
Some other options for names: KiCommand, KSCommand,
KiCommandStack, KiStack, KiCommandString, KCString
I like that "Command" implies a command interface since most non-programmers
won't know what a stack is, or at least won't identify it with commands.
Clearly I like names that have Command in them.
KCStack allows simple command strings to be executed within pcbnew.
Command strings consist of a variety commands that retrieve, filter, and
process Kicad objects. Commands are very easily added with a simple syntax.
Here are a few short examples:
: SELECTALLPADS PADS SETSELECT ;
- define a new command called SELECTALLPADS that select all pads
MODULES U1 MATCHREFERENCE GETPADS SETSELECT
- select the pads of the module with reference 'U1'
: SELECTMODPADS MODULES SWAP MATCHREFERENCE GETPADS SETSELECT ;
- define a command that select the pads of the module indicated by the argument.
- Use the command like this: U1 SELECTMODPADS
VALUETEXTOBJ DeleteStructure CALL
- Delete all value objects on the modules
VALUETEXTOBJ SELECTED DeleteStructure CALL
- Delete all selected value objects on the modules
KCStack is (will be) an ActionPlugin and is installed similarly to other Action Plugins:
1) Place the kcstack.py and kcstack_gui.py files in
Or the equivalent in MacOS or Linux
(there may be a user-level directory for such files, but I am not aware of it at the moment.)
2) Within KiCad pcbnew, select the Tools > External Plugins > Refresh Plugins
3) The next time you start pcbnew, the KCStack menu item will already be in
the External Plugins menu so there is no need to Refresh Plugins.
KCStack dialog box is shown when the Tools > External Plugins > KCStack menu item is selected.
Self Documented Help
Open the Script Console from the Tools menu. Then type
This will display a short help message, including how to get a list of
commands and how to get more detailed information about each command.
Another useful help commands are:
- r("Help HELPCAT") - short list of help commands
- r("'HELP HELPCOM") - details of commands with HELP in the name.
Note the preceding single quote character.
- r("ALL HELPCAT") - all commands listed by category
- r("HELPALL") - all commands by category with their details in
With KCStack, arguments to commands are enter before the command. Any results
from the command are then used as an argument to the next command. This way,
you can chain together commands in a way that often makes sense. This
programming structure is
called stack-based programming.
KCStack has several advantages over Python Scripting:
- Simplicity in programming and argument type handling make KCStack more
accessible than the equivalent KiCad Python scripting.
- Command strings mean less worrying about variables.
- Command strings are often short and easily sharable.
- Many commands accept a variety of input types, and still work as you would expect.
- Programming structure means you don't have to worry as much about variables.
- KCStack naturally handles lists of objects, so looping over objects is not
needed: it just happens.
- Being able use pcbnew Python object attributes and functions gives
KCStack a lot of access to the Kicad object model.
- Defining new commands is simple.
- With KCStack handling of argument types, there's less worrying about
And several disadvantages:
- Built in commands have flexible argument types, while Python commands
(accessed with CALLARGS) may require careful argument manipulation.
- Most commands are simple and straightforward, while complex commands are
possible. The stack-based structure makes some complex strings difficult to
decipher or create even for experienced programmers.
- While creating entirely new elements from scratch is usually possible,
command strings are sometimes wordy.
- There are currently no looping or conditional commands.
- Full flexibility is only available with Python scripting. Command strings
are a short simple interface for some object manipulation or interrogation.
- (Currently) Strings with spaces cannot be created from scratch.
Introduction to Command Strings and Programming Structure
In KCStack, a Command String contains a sequence of arguments and commands
that are executed sequentially. Arguments occur before the command that uses
them. The arguments are consumed by a command and the results of the command
are stored on top of any previously unused arguments or results, making those
arguments and results available to a future commands.
This is implemented and often imagined as a stack structure.
In this structure, the stack holds values (aka operands) that are used in
Several important characteristics of the stack structure of programming:
- operands are placed on top of the stack when encountered in the
- operands are removed from the top of the stack when commands are encountered in the command string
- operands are placed on top of the stack when returned from executed commands
- results from previous commands, when unused, continue to exist on the stack
and can be used for future commands. In this way, results from past commands
build up to become arguments for future commands.
- return the list of modules
- return the list of selected modules
[MODULES SELECTED CLEARSELECT]
- unselect all selected modules
- select all modules (this seems to have no visual effect)
[MODULES GETPADS SETSELECT]
- select all pads of all modules
[MODULES GETPADS CLEARSELECT]
- unselect all pads of all modules
[MODULES U1 MATCHREFERENCE GETPADS SETSELECT]
- select the pads of the module with reference 'U1'
KCStack follows a general set of conventions:
COMMANDs are in all capital letters.
- To enter an argument that also happens to be a command, use the single quote
mark (') such as in the following string (the brackets are not part of the
string): ['CALLLIST HELP]
- Access to Python functions and attributes are exactly as documented in
Python pcbnew documentation,
which is often in mixed case. Example [MODULES GetCenter CALL]
- Define a new command with the colon, and end with the semicolon.
- : NEWCOMMAND ARG ARG COMMAND ARG COMMAND ;
- Core commands either place objects on the stack or operate on objects on the
stack. The commands that place a list of objects on the stack are in the
category Elements and are listed with the command Elements HELPCAT:
TRACKS - includes vias
- From these core commands, other commands are defined to
retrieve certain objects.
- And in case there is anything missing, you can access the top-level
board and pcbnew objects.
PCBNEW - top level pcbnew Python object
BOARD - top level Board Python object from pcbnew.GetBoard()
- And finally, you can filter each of the above objects to choose exactly the
objects you want, or get at them in slightly different ways.
- PADS SELECTED
- MODULES U1 MATCHREFERENCE GETPADS
- TRACKS VIA FILTERTYPE