The Text Editor and Browser

Overview

The Editor (Model → Editor) edits a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 model as text. The Browser (Model → Browser) shows the same model as a tree of packages and their members.

Both work on one model. Text you type is applied to the model when it parses. A change made anywhere else, such as in a view, a table or the inspector, appears in the text at once. Show in Text and Open Text buttons across the app open the Editor at an element.

Concepts

Text documents

The Editor shows one text document per top-level package. The Packages list on the left switches between them. Elements at the top level that are not in a package share one extra document, Outside packages.

A project holds no files: the documents are printed from the model. To get .sysml files, export the model (see Exchanging SysML v2 Models).

Applying text to the model

Typing changes only the text at first. The text is applied to the model at a commit point:

• when you stop typing for a moment (about 0.6 s);
• when you leave the editor;
• when you press ⌘S / Ctrl+S or ⌘↩ / Ctrl+Enter.

Each commit is one undo step. Holarch compares the text with the model and changes only what differs, so elements keep their identity. A renamed element stays the same element: its view positions, comments, traces and links follow it.

Errors and drafts

Text with an error is not lost. The members that parse are applied; a member with an error is not applied and keeps its last good state in the model. The status line says Not applied: fix line N.

Text that is not applied yet stays a draft in this browser until it parses. When you open the package again, a banner says This text has changes from <date> that are not applied to the model. Fix the text to apply it, or click Discard Draft to go back to the model's text.

Drafts are kept only in the browser where you typed them. Other people see the model's last good state.

How to use it

Open a package's text

1. Open Model → Editor. The first package opens. If the model has no packages, click + New Package.
2. Click a package in the Packages list to open its text.
3. To jump to an element, use Show in Text in the Browser, the inspector or a view. The Editor opens its package and selects its declaration.

Edit and apply text

1. Type as in any code editor. Enter keeps the indentation and indents after {; typing } lines it up with its opening line.
2. Stop typing. The status line under the text shows Not applied yet, then Applying…, then Applied. The Browser, views and pages now show the change.
3. Press ⌘Z / Ctrl+Z to undo typing. When the Editor has no typing left to undo, ⌘Z / Ctrl+Z undoes the project's last change, like everywhere else in Holarch.

A change that only reformats the text shows No model changes.

Insert a construct

Insert ▾ writes a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. construct for you, such as a part with its type and multiplicity.

1. Place the cursor on an empty line in the body where the construct belongs.
2. Click Insert ▾ in the top bar, or press ⌃⇧Space / Ctrl+Shift+Space. The list shows only the constructs that fit at the cursor, in four groups: Structure, Behavior, Requirements and Other. Its header says where you are, for example Package level or Inside part definition.
3. Type to filter the list. The preview shows the text and what it means.
4. Press Enter (or click) to insert it on its own line.
5. Type over the selected field (a name, type or multiplicity), then press Tab for the next field. ⇧Tab / Shift+Tab goes back. Type fields list the model's definitions.
6. Press Tab after the last field, or Esc, to leave the snippet. The construct is applied to the model.

Completion offers the same snippets: typing par offers the keyword part and the Part snippet.

Complete names and keywords

1. Type two letters of a name or keyword, or :: or . after a name. Or press ⌃Space / Ctrl+Space. A list offers the keywords, names and snippets that fit at the cursor.
2. Move with ↑ and ↓ (PageUp and PageDown jump 8 rows).
3. Press Enter or Tab to accept, or Esc to close the list. A list that opened while you typed also closes after 4 seconds without a key, when the name is complete, when nothing matches, or when you move the cursor away or leave the editor.

Go to a definition and rename

1. Point at a name to see a card with its kind, qualified name and documentation, and any problem on it. ⌘I / Ctrl+I shows the same card from the keyboard. The card closes when you edit, press Esc, scroll, leave the editor or move the pointer away, and it never covers the completion list.
2. ⌘ / Ctrl-click a name, or press F12, to go to its declaration. A declaration in another package opens that package.
3. To rename, place the cursor on a declared name and press F2. Enter the New name and confirm. Every reference to it changes, in every package, as one undo step. The toast says Renamed to “name”.

Find and replace

1. Press ⌘F / Ctrl+F or click Find in the top bar.
2. Type the text to find. The bar shows n of m matches.
3. Turn on Aa (match case), W (whole word) or .* (regular expression) as needed.
4. Press Enter or ⌘G / Ctrl+G for the next match, ⇧Enter / Shift+Enter or ⇧⌘G / Ctrl+Shift+G for the previous one.
5. Click Replace…, type the replacement, then Replace (this match) or Replace All.
6. Press Esc or click ✕ to close the bar.

Fix errors

1. Look at the status line: it counts the problems, for example 2 errors, 1 warning, or says No problems.
2. Press F8 to go to the next problem (⇧F8 / Shift+F8: the previous one). Or click a mark in the gutter. The problem is selected and its message shows: first the problem, then the fix.
3. Fix the text. When the member parses, it is applied.

Browse the model tree

1. Open Model → Browser.
2. Click ▸ next to a package to open it, or click Expand All.
3. Type in Filter by name, or choose a kind such as part def in All kinds. The tree shows the matches with their owners. The count shows n of N elements.
4. Select an element to see its details in the inspector.
5. Double-click it, or press Enter, to show it in the Editor.

Delete and restore elements

1. In the Browser, open the row menu (⋯, right-click or Shift+F10) and choose Delete…. Confirm. The element and its members go to the project's Trash. Deleting the text in the Editor has the same effect.
2. To bring it back, open the Trash tool at the bottom of the rail and click Restore on its row. It returns with the same identity, so references to it resolve again.

Worked example: add a wheel sensor to the Hybrid Car

This example uses the Hybrid Car (SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2) demo.

1. Open Model → Editor and click Vehicles in the Packages list.
2. Find part def Wheel :> Component. Place the cursor on a new empty line inside its body, after port hub : ~TorquePort;.
3. Press ⌃⇧Space / Ctrl+Shift+Space. The header says Inside part definition. Type att and press Enter to insert Attribute.
4. Type speedSensorMass over the name field, press Tab, type MassValue over the type field and press Tab again to leave the snippet. The line reads attribute speedSensorMass : MassValue; and is applied.
5. Type = 0.2 [kg] before the ; and stop typing. The status line says Applied.
6. Open Model → Browser, type speedSensor in Filter by name. The attribute shows under Vehicles › Wheel; its inspector shows Owner Wheel and Typed by MassValue.
7. Back in the Editor, press F2 on speedSensorMass, enter sensorMass and confirm. The Browser shows the new name.
8. Delete the line and pause. The attribute goes to the Trash; restore it there with Restore.

Tips and common mistakes

• Save is automatic. ⌘S / Ctrl+S only applies the text now; there is nothing else to save.
• One error does not block the rest. Members before and after a broken member are still applied.
• Typing over a collaborator. If the model changed while you typed, Holarch merges your text with the new model. When both changed the same member, choose Keep Mine or Take Theirs.
• Renaming by retyping. Changing a name in place also keeps the element (Holarch matches it by position and kind), but references elsewhere still use the old name and no longer resolve. Use F2 to rename everywhere.
• Deleting a used element. When deleted text removes an element that other elements or views use, Holarch asks first. Cancel to keep it; the text then stays not applied until you press ⌘S / Ctrl+S to decide again.

The Editor

Layout

• Packages (left): one entry per top-level package, plus Outside packages when needed. A number after the open package counts its errors. In a shared project, initials show who else has a package open.
• Top bar: + New Package, Insert ▾ and Find.
• Text area: syntax highlighting, line numbers and a gutter with problem marks. Click a line number to select the line; click a mark to select the problem and show its message.
• Status line (below the text): the cursor position (Ln 12, Col 5), the problem count, and the apply state.

Viewers see the text read-only.

Insert ▾ constructs

Each construct is offered only where it is valid. TBDTo Be Determined A requirement value or detail that is not known yet. Holarch tracks TBDs with an owner and a due date. Value and TBRTo Be Reviewed A requirement value that is filled in but still needs to be confirmed. Value need private import HolarchMetadata::*; in the package (see Mark a value as TBD or TBR).

Keyboard shortcuts

On Windows and Linux, use Ctrl in place of ⌘. / Ctrl+.

Text and views stay in sync

The text, the views, the tables and the inspector are all ways to edit one model.

• Text to model. Text is applied at each commit point, as one undo step. Views, tables and pages update at once.
• Model to text. A change in a view, the Browser, a table, the inspector, a change request or an undo is written into the text right away. If you have unapplied text in the same package, Holarch merges it with the change; see Working with others.
• Every change is checked first. A view edit is written as SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. text and checked before it is applied. If it cannot be written as valid text, it is refused: The change cannot be written as SysML text: …. A guard that is not a valid expression, for example, is refused in an action flow view.
• Your formatting stays. Elements you did not change keep their exact text, including comments, blank lines and keyword spellings (such as subsets versus :>). A changed part of an element, or a new element, is written in the standard layout, indented like its neighbors.
• Layouts stay. View positions are stored by element identity. Editing or renaming an element in the text keeps its place in every view.

Holarch data (status, results, labels, layouts, simulator settings) is never written into the text. See Model data and Holarch data.

Working with others

In a shared project, several people can edit the model at once.

• The Packages list shows the initials of others who have a package's text open. Point at them for the names.
• When the model changes while you type, Holarch merges your unapplied text with the change, member by member. A clean merge keeps you typing.
• When you and someone else changed the same member, a banner says <Package> changed while you were typing. Click Keep Mine to apply your text over theirs, or Take Theirs to replace your text with the model's.
• If someone deletes or moves the package you have open, a banner says This package was deleted or moved. Its text stays here until you leave the page.

The Browser

The Browser shows the model as a tree: top-level packages, then their members in order.

Top bar and filters

• Expand All and Collapse All open or close every element. The Browser remembers what is open in this browser.
• Filter by name matches names and short names.
• All kinds limits the tree to one kind, such as part def, requirement or port. Only kinds in the model are listed.
• With a filter, the tree shows the matches with their owners, all open. The count shows n of N elements.

Rows

Each row shows the element's kind, its name and its short name in angle brackets (<VR-1.1>). Elements without a name show as (unnamed kind), for example (unnamed succession).

Inspector

Select an element to see it in the inspector, the same element panel as on the Database page: Item (short name, name, documentation, labels, assignee), Features (type, multiplicity, value), Trace, Discussion and Details (kind, qualified name, owner, history). Edits are written into the model, one undo step each. See Holarch Features.

Row menu

Open it with ⋯ on the row, a right-click, Shift+F10, the context-menu key or F2.

Keyboard

Misplaced elements

An element whose owner is missing, for example after a collaborator deleted its package at the same moment, is listed under Misplaced (owner missing): move them into a package. Home shows a Misplaced elements card too. Open the element in the Editor and move its text into a package.

Deleted elements

Deleting an element in a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project moves it to the project's Trash. It takes with it everything it owns, the connections and satisfy relationships that name it, its view layouts and its comments.

• Open the Trash tool at the bottom of the rail. Each row shows the element's kind, name, when it was deleted, the reason (Deleted with 3 members) and how long it is kept.
• Restore brings it back with the same identity, so references to it resolve again. Restore All restores every entry.
• ⋯ → Preview shows its kind, short name, documentation, members, and the elements that still refer to it (Referenced by).
• ⋯ → Delete for Good… removes one entry at once. Empty Trash removes them all. Both can be undone with ⌘Z / Ctrl+Z.
• Entries are removed automatically after 30 days.

When deleted text removes an element that is still used, the Editor asks first: <n> references and <m> views use <name>. Delete it?

Accessibility

The Editor and the Browser work with the keyboard alone and with a screen reader.

• The Editor is a labelled text box. Tab indents; to leave the editor, press Esc, then Tab.
• F8 and Shift+F8 move to the next and previous problem and read it with its line. Problems are also announced about a second after they change.
• F12 goes to the definition, F2 renames, ⌘F / Ctrl+F finds, Ctrl+Space completes and Ctrl+Shift+Space opens Insert. Completion and Insert are lists that announce the selected entry. In a snippet, each field is announced ("Field 1 of 3: name").
• The Browser is a tree. Each row is read by its own name and kind, such as "Car, part definition". Arrow keys move through it; → opens a package and ← closes it. Shift+F10 opens the row menu.

Messages

The checker's messages about the SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. text itself are listed on SysML v2 Textual Notation.

Limits

• One text document per top-level package; there are no files inside a project.
• A document larger than 8 MB, a line longer than 64 KB, or nesting deeper than 256 levels is not checked.
• Drafts live only in the browser where you typed them.
• Find shows at most 10,000 matches (10,000+).
• Deleted elements stay in the Trash for 30 days.

Related pages

• Getting Started with SysML v2 Projects
• SysML v2 Textual Notation
• SysML v2 Views
• Exchanging SysML v2 Models

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.® and OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI.® are registered trademarks of Object Management Group, Inc. in the United States and other countries.