mps-aspect-behavior

MPS Behavior Aspect

The behavior aspect attaches methods and a constructor to a concept, much like adding methods to a Java class. Bodies are written in BaseLanguage + smodel and are callable from any other aspect (editor, constraints, typesystem, generator, intentions, plugin) via node.methodName(...). Lives in <lang>/languageModels/behavior.mps, language jetbrains.mps.lang.behavior.

Critical Directives

• One ConceptBehavior root per concept. The constructor child is mandatory (an empty body is fine).
• Constructors run before the node is attached to the model. parent, ancestors, and all children/descendants evaluate to null. Constructors can only set own property/reference defaults and add mandatory children — use a NodeFactory (actions aspect) for anything that needs the parent/model context.
• Quotations (<C()>) bypass behavior constructors. Use new node<C>() or add new initialized C when you need the constructor to fire.
• Constructors are not inherited — each concept has at most one, and they do not chain (no super()). MPS runs each ancestor's constructor in ancestor-first order independently.
• An overriding method must match the signature of the supertype/interface method exactly. When implementing an interface method (e.g. ScopeProvider.getScope), set overriddenMethod on the new method to the interface declaration — MPS uses it for dispatch and signature validation.
• Behavior calls on a null node do not NPE — MPS returns null for reference/String returns and the default for primitives. Still handle the null return for reference types.
• Hoist shared methods to an abstract super-concept rather than duplicating per-sub-concept ConceptBehavior roots — virtual dispatch covers all non-abstract sub-concepts. (See references/inheritance-and-dispatch.md.)
• Methods are non-virtual by default: all modifier booleans (isVirtual, isAbstract, isStatic, isFinal) default to false. Only virtual methods can be overridden; mark a method virtual up front if sub-concepts may ever need to specialise it.
• When the same piece of node-handling logic repeats across several places or several aspects of one concept (editor, constraints, typesystem, generator, intentions, textgen), extract it into a behavior method and call it everywhere via node.m(...) — this de-duplication is the behavior aspect's primary purpose. Pick the modifier with the table below.
• Edit behavior models through MPS MCP tools (mps_mcp_insert_root_node_from_json, mps_mcp_update_node, mps_mcp_parse_java_and_insert). Do not hand-edit .mps files.
• For MPS-typed return types (sequence<node<X>>, list<node<X>>), mps_mcp_parse_java_and_insert produces Java List<SNode> — replace returnType afterwards with the correct MPS blueprint (see mps-model-manipulation/references/variable-declarations.md).
• After edits run mps_mcp_check_root_node_problems and rebuild the language.

Common-Path Workflow

1. Create a behavior model if missing (mps_mcp_create_model with modelName: "<lang>.behavior" — aspect ID behavior, case-sensitive, no @ suffix; see aspect-model-stereotypes.md). Use languages: jetbrains.mps.lang.behavior, plus any languages referenced in bodies (smodel, collections, closures, baseLanguage).
2. Add a ConceptBehavior root for the target concept; set concept ref. The minimal blueprint (with the mandatory empty constructor) is in references/json-blueprints.md.
3. Add ConceptConstructorDeclaration (at most one) and/or ConceptMethodDeclaration children.
4. Write bodies. For non-trivial logic prefer mps_mcp_parse_java_and_insert with featureKind: "STATEMENTS" or "METHOD", then fix MPS-typed return/parameter types.
5. Validate with mps_mcp_check_root_node_problems, rebuild the language.

Method Modifier Quick Reference

Choosing a modifier for an extracted method

• Invoked on a node (needs this, properties, children)? → instance method: virtual if sub-concepts must be able to override it (or the logic varies by concept), non-virtual for a fixed helper.
• Invoked on a concept (no node instance at hand, concept-wide utility, or nodes passed as parameters)? → static; make it virtual static when the result must vary per concept (dispatch on a concept<X> value).
• Shared by several sub-concepts? → declare it once on their common (abstract) super-concept or interface; use abstract (+ virtual) when only sub-concepts can supply the body.

Related Skills

• mps-aspect-actions — NodeFactory is the right place for initialization that needs parent/model context (constructors run before the node is attached).
• mps-aspect-intentions, mps-aspect-constraints, mps-aspect-generator, mps-aspect-typesystem — call behavior methods via node.m(...); behavior is one of the most-used aspects from these.
• mps-model-manipulation — full BaseLanguage / smodel / collections reference. Covers the LinkList_AddNewChildOperation family and the List<SNode> → sequence<node<X>> return-type fix.
• mps-aspect-constraints — ScopeProvider.getScope is most often overridden in a behavior; constraints describe where the reference lives.
• mps-aspect-structure-concepts — when introducing the concept that the behavior attaches to.
• mps-language-inheritance — to design the abstract-super-concept refactors discussed in references/inheritance-and-dispatch.md.
• mps-quotations — quotations bypass behavior constructors; document the workaround in the generator.

Reference Index

• Open references/method-declarations.md when authoring a ConceptMethodDeclaration — modifiers, parameters, overriddenMethod, BaseConcept overrides (getPresentation / getSideIcon), implicit-return rule, and the MPS-typed return-type Java-parser caveat.
• Open references/local-and-super-calls.md when calling sibling methods of the same ConceptBehavior (LocalBehaviorMethodCall), distinguishing unqualified m(args) from this.m(args) (which generates DotExpression { ThisNodeExpression, Node_ConceptMethodCall }), or calling super<Interface>.method(...) — includes the verbatim Stateful and Kaja CommentLine_Behavior examples and the Stateful_Behavior.getScope super-call JSON.
• Open references/inheritance-and-dispatch.md when designing or debugging virtual dispatch — the MRO algorithm (own → extended super → interfaces in definition order), how a method on an abstract super-concept covers every concrete sub-concept (Stateful pattern), and when to hoist shared behavior up vs. duplicate per concept.
• Open references/constructors.md when writing a ConceptConstructorDeclaration — what runs and what does not run a constructor, the "node not yet attached" constraint, scalar-default and seed-mandatory-child examples (ChemMastery Compound_Behavior and ChemEquation_Behavior) with full JSON blueprints, and the surface→FQN mapping for the surface syntax involved.
• Open references/calling-from-other-aspects.md when calling a behavior method from generator templates, typesystem rules, constraints, intentions, or hand-written Java — the descriptor invocation shape, the _idXXXXX stable suffix, and the null-safety behavior of node.method().
• Open references/json-blueprints.md when inserting a behavior root or a method via MCP — minimal ConceptBehavior with the mandatory empty constructor, the ConceptMethodDeclaration skeleton, and the validated concept ref.
• Open references/lang-core-behavior-overrides.md for the validated node refs to set as overriddenMethod when implementing common lang.core.behavior methods (getTextualRepresentation, isTODOComment, getScope), plus the IGenericComment interface node ref used in super<IGenericComment>.isTODOComment() calls.
• Open references/common-failures.md when a behavior method isn't found, an override is ignored, a constructor's defaults don't stick, a descriptor returns Object, the return type fights the Java parser, or quotations bypass the constructor.