## Alien file formats: common

This section deals with some common aspects on handling alien (non-native) file formats (load/save, import/export).

### Sheet load postproc: config

The data model of different schematics capture tools differ a lot. Most notably the name and interpretation of attributes vary. A typical example is: geda/gschem uses the refdes attribute to name symbols while sch-rnd uses the name attribute. Loading a gschem sheet (using the io_geda plugin) won't result in a netlistable sheet without renaming all refdes attributes to name attributes.

sch-rnd provides a flexible, configurable sheet postprocessing. When an io_ plugin supports it, it has a list type config node called postproc_sheet_load, which contains pattern-action pairs. The pattern is a valid query script that is ran on the concrete model of the sheet after load. Whenever it yields a matching object, the object is marked and the corresponding action is executed. The action is expected to make the necessary modification on the marked object.

For example above refdes-to-name translation for io_geda is configured in two pairs in config node plugins.io_geda.postproc_sheet_load:

    {(@.a.refdes != "")};                                {propset(@, rename/a/refdes, name)}
    {(@.type == TEXT)  && (@.text == "%../A.refdes%")};  {propset(@, p/text/text, "%../A.name%")}

The first one runs on any object that has a non-empty refdes attribute. It does not have to check for the object being a group (GRP), because only groups have attribute in our model.

If it triggers, the group (typically symbol) has a refdes attribute, the corresponding action, a propset() is ran. The first argument of the propset is @, which defines the scope to be the object marked. Without this scoping, propset would run on all selected objects, which would also work because the code also makes sure only the marked object is selected, however searching for selection is time consuming. Then the propset goes and renames the refdes attribute to name.

The second rule edits the text string of attribute printout floaters. These floaters are dyntext and refer to the attribute by attribute name, which was originally refdes. The query expression matches text objects that have the exact reference text insertedby io_geda for the refdes attribute. The corresponding propset action simply changes the value of the text string to refer to the name attribute.

There is no limit on how many pattern-action pairs can be configured. However, it will take time to run all them after each sheet load from the given format. The pairs are executed in order; the config node is an ordered list, config files can use prepend or append subtrees to modify an existing list without overwriting it.

Whether a given io_ plugin supports sheet postproc or not depends on whehter it has the postproc_sheet_load node defined in its config subtree.

### Sheet load postproc: generic scripting

An alternative to the above configured sheet post processing is using an user script. After the above mechanism ran, the code also calls the an action whose name is the io plugin's name suffixed with _postproc_sheet_load. For example loading a gschem sheet with io_geda, the action name is io_geda_postproc_sheet_load. No error is thrown if the action does not exist.

The action then can be implemented in a plugin or in an user script and go and visit and modify object in any order and with any method it sees fit.

Limitations:

- Only one action per io plugin can be registered, so if there are two scripts providing the io_geda_postproc_sheet_load action, only one will run
- With librnd 4.0.0 there is a limitation that will be fixed later: permascripts are not loaded before the sheet if the sheet is loaded from the command line. This means an user script action postprocessor will work only when the sheet is loaded from the GUI.