# 10. cschem - forge

{imp10:0} The purpose of the forge plugin is to provide an easy to implement yet generic way for describing attribute transformations in attributes, e.g. in a library symbol.

{imp10:1} The forge plugin works from the array attribute forge, which is taken as an ordered list of atomic steps to execute on attributes. For portability of data, the forge plugin needs to implement exactly the operations described below.

{imp10:2} Each entry of the array is one operation. An operation is split into tokens separated by the separator character, which is a non-alphanumeric character following the operator (first token). For example sub,^dip,DIP,footprint is a valid operation that uses regexp to replace leading "dip" to DIP in the footprint attribute. Since sub is followed by a comma, the token separator is comma.

{imp10:3} Operations work with the current values of attributes at the time of plugin execution during compilation of the abstract model. If destination attribute doesn't exist, it is created.

{imp10:4} If referenced source attribute of an operation does not exist, the operation is silently skipped.

{imp10:5} Operation summary
operations and arguments | in-place | array? | short description
--- | --- | --- | ---
sub,pat,str,attr | yes | map | substitutes one match of regex pattern pat with str in attr
gsub,pat,str,attr | yes | map | substitutes all matches of regex pattern pat with str in attr
suba,pat,ref,attr | yes | map | substitutes one match of regex pattern pat with the value of the ref attribute in attr
gsuba,pat,ref,attr | yes | map | substitutes all matches of regex pattern pat with the value of the ref attribute in attr
delete,attr | yes | atomic | deletes (removes) the attribute
scalar,attr | yes* | atomic | create attr as scalar if it does not exist; throw an error if it exists as an array
array,attr | yes* | atomic | create attr as array if it does not exist; throw an error if it exists as a scalar
copy,dstattr,srcattr | no | atomic | copies the value of srcattr to the destination attribute dstattr (overwriting or creating it)
append,dstattr,srcattr | no | darr | appends the value of the source attribute srcattr to the value of the destination attribute dstattr
prepend,dstattr,srcattr | no | darr | prepends the value of the source attribute srcattr to the value of the destination attribute dstattr

{imp10:6} In-place operations modify existing attributes in place. They are no-op for non-existing attributes.

{imp10:7} If addressed attribute of the operation is an array, the operation will behave according to the "array?" column:

- map: on copy, an array is mapped into an array; on edit-in-place each array element is edited individually
- atomic: if array, the whole array is dealt with at once, as an atomic object; if scalar, result is a scalar too
- darr: if destination is an array, the source (or each element of the source, if it's an array) is combined into the destination array. Fails if source is array and destination is scalar.