Part III · Conformance and process
All requirements
Every requirement in the specification, by chapter, and whether Roswaal meets it.
InformativeDraft 0.1
Each requirement is numbered for the section it is in: 5.8-R3 is the third in §5.8. A number never moves once published, so it can be cited; one that is taken out leaves its number unused. Each links to where the chapter states it.
| Roswaal | Requirements |
|---|---|
| Roswaal meets | 87 |
| Roswaal partly | 8 |
| Not yet in Roswaal | 9 |
| All | 104 |
1 Overview
| Number | Requirement | Roswaal |
|---|---|---|
| 1.2-R1 | An implementation given a graph for a profile it does not support MUST say so, rather than open the graph as though it belonged to another. | Not yet in Roswaal. Roswaal reads a graph whose target it does not know as a Roblox graph. |
| 1.3-R1 | An implementation MUST state which levels and which profiles it conforms to, and which draft of the specification. | Not yet in Roswaal. Roswaal does not say yet. It will once there are fixtures to check a claim against (§13). |
2 Principles
| Number | Requirement | Roswaal |
|---|---|---|
| 2.1-R1 | A profile MUST keep all ten. Where a language seems to need an exception, the exception is a proposal to change this page (§14.2), not a choice a profile makes quietly. | Roswaal partly. Roswaal's two Luau profiles do not yet keep principle 9 on the canvas (§8.4), and a graph with more than one script start runs them by position (§7.1), which principle 1 rules out. |
4 Interaction
| Number | Requirement | Roswaal |
|---|---|---|
| 4.1-R1 | An editor MUST offer a searchable list of every node the graph's profile and its packs provide, opened where the pointer is, and place the chosen node there. | Roswaal meets |
| 4.1-R2 | Search SHOULD match a node's title first, then its other names, its category and its description, and SHOULD also find things that become nodes: the graph's variables, functions and parameters. | Roswaal meets |
| 4.1-R3 | Dropping a wire on empty canvas MUST open the same list, narrowed to nodes with a pin the wire can connect to (§6.3), and connect the wire to the first such pin of the node chosen. | Roswaal partly. Roswaal's list is narrowed. Its larger visual picker, opened with Ctrl, is not, though it still connects the wire. |
| 4.1-R4 | Choosing a step while dragging from a wired flow output SHOULD put the new step into the chain, between the two it was joining. | Roswaal meets |
| 4.2-R1 | While a wire is in flight, every pin it cannot connect to MUST fade, and the pins it can SHOULD be marked, so the legal targets are the only ones that read as reachable (§5.8). | Roswaal meets |
| 4.2-R2 | While a wire is in flight, a pin's target area SHOULD grow, because by then the person knows which pin they want. | Roswaal meets |
| 4.2-R3 | Dropping on an input that already has a wire MUST replace that wire (§7.1). Dragging from a wired input SHOULD lift its wire off, to be dropped somewhere else. | Roswaal meets |
| 4.2-R4 | Dropping a data wire on the body of a node that takes a list SHOULD add a pin and connect to it. | Roswaal meets |
| 4.2-R5 | Where a wire would connect only through a conversion the profile offers, such as narrowing a class to a subclass, an editor MUST NOT connect the pins directly. It MAY place the conversion node itself, as Roswaal does. | Roswaal meets |
| 4.2-R6 | A wire MUST be removable from either end and from the wire itself. Roswaal removes one with Shift-click or Alt-click on the wire, and every wire on a pin with Shift-click on the pin. | Roswaal meets |
| 4.2-R7 | Double-clicking a wire SHOULD add a reroute knot where it was clicked. | Roswaal meets |
| 4.3-R1 | Positions are free. Holding Shift while moving SHOULD snap the node being dragged to the grid (24 units, §5.1), the rest of the selection keeping its place relative to it. | Roswaal meets |
| 4.3-R2 | Moving a comment MUST move what is inside it: every node and comment wholly within it. What is inside is worked out when the move starts, never stored. | Roswaal meets |
| 4.4-R1 | An input with no wire MUST be editable on the node itself, with an editor for its type: a check box for a boolean, a number field, a text field, or a choice from the values the pin allows. | Roswaal meets |
| 4.4-R2 | An optional input MUST show whether it is passed at all, apart from what it is set to. Roswaal shows default until it is set, and a control beside a set value to stop passing it. | Roswaal meets |
| 4.5-R1 | Controls that change a node, such as adding or removing a pin on a node that takes a list, MUST be hidden at rest and MUST appear when the pointer is over the node, when the node is selected, or when the keyboard reaches them. | Roswaal meets |
| 4.5-R2 | Hidden, they MUST NOT take clicks, and showing them MUST NOT move anything else in the node. | Roswaal meets |
| 4.5-R3 | A node that takes a list SHOULD offer one control that adds an entry at the end, and one beside each entry that removes it, wherever it is in the list. Roswaal hangs an Add row under the node and puts a grey × beside each entry. | Roswaal meets |
| 4.5-R4 | Removing an entry MUST keep the wires and typed values of the entries after it on those same entries, and MUST remove the removed entry's own wires. | Roswaal meets |
| 4.5-R5 | A control to remove an entry MUST NOT be offered when the node is at its minimum. | Roswaal meets |
| 4.6-R1 | A problem a compiler finds in a node (§7.7) MUST be shown on the canvas, on that node, as soon as it is found: its count on the node, its sentence under the node, the pin it names marked (§5.8). | Roswaal meets |
| 4.6-R2 | An editor MUST NOT show a problem only in a list away from the graph. It MAY list every problem elsewhere as well. | Roswaal meets |
| 4.6-R3 | A warning that is about where a node sits rather than what it is, such as a node not yet joined to anything, SHOULD NOT be marked on the node while a graph is being built. A warning a person can act on from the node SHOULD be. | Roswaal meets |
| 4.7-R1 | An editor SHOULD use the platform's own keys for undo, redo, copy, cut, paste, select all and delete. | Roswaal meets |
| 4.8-R1 | An editor that can be used by touch MUST offer every action of this chapter to a finger. | Roswaal meets |
| 4.9-R1 | Every change to a graph MUST be undoable: nodes, wires, comments, values, variables and settings stored in the file. Selecting, panning and zooming are not changes and MUST NOT be undone. | Roswaal meets |
| 4.9-R2 | A gesture MUST be one step however many changes it makes: a drag, a resize, a node placed with a wire connected to it. | Roswaal meets |
| 4.9-R3 | Typing into a field SHOULD be one step from the first key to leaving the field. | Roswaal partly. Roswaal's Inspector fields are one step each; the fields on the canvas itself undo a change at a time. |
5 Visual grammar
| Number | Requirement | Roswaal |
|---|---|---|
| 5-R1 | Where a length is given, a renderer MUST use it, so that a graph drawn by one implementation can be laid over the same graph drawn by another and every pin meets the same wire. | Roswaal meets |
| 5.1-R1 | The grid MUST be drawn below everything in the graph (§5.8). | Roswaal meets |
| 5.2-R1 | A wire MUST end where its pin is, by these rules. A renderer that drew the pin elsewhere would show a wire ending in empty space. | Roswaal meets |
| 5.3-R1 | A renderer MUST NOT draw one kind of node in another's shape. | Roswaal meets |
| 5.4-R1 | A renderer MUST NOT fill a header with the category's colour at full strength and MUST NOT put the category's colour behind the title text. The colour belongs to the tab. | Roswaal meets |
| 5.4-R2 | A node that holds code SHOULD show the profile's mark for that kind of code in its tab, in place of a glyph, as the profile's code editor marks it. Roswaal's are { } for statements, ƒx for an expression and <T> for a type, in the theme's code colours on the code editor's surface. | Roswaal meets |
| 5.4-R3 | A function definition's second line SHOULD be its signature as types alone, each in its type's colour, such as (Model, BasePart) → boolean: the names are on its pins, and with them the line is too long to read. | Roswaal meets |
| 5.5-R1 | A renderer MUST draw these shapes, so a pin's kind can be read without telling colours apart (§8.1). | Roswaal partly. A reroute knot's pin is drawn as a circle whatever it carries. |
| 5.5-R2 | The full name of a type on a chip MUST be shown when the reader asks, by pointing at the chip or tapping it, with what the type is. | Roswaal partly. The canvas does. The documentation's pictures draw the chips but cannot open their card, and do not yet draw a getter's, an operator's or a knot's type under it. |
| 5.6-R1 | Where a data wire joins pins of different colours, as when a number feeds a string, it SHOULD fade from one colour to the other along its length. | Roswaal meets |
| 5.6-R2 | A wire MUST be drawn below every node (§5.8). | Roswaal meets |
| 5.6-R3 | A renderer MUST offer the curved route, and MAY offer others. | Roswaal meets |
| 5.7-R1 | A theme MUST meet the contrasts of §8.2. | Roswaal meets |
| 5.8-R1 | A renderer MUST keep this order. The numbers are Roswaal's; another implementation MAY use any numbers that keep the same order. | Roswaal meets |
| 5.8-R2 | A node with an error MUST be marked: its border in the theme's danger colour and a count of its errors on its corner. | Roswaal meets |
| 5.8-R3 | The first problem's sentence MUST be written under the node, in a note, with how many more there are. A pin a problem names MUST be marked in the node. | Roswaal meets |
| 5.8-R4 | Notes MUST be drawn above every node, comment and wire, selected or not, so nothing in the graph covers what is wrong with it. Only the panels around the canvas, its menus and the compile cover MAY cover one. | Roswaal meets |
| 5.8-R5 | A note MUST be drawn in a layer of its own rather than inside its node: a node is drawn as a unit, so nothing inside one can rise above the node next to it. | Roswaal meets |
| 5.8-R6 | Where two notes overlap, the one belonging to a selected node SHOULD be drawn on top. | Roswaal meets |
| 5.8-R7 | A note SHOULD NOT take the pointer, so the node under it can still be grabbed. | Roswaal meets |
6 Types
| Number | Requirement | Roswaal |
|---|---|---|
| 6.1-R1 | A renderer SHOULD say where it shows a pin's type that its value may be missing. Roswaal writes Model?. | Roswaal partly. Roswaal does in a pin's tooltip and the Inspector, and not yet on its type chip. |
| 6.1-R2 | Choosing the type of an any input narrows what can be wired and typed in, and MUST NOT change the program. | Roswaal meets |
| 6.2-R1 | A profile MUST put each of its types in one family, and MUST NOT add a family. | Roswaal meets |
| 6.3-R1 | An editor MUST refuse to make a wire this rule does not allow, and SHOULD say why. | Roswaal partly. Roswaal refuses every one, and says why only when a class cannot be narrowed without a cast. |
| 6.3-R2 | A compiler MUST report a wire between a flow pin and a data pin as an error, and SHOULD report a data wire this rule does not allow, which can arrive in a file written elsewhere, as a warning. | Roswaal meets |
| 6.3-R3 | A wire between two types the rule joins through a conversion SHOULD be drawn so the change shows (§5.6). | Roswaal meets |
7 Execution
| Number | Requirement | Roswaal |
|---|---|---|
| 7.1-R1 | A compiler SHOULD warn when a graph has more than one script start. | Roswaal meets |
| 7.1-R2 | A compiler SHOULD say so when a graph has nodes and no entry. | Roswaal meets |
| 7.1-R3 | A flow output MUST lead to at most one node. | Roswaal meets |
| 7.1-R4 | A flow input MUST take at most one wire. Two flows cannot join at one node. | Roswaal meets |
| 7.1-R5 | A compiler SHOULD warn about a node that nothing running reaches. | Roswaal partly. Roswaal follows every wire, not only flow wires, so a step joined to the rest only by data wires is not warned about, though it never runs. |
| 7.1-R6 | Flow wires MUST NOT form a loop. Repetition is a loop node's: a compiler MUST report a loop of flow wires as an error. | Roswaal meets |
| 7.1-R7 | A step that ends its block, such as a return, break or continue, MUST be the last step of its chain. A compiler MUST report a step that could never run after one, such as a sequence output following an output that returned. | Roswaal meets |
| 7.1-R8 | Break and continue MUST be inside a loop's block, and not inside a function nested in it. | Roswaal meets |
| 7.2-R1 | Within one block, a value MUST be worked out once however many inputs it feeds, so work and side effects are not repeated. A compiler MAY write a value used once directly where it is used. | Roswaal meets |
| 7.2-R2 | A variable's value is read where it is used, every time, never shared between uses: a set between two reads MUST be seen by the second. | Roswaal meets |
| 7.3-R1 | A renderer MUST mark a latent node where it can be seen. Roswaal puts an hourglass in its header. | Roswaal meets |
| 7.4-R1 | A compiler MUST report a read of a local, a parameter or a step's output outside its scope as an error. | Roswaal meets |
| 7.5-R1 | Each function's body is drawn in a graph of its own (§9.2), and a wire MUST NOT run between two graphs: a value reaches a function through a parameter, a local or a variable. | Roswaal meets |
| 7.7-R1 | A compiler MUST report each of these as an error, on the node or wire at fault (§5.8), and MUST NOT produce a program from a graph that has one: | Roswaal meets |
| 7.7-R2 | A compiler SHOULD report these as warnings: a node joined to nothing that runs, a graph with no entry, more than one script start, and a wire between pins whose types do not connect (§6.3). | Roswaal meets |
8 Accessibility
| Number | Requirement | Roswaal |
|---|---|---|
| 8.1-R1 | A renderer MUST NOT rely on colour alone to tell any two things on the canvas apart. | Roswaal meets |
| 8.2-R1 | A theme MUST be refused if any of these is lower than its minimum, using the WCAG 2 contrast ratio: | Roswaal meets |
| 8.2-R2 | A theme MUST say whether it is dark, and the claim MUST match its window colour, because the overlays worked out from it (§5.7) depend on it. | Roswaal meets |
| 8.3-R1 | Landing a wire takes no aim: while a wire is in flight every pin's target MUST grow. Roswaal's grows to 9 units around the slot, 34 across. | Roswaal meets |
| 8.3-R2 | On a touch screen, every control SHOULD be at least 44 by 44 CSS pixels at the zoom the graph is shown at, as WCAG 2.5.5 asks, and where a control cannot be, the editor SHOULD offer a way to zoom to one that is. | Not yet in Roswaal. On a touch screen Roswaal's toolbar buttons grow to 38 pixels, and its pins do not grow at all. |
| 8.4-R1 | Every action of chapter 4 MUST be possible from the keyboard alone: moving between nodes and between a node's pins, making and removing a wire, opening the node list and placing a node, moving a node, and editing its values. | Not yet in Roswaal. Nothing on Roswaal's canvas is reached by the keyboard yet. |
| 8.4-R2 | A node MUST have an accessible name: its title, its kind, and its problems. A pin MUST have one: its name, its side, its type, and what it is wired to. | Not yet in Roswaal. Roswaal's nodes and pins have no accessible names; its menus, dialogs and panels have roles and labels. |
| 8.4-R3 | Changes a person makes SHOULD be announced: a wire made, a node placed or deleted, a problem found or fixed. | Not yet in Roswaal. Roswaal announces only compiling and its toasts. |
| 8.4-R4 | Focus MUST be visible on the canvas, on a node and on a pin. | Not yet in Roswaal. Roswaal draws no focus ring on its canvas. |
| 8.5-R1 | Where the system asks for reduced motion, an editor MUST drop animation that is not needed to understand a change, such as controls fading in on hover. | Roswaal meets |
| 8.5-R2 | A renderer MUST NOT make anything flash more than three times a second. | Roswaal meets |
| 8.5-R3 | An editor MUST NOT move the view without being asked, except to show something the person asked to see. | Roswaal meets |
9 File format
| Number | Requirement | Roswaal |
|---|---|---|
| 9.1-R1 | A reader MUST keep fields it does not know when it writes a file back. | Not yet in Roswaal. Roswaal keeps them in roswaal.json, and drops them from a graph file when it saves it. |
| 9.2-R1 | An implementation MUST NOT read meaning into another's ids. | Roswaal meets |
| 9.3-R1 | The list of modules is the program's whole list: a compiler MUST NOT load a module the list does not name. | Roswaal meets |
| 9.6-R1 | A field of the project file a reader does not know MUST be kept. | Roswaal meets |
| 9.7-R1 | A reader MUST refuse a file with a higher version than it knows, and say it was written by a newer implementation, rather than guess at it. | Roswaal meets |
| 9.7-R2 | A reader SHOULD bring an older file up to date as it reads it: fill in fields that did not exist, and rename nodes and pins that were renamed. It MUST say what it changed. | Roswaal meets |
| 9.7-R3 | A writer MUST write the version it implements. | Roswaal meets |
| 9.8-R1 | So that a graph saved twice is the same bytes, and a change to a graph is a small change to its file, a writer SHOULD write the canonical form: two-space indentation and a final newline; keys in the order this chapter lists them; nodes, links and comments sorted by id; the keys inside literals and config sorted; positions rounded to two decimal places; and optional fields left out when empty. Variables and modules keep the order the author gave them. | Roswaal meets |
10 Writing a profile
| Number | Requirement | Roswaal |
|---|---|---|
| 10.2-R1 | A profile MUST NOT change the meaning of anything in Part I. | Roswaal meets |
| 10.3-R1 | Every type a pin can have MUST have a name, a family, and a colour or the profile's colour for untyped pins. | Roswaal meets |
| 10.3-R2 | Where the language has subtypes, the profile gives each type its parent. A type MUST NOT be its own ancestor, and a reader SHOULD stop following parents after a fixed number of steps rather than trust the data. | Roswaal meets |
| 10.4-R1 | Node definitions MUST be data. A profile's library, and every pack written for it, MUST load without running any code from it. | Roswaal meets |
| 10.4-R2 | Each definition has an id, a title, a category, its pins, and what it becomes (§10.5). Its id is how files refer to it (§9.2), so it MUST NOT change; a renamed node keeps its old id as an alias (§9.7). | Roswaal meets |
| 10.5-R1 | A pack MUST NOT use builtin: a definition a pack brings compiles from a template. | Roswaal meets |
| 10.6-R1 | The file SHOULD begin by saying it was generated, from which graph file, and that it is edited by editing the graph. | Roswaal meets |
| 10.6-R2 | It SHOULD carry the graph's id and a hash of the graph and of its own text, so an implementation can tell a file it wrote from one edited by hand. | Roswaal meets |
| 10.6-R3 | It SHOULD be laid out by the language's usual formatter, where the project has one. | Roswaal meets |
| 10.6-R4 | It MUST NOT need a library of the implementation's to run (§2.1, principle 10). | Roswaal meets |
| 10.7-R1 | A profile MUST come with fixtures: graphs, and the programs they should compile to or what those programs should do when run. | Not yet in Roswaal. Roswaal's two profiles have tests of their own, but no fixtures published in the shape §13 describes. |
14 Process
| Number | Requirement | Roswaal |
|---|---|---|
| 14.3-R1 | A profile's id is what a graph file says it is for (§9.1), so two profiles MUST NOT share one. | Roswaal meets |