Anvil
How-to guides

Anvil: write a macro

A macro is an Activity you draw in the model, and Anvil interprets it when a modeller picks it from a shortcut menu. This page builds one that copies a template under the selected package, renames its placeholders and opens its diagram. Nothing here is code: the whole macro is drawn, and the steps it calls ship with Anvil.

Draw the Activity

Create an Activity, apply «Macro» to it, and give it the three things every macro carries.

  1. One in parameter, typed by the Element metaclass, with multiplicity 1..1 or 1..*. Name it selection.
  2. One ActivityParameterNode standing for that parameter, on the diagram.
  3. An initial node and a final node.

The parameter is the launch contract. Anvil binds the modeller's selection to it and enables the menu item only when the selection size fits, so 1..1 gives an item that runs on one element and 1..* one that runs on many. A macro declares no other parameter, because the shortcut menu has nothing else to bind.

Drop the steps

Drag a step out of the containment tree onto the diagram. Anvil_Macros_Steps holds seventeen of them, grouped into Copying, Model, Diagrams, Dialogs and Feedback; the step catalogue states what each one does and what it takes.

The tool creates one pin per in parameter of the step. Anvil then converts the pins of parameters marked «ValueParameter» into value pins and gives each an empty value of the right kind, so a parameter that takes text arrives carrying an empty string and one that takes an element arrives carrying an empty element value. Two gestures follow from that:

  • For text, a number or a switch, open the pin's specification and type into the Value cell.
  • For an element, open the Value cell and pick the element — a stereotype for Apply stereotype.stereotype, a tag definition for Set tag.tag, the template itself for Copy.source.

Type into a value cell that carries nothing and the tool writes an OpaqueExpression instead of a literal, which no macro can read. The empty value Anvil creates is what keeps you out of that: the cell already holds a string, so typing edits the string.

The catalogue's Fed by column says which parameters work this way. Every other parameter is fed by an object flow.

Wire the flows

Two kinds of edge do two different jobs, and confusing them is the one mistake that stops a macro that otherwise looks finished.

A control flow sequences the actions. Every step action needs exactly one incoming control flow and exactly one outgoing control flow, from the initial node through to the final node. A macro missing one reports

Step Action "rename" has 0 outgoing control flows; it needs exactly one
Step Action "open" cannot be reached from the initial node

An object flow carries a value. It runs from the parameter node, or from an earlier action's output pin, to the input pin that reads it. An object flow sequences nothing, so a chain of object flows with no control flow between the actions is a macro that never runs.

The reference macro reads as one control-flow line with object flows crossing it:

ActionIts input pinsFed by
Ask texttitle, questionvalue pins carrying strings
Copysourcea value pin naming the template
owneran object flow from the selection parameter node
Replace in nameselementsan object flow from Copy.copy
placeholdera value pin carrying the placeholder text
replacementan object flow from Ask text.text
Diagrams ofelementsan object flow from Copy.copy
recursivea value pin carrying true
Open diagramsdiagramsan object flow from Diagrams of.diagrams

Copy.copy feeds two consumers. Anvil copies a value to every outgoing object flow rather than consuming it, so a fan-out needs no fork node.

Leave an optional parameter empty

A parameter whose lower bound is zero may keep the pin the tool drew and carry nothing. The step reads the position as absent: as nothing where the parameter takes one value, and as an empty list where it takes many. Ask text.initial left empty opens a dialog with an empty field, and Ask elements.types left empty offers every element.

A required parameter is different. A pin nothing feeds, on a parameter whose lower bound is one, stops the macro from compiling.

Branch on a decision

A decision reads one value and takes the branch whose guard matches it.

  1. Draw a decision node and give it a decisionInputFlow — an object flow from the output pin whose value it reads.
  2. Draw two or more outgoing control flows, each carrying a literal guard. A LiteralBoolean, LiteralString, LiteralInteger or an element value all work.
  3. Mark at most one flow else.

Confirm and Has stereotype are the two steps written for this: each returns a Boolean, so a decision reading one takes the true branch or the false branch. Bring the branches back together at a merge node, and remember that a value consumed after the merge must be produced on every path that reaches it.

Fail ends a run deliberately, which is how a macro stops after a decision that found the work already done.

Run it

A macro is reachable once a «Menu» carries it and the project names a menu root, which Anvil: put an automation in a menu covers. The whole run is one session, so one undo entry takes the model back to where the run started, and a failure or a cancelled dialog rolls it back for you.

When the item will not run

A menu entry whose macro does not compile is shown and disabled, and its tooltip lists every problem, each naming the element it found. Read the tooltip before reading the model: the message names the pin or the action, not just the macro.

Six rules decide whether a macro compiles.

The ruleWhat it wants
A macro has one initial nodeExactly one initial node
A macro declares its selectionOne in parameter typed Element at 1..1 or 1..*, and one parameter node standing for it
A macro uses supported nodesEvery node interpretable, and every action calling an OpaqueBehavior
A pin is fed onceEach pin fed once, by a flow or by its own value; every required parameter fed; no two pins on one parameter
A decision reads a valueOne decision input flow, literal guards, at most one else
Control flow is acyclic and completeNo cycle, every node reachable, every value produced on every path to its consumer

A macro that compiles can still fail while it runs, when the model refuses what a step asks — a read-only element, an owner that may not own what a step moves. The run then rolls back and an error balloon names the item, the action and the cause.

  • The macro steps — every step, its parameters, and whether each takes a value pin or a flow
  • Anvil: put an automation in a menu — making the macro reachable, and the project option that names the menu root
  • contributing/add-a-step.md in the repository — writing a step of your own when the catalogue holds none that fits
  • How macros run — why a macro is compiled before it is walked, and what one run commits

On this page