Anvil
How-to guides

Anvil: render model values

toString on a model element answers with an implementation class and a hash, which identifies nothing a reader can act on. The format package renders any value — model element or not — as text that names what the element is, what it is called, what is applied to it, and enough identity to tell two elements apart.

The package holds plain extension functions and no state. They read as well in an exception message, a validation result or a dialog as they do in a log line, and they depend on nothing else in Anvil.

Render a value with fString

import com.mbseconsulting.anvil.format.IdStyle
import com.mbseconsulting.anvil.format.fString

log.info { "applied to ${element.fString()}" }
Class "Concept A" «Concept» (_2026x_1_328c0658_1786288981600_428316_3213)

An element renders as its metaclass, its name, its applied stereotypes and its identifier. The metaclass comes from the implemented interface — Property, Class, Association — rather than from humanType, which answers with the stereotype's name once one is applied and reads as Attribute (unnamed) «Attribute». Each field degrades on its own: an unnamed element renders as (unnamed), and an element carrying no stereotype renders without the guillemets.

fString accepts any receiver, including null, so a value whose type is not known at the call site renders through the same call:

ReceiverRenders as
nullnull
A String"quoted"
A Collection[a, b, c], each entry rendered; an empty collection renders as []
A Map{k=v}, keys and values rendered
A BaseElementClass "Concept A" «Concept» (…428316_3213)
Anything elseIts own toString

Choose how much identity to print

A CATIA Magic identifier runs to about forty-five characters, and most of it repeats across every element of a session.

IdStylePrintsUse when
FULL (default)The whole identifierThe line will be searched against a model export
SHORTThe last two segments, as …428316_3213The line is read by eye, or thousands are
NONENothingThe name alone identifies the element
log.debug { "candidates: ${candidates.fString(IdStyle.SHORT)}" }

The event tracer renders at SHORT for that reason, and a rule's conditions render at NONE, because the trace line already names the element the condition belongs to.

A fString(includeId: Boolean) overload ships for call sites written against the original two-value flag, where true means FULL and false means NONE. New code names the IdStyle.

Rely on the guard

Every read inside fString is guarded. A value reaching a log line is often an element a transaction has just changed or deleted, and such an element answers its accessors by throwing from the JMI layer, with an exception type that varies by accessor — which is why code guarding a read of this kind catches RuntimeException broadly rather than a narrower type. The rendering degrades field by field instead, so a renderer used to build a message can never fail its caller.

That guarantee is what makes the same function usable inside a catch block, inside a commit listener, and inside a validation rule that reports on an element it has just found invalid.

The Message Window renders HTML. hString wraps fString in an mdel:// anchor, so a logged element becomes a link that selects it in the containment tree:

GUILog.log("«Attribute» applied to ${element.hString()}", true)

The label is HTML-escaped, because a model element may legitimately be named A<B or R&D and an unescaped name renders as neither a link nor the name. A value that is not a model element, or whose URL cannot be resolved, degrades to the escaped fString rather than to broken markup. hString takes the same IdStyle argument and the same compatibility overload as fString.

fString itself escapes nothing — it is plain text, meant for a log line or an exception message. Only hString escapes, because only hString produces HTML.

Any other text assembled from model names and sent to the Message Window needs escapeHtml, which is exposed for that reason:

GUILog.log("skipped ${escapeHtml(project.name)}", true)

Anvil writes nothing to the Message Window itself. GUILog.log(String) delegates to log(message, open = true), which opens the notification window on every call. Interrupting a modelling session is a decision that belongs to the resource making it, at the moment it interrupts, and the resource calls GUILog with the flag it wants. hString is there for the resource that builds such a sink — or the resource reaches for Notify.of(category), which builds a transient balloon sink already, with no window and no interruption; see Anvil: notify a modeller. See Anvil: log from a resource.

On this page