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.
- One
inparameter, typed by theElementmetaclass, with multiplicity1..1or1..*. Name itselection. - One ActivityParameterNode standing for that parameter, on the diagram.
- 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 forSet tag.tag, the template itself forCopy.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 nodeAn 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:
| Action | Its input pins | Fed by |
|---|---|---|
Ask text | title, question | value pins carrying strings |
Copy | source | a value pin naming the template |
owner | an object flow from the selection parameter node | |
Replace in names | elements | an object flow from Copy.copy |
placeholder | a value pin carrying the placeholder text | |
replacement | an object flow from Ask text.text | |
Diagrams of | elements | an object flow from Copy.copy |
recursive | a value pin carrying true | |
Open diagrams | diagrams | an 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.
- Draw a decision node and give it a
decisionInputFlow— an object flow from the output pin whose value it reads. - Draw two or more outgoing control flows, each carrying a literal guard. A
LiteralBoolean,LiteralString,LiteralIntegeror an element value all work. - 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 rule | What it wants |
|---|---|
| A macro has one initial node | Exactly one initial node |
| A macro declares its selection | One in parameter typed Element at 1..1 or 1..*, and one parameter node standing for it |
| A macro uses supported nodes | Every node interpretable, and every action calling an OpaqueBehavior |
| A pin is fed once | Each 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 value | One decision input flow, literal guards, at most one else |
| Control flow is acyclic and complete | No 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.
Related pages
- 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.mdin 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