On splicing in bocca

• Bocca will only rewrite in impls the bocca protected blocks.
• Bocca will only generate non-protected code at component create.
• Bocca will *always* rewrite the bocca protected blocks (not sometimes) unless told not to.
• When more than one bocca block goes into a single babel block at generation, each must have clear prefix or suffix position in the splicer block and the tag is the tag on the block + :prolog or :epilog.
• No bocca code goes in _misc.
• No unconditional bocca native code goes in _include unless it is to include language standard headers. corollary: boccaSetServices and boccaForceUsePortInclude must appear in sidl.
• Bocca macro code is allowed in _include; the BOCCA_ prefix is always used.
• If the user deletes a bocca protected block entirely, it will not be reinserted-- the user gets what they deserve. If they want it back, they can insert the empty delimiters and then have bocca update all protected blocks by adding and removing a dummy port.

Bocca understands babel splicer blocks and leverages those conventions as much as possible to manage bocca-generated code inside those blocks while never stepping on user-written code. This note is primarily for the users to understand the lengths we go to to preserve their code and for the developers to gain a common understanding of how splicing is handled in the bocca implementation.

Background

• Babel blocks are delimited DO-NOT-DELETE splicer.begin/end(tag).
• Bocca generated blocks are delimited bocca.protected.begin/end(tag).
• User-written blocks in bocca-generated files (only sidl currently) are delimited DO-NOT-DELETE bocca.splicer.begin/end(tag).

To generalize the above delimiters, they consist of a tag in parentheses and a leading key string that is always followed by .begin(tag) or .end(tag). The key string examples here would be "DO-NOT-DELETE splicer", "bocca.protected", and "DO-NOT-DELETE bocca.splicer". Delimited block tags are always well-nested; ill-nested blocks cause splicers to generate errors and cancel any overwrites that would occur in a successful splicing.
Summary: KEY.begin(TAG)/KEY.end(TAG) is the delimiter pair.

Handling SIDL

• Bocca generates SIDL package/class/interface/CCA Port declarations but leaves the methods within them to the user to write. The user puts their interface code in a bocca.splicer block.
• Bocca generates a SIDL CCA component declaration leaving a user block in the sidl but also including some bocca-related methods outside the user block.

Handling Impl files

Bocca must handle a component's impl files when a component is created and any time the bocca-information is changed, such as when a new CCA port is added to update the bocca-generated methods.

Most of the Babel splicer blocks in a Component implementation file are application-related methods that only the component writer knows how to implement. Bocca does not touch these methods at all. Bocca can (and normally does) generate default implementations for methods of the CCA interfaces gov.cca.Component, gov.cca.ComponentRelease, gov.cca.ports.GoPort (at the user's request) and portions of the component's private data. Bocca does not claim ownership of any method normally required by babel or cca specifications; bocca merely provides suggested implementations that the user may edit or discard.

Invoking the splicer to keep users happy

The bocca splicer is almost always be invoked with identical keys for source and target if replacement is intended and distinct keys if insertion is intended. In normal operations (generate a component, update a component for new ports) only the identical keys case is needed.

When the tags match, the source block will be inserted (or appended if insertFirst=True is not passed).
To handle multiple bocca.protected in a single Babel splicer block, simply splice to the same target.

To handle multiple bocca tags inside a single bocca block, note that this requires no reference to a babel splicer key at all. Simply use extended bocca protected keys. In an example suited to setServices


In any operation in which any user code might be replaced, rejectSave=True should be passed and the .rej file generated should be put in the appropriate Trash directory and a warning issued about where old code can be found.
There are no such operations currently.

Algorithms

We distinguish for clarity (not because they are unique) several cases and explain what happens with splicing in each:

• A new component is defined in bocca.

• An existing component is changed, e.g. a uses port is added.

• A bocca component is created based on an existing component implementation.

Special cases of code changes outside bocca.protected splicers:

• (1) An existing port instance is renamed (future feature)

• (2) Babel default exceptions

Splicing for power users

• Users may want to splice or to extract splices from their own files. The splicer in bocca has a powerful python programming interface but is also accessible from the command line in the form of an extractor (bocca-extract) and splicer (bocca-merge). Either command responds to the --help switch with further information. There are many options to fine tune, replicating on the command line most of the functionality available in the programming interface.
• Users are warned against any component maintenance model which uses both bocca and a collection of individual splice files to generate the final components to be compiled. Bocca is not designed for use in such models and sooner or later a splicing conflict will occur and will be fiendishly hard to debug.
• The bocca-merge tool can be used independent of any bocca project to aid the renaming of a component implementation from one package and/or class name into another. Specifically it will migrate blocks from the old impl file into the new impl file generated from sidl where the names have been changed. Previously this kind of rename had to be done by hand or by custom written string substitution scripts.