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:
| Receiver | Renders as |
|---|---|
null | null |
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 BaseElement | Class "Concept A" «Concept» (…428316_3213) |
| Anything else | Its 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.
IdStyle | Prints | Use when |
|---|---|---|
FULL (default) | The whole identifier | The line will be searched against a model export |
SHORT | The last two segments, as …428316_3213 | The line is read by eye, or thousands are |
NONE | Nothing | The 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.
Link an element in the Message Window
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.
Related
- Anvil: log from a resource — the logger these renderings are usually passed to.
- Anvil: trace model events — every trace line is assembled from
fString. - Anvil: notify a modeller —
hStringrenders a notification'ssubject.