## Attribute table editing

### Introduction: mass attribute edits

Sch-rnd offers propedit for mass-editing attributes: select multiple symbols and/or wirenets and invoke the property editor in one of the following ways:

- Select menu, Change selected objects, Edit properties submenu
- press the {s p} hotkey
- invoke the propedit selection action

The property editor dialog that comes up will edit all selected objects at once. Clicking an attribute (on the left side tree) will show all different values (on the right side). Changing the value will change the value of the given attribute on all selected objects.

This is an efficient and practical way to get an overview or unify attributes of selected concrete objects on a single sheet. There are however some limitations:

- this method operates only on the concrete model, never the abstract model
- limited to a per sheet operation, can not edit attributes of objects scattered on different sheets within the project
- can view an change only one attribute at a time; all attribute keys and values can not be displayed in one large table

### Introduction: attribute edit workflow

As an alternative some users prefer to get a tabular view of all attributes of all concrete objects (of a sheet or a whole project) or all abstract objects (of a project). Following the best UNIX traditions, there is no tabular attribute editor built into sch-rnd and there is no tabular attribute editor utility developed specifically for sch-rnd; instead, any external spreadsheet application or table editor can be applied using a simple export-import workflow shown below on Figure 1.

Figure 1. attribute table export-edit-import workflow

The export is a text file, typically in the CSV format, that holds all attributes of all objects in a tabular form with a header row for each table. The external editor is required to save the same file format.

After the import sch-rnd compares all attributes to the current state of the project and makes the necessary modifications. In case of concrete objects these are batched undoable operations per sheet. In case of abstract objects a back annotation is created in a back annotation dialog.

### Manual process

In the manual process the user opens the sheet or project and exports data using an attbl_* exporter. Then the file is open with the external editor software independently of the sch-rnd session. Once editing finished and the file is saved, the user commands sch-rnd to import the files. Sch-rnd can be stopped or kept running while external editing takes place. Both import and export can be done via the command line or GUI.

Figure 2. attribute table export-edit-import workflow

The export step is:

- GUI: file menu, "Export sheet..." or "Export project..."
- GUI: same dialogs invoked via the hotkey {f e} or {f j}
- GUI or CLI: using the Export() action with one of the attbl_* plugins named
- CLI: sch-rnd -x attbl_csv (replace attbl_csv with any other attbl_* plugin name for other formats)

Import can be done:

- GUI: from the File menu, Import, Load attribute table file
- GUI or CLI: using the ImportAttbl action

Figure 2. shows the arguments of a typical attribute table in the exporter dialog.

The model argument of the export plugin defines the scope of the export: concrete writes all symbol and wirenet attributes of the concrete model (drawing) while abstract compiles the project and writes all resulting abstract components and nets. There are variants of these limiting the output to some object types only.

The multi option separates the tables of different object types into different files so the editor needs to deal with only one table per file.

The view argument specifies the name of the view to use for compiling the abstract model (e.g. pcb or sim_ngspice or raw, etc.). If unspecified the default view of the project is used.

### Automated: run external editor flow

When the process is operated from the GUI, the export dialog shown on Figure 2, there is an option provided for a more automated workflow. In the framed section there is a command line template for the external editor to run, with %f substituted for the file name the editor should edit (and save). Click the Run button instead of the Export button to get sch-rnd to:

1. export the selected model into a temporary file
2. execute the editor on the file
3. suspend sch-rnd until the external editor exits
4. import the same temporary file (assuming the external editor has overwritten it with new data)
5. apply the changes

Note: for the automated process the value of outfile is ignored and multi should not be checked.

### How to edit the table

Each table has a header in its first row with the attribute name for each column. Subsequent rows are objects, one object per row. The last column is for the uuid, which is an universal identifier of the object. The uuid header cell also contains extra information for the import code for the abstract model.

Considerations for editing the file (manually or with scripts):

- the uuid column shall never be modified
- the first row of each table must remain the header row
- if the file contains multiple tables there must be an empty row between any two tables
- it is okay to reorder rows within a table as long as the first row (header) remains in place
- it is okay to reorder columns within a table as long as the last row (uuid) remains in place
- it is okay to remove rows (except for the header); a row removal will not remove the given object on import, merely indicates that there will be no attribute change for the object
- it is okay to remove columns (except for uuid); a column removal will not remove any attribute on import, merely indicates the given attribute would not be be changed for any object listed in the table

Attribute editing rules:

- it is possible to change the existing value of an attribute by simply editing the corresponding cell
- editing an attribute to empty string will remove the attribute from the object at import
- creating a new column (with the new attribute key in the header row) will create a new attribute in any object where the cell is not empty
- the table contains only textual attributes, array attributes are exported as empty and are not deleted when the import code sees empty in the file (but overwritten with a string if it sees non-empty cell)
- it is not possible to remove an object using attribute tables

  ### External script

  The attribute table infrastructure can be used to drive external scripts to do automated checks or edits on project attributes without those scripts having to deal with complex data models and file formats. Since CSV is not the most convenient format to parse, there are other formats provided by different attbl_* plugins:

  - attbl_tedax writes simple tEDAx table blocks, ideal for line-by-line processing (e.g. awk, sed, perl)
  - attbl_lht writes the same data in a lihata document which is easy to load with the lihata parser (e.g. from a compiled program)
  - attbl_json writes a JSON file, which is convenient if there is a JSON parser at hand

  The tEDAx file contains table v1 blocks. Each table block features an ordered list of row and col commands. The first row for each table is the header row. Each col holds a single field of textual data.

  The lihata document contains conceptually the same structure; the root is a sch-rnd-attbl-v1 list, with table children. Each table is a list of row nodes and each row is a list of col nodes which are plain text nodes holding cell data. First row of each table acts as a header. A table is essentially a list-of-lists.

  The JSON document starts with a root object with the a single child called "sch-rnd-attbl-v1". This is an array holding tables. Each table is an array of rows. Each row is an array of cells, each cell is a string.

  ### Export scope consideration

  Exporting the concrete model of a single sheet is done by using the GUI "Export sheet" menu ({f e}) or by the command line sch-rnd -x attbl_csv foo.rs; in this case only the symbols/wirenets of the given sheet is exported.

  Exporting the concrete model of a whole project is done by using the GUI "Export project" menu ({f j}) or by the command line sch-rnd -x attbl_csv project.lht (this requires a project file); in this case all symbols/wirenets on all sheets of the project are exported.

  The abstract model normally should be exported on project basis, so "Export project" menu ({f j}) or -x with loading project.lht to make sure all sheets are loaded. If an abstract model export is invoked in sheet export mode or when not all sheets of the project are loaded, the normal partial compilation happens with the associated warning, which means the exported attribute table will contain only as many objects as can be deduced from the sheets currently loaded.