Bulk edit properties of multiple footprints using regex based tools

I was searching for a method to unhide (i.e. check the Show tickbox) for the reference designator on a stackup layer (${REFERENCE} on the M12 Stackup layer below) for hundreds of parts. In other words I needed a way to bulk edit the visibility of one or more fields.

As recommended by @ paulvdh elsewhere, the recommended approach to these kinds of bulk edits would be to use the PCB Editor / Edit / Edit Text and Graphics Properties shown below:

Although there may be a way to do this specific task via this GUI method, I was after a more general method via some text editing tools like vim/sed/awk/grep/perl.

I saw some other users doing similar things:

  1. Editing one property of multiple footprints - #5 by aaron
  2. How to hide multiple designators on Silkscreen? - #3 by aaron

but this was limited to hiding elements by adding the text hide to certain parts of the file. I was after the opposite (i.e. removing this hide text). It seemed easy enough, but due to the limitations on certain flavors of regex, I was unable to get what I needed using sed. It looks like the best option was to use Perl compatible regular expressions (PCRE). See more here for details as to why I chose this. Essentially sed regex doesn’t have look behind or look ahead functionality so I needed to use a beefier version of regex.

For my specific use case, I settled on this:

perl -i -pe 's|^    \(fp_text user \"\${REFERENCE}\" \([^/)]+\) \([^\)]+\)\K hide||g' robot.kicad_pcb

Note this will modify your file and may break it. Be sure to use git or otherwise backup your files before trying something like this. Don’t use this if you don’t understand what it does.

A breakdown of this is (flag text copied from this stack overflow answer):

  • -p: Places a printing loop around your command so that it acts on each line of standard input.
  • -e: Allows you to provide the program as an argument rather than in a file. You don’t want to have to create a script file for every little Perl one-liner.
  • -i: Modifies your input file in-place.
  • 's|[matching regex]|[replacement text]|g' is perl subtitution syntax. More info here.

Although my syntax was specific to this issue, you can easily find what KiCAD is modifying for a single part, save the file and do a diff (e.g. git diff) to see what exactly changed. You can then use perl to replicate such a change in bulk easily enough.

Note I am writing this up not as a question but a self answered question based on some discussions elsewhere that have now been removed.

KiCad’s PCB has scripting capabilities in Python: PCB Editor / Tools / Scripting Console, and with that you have a pretty powerful interface to reach any part of your PCB from within KiCad itself.

I do want to add I don’t like Python much for various reasons (mainly white space dependency, lack of variable declarations, and lots of “ad-hoc” solutions such as the “main()” contraption), but besides that I’m still dabbling into Python because it has apparently become the defacto standard for scripting interfaces.

Using python lets you name things by their real names instead of the cryptic regular expression syntax, and this also makes your scripts much easier to understand a few years into the future and maintain and modify them.

If you bring programming languages into the toolkit then you can even script arbitrary selection criteria for actions. You could even use a proper S-expression parser. As CS students know regexes, and hence the associated automata, cannot count, so there will be legit input that REs cannot handle. But of course this requires programming, which might be as daunting or more compared to writing REs.

In the end, I think its just what you are used to using and the purpose for which it is being used. I also have MANY complaints about python, but I use it professionally and am pretty proficient, but the documentation on the KiCAD API for accessing everything was REALLY convoluted/outdated/missing. It is way easier to understand the raw text file as it is all organized into a fairly self-explanatory indented hierarchy. I think they did a pretty great job on the file structure for the v6 files (kicad_{sch,pcb,…etc}).

Even after giving up on finding accurate documentation on the KiCAD python API, I just dove into the source code and even then I wasn’t able to do this task after at least an hour of trail/error trying to find the objects that contained what I wanted. On the flip side, with perl (a language I have never used before this btw), I could do it in a matter of minutes. Until the KiCAD python API gets better official documentation and examples, I’ll stick with perl.

Yep, both perl, and python can do both REGEX substitution and more robust parsing/handling, but for adding the word hide to a bunch of lines that match a pattern, REGEX is both sufficient and more efficient. Perl has the advantage in this particular use case as it has a much simpler one-line syntax for this functionality, whereas you’d need to do all sorts of file handling operations with python to get the same thing done.