mapcan 0.23.0__tar.gz → 0.23.2__tar.gz

{mapcan-0.23.0 → mapcan-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mapcan
-Version: 0.23.0
+Version: 0.23.2
 Summary: A YAML map of CAN signals as the single source of truth: validation, Excel/PDF/Markdown/HTML, DBC, C/Python code
 Project-URL: Homepage, https://github.com/ordu1453/mapcan
 Project-URL: Documentation, https://github.com/ordu1453/mapcan/blob/main/docs/format.md

{mapcan-0.23.0 → mapcan-0.23.2}/docs/format.md

@@ -180,7 +180,7 @@ CANopen ID computation:
 | `terminator` | `string`: the byte that ends a shorter text and fills the rest of the field: a number (`0x00`) or one character (`"*"`, as in J1939 text parameters). Without it the text fills the field and unused bytes are 0x00 |
 | `start_bit` + `bit_length` | Canonical position |
 | `byte` [+ `bit`] + `byte_length` \| `bit_length` | Shorthand position (see below) |
-| `byte_order` | `little_endian` (default) or `big_endian` |
+| `byte_order` | `little_endian` (default) or `big_endian`. CANopen and J1939 carry little-endian data, so the editors offer the field only on other buses (or when it is set), and validation warns about a big-endian signal there (`byte-order-protocol`) |
 | `representation` | How the raw value is read as a number: `unsigned` (default), `twos_complement` (the usual signed integer), `ones_complement` or `sign_magnitude`. Generated C and Python code packs and unpacks the value in this representation; the last two have a symmetric range (−127…127 for 8 bits). DBC stores two's complement only, so the export warns about the other two. Formerly `signed` + `signed_code` |
 | `values` | Value table: `{0: NO_DATA, 1: {name: OK, description: "normal"}}` |
 | `value_format` | `dec` \| `hex`: how values are shown in documents |
@@ -302,6 +302,13 @@ marked as float.
 `start_bit` cannot be combined with `byte`/`bit`, and `bit_length` cannot be combined with
 `byte_length`.
 
+Both notations are valid. The editors (the forms and bit layouts of the web editor and VS Code,
+`mapcan import dbc`) write one of them, whichever field or drag changed the position: the shorthand
+when the signal takes whole bytes from a byte boundary (`byte` + `byte_length`) or fits in one byte
+(`byte` + `bit` + `bit_length`), and `start_bit` + `bit_length` otherwise. A length the encoding
+implies (32 bits of a `float`, 1 bit of a `flag`) and `bit: 0` stay omitted where they were.
+`mapcan fmt --check` notes the positions written otherwise, without failing.
+
 #### Big-endian
 
 For `big_endian` (Motorola) signals, `start_bit` is also the position of the least significant
@@ -567,6 +574,13 @@ file (or an earlier included file) already describes can only get more `devices`
 its other fields, and a value table name used twice, are errors (`include`). Included files are
 not nested.
 
+To keep one file per device, add a device with **Add Device in a New File…** on a bus in the
+VS Code Map view, or **+ Device in a new file** on a bus page of the web editor: the editor makes
+the file (by default `devices/<name>.yaml`) with the device, named after the file when that name
+is a free identifier on the bus, and adds it to `include`, in one edit. Deleting a device from the
+editors' trees deletes an included file it leaves adding nothing to the map (only the bus by name,
+without devices, frames or value tables), with its line of `include`; Undo brings both back.
+
 Validation, documents and generated code use the whole map. Messages about an included file
 point into that file on the command line; in the editors they are shown on the `include` line
 of the main file, with the file and line in the text. The editors' trees show the included buses,
@@ -610,7 +624,8 @@ Included devices can be chosen as senders and receivers of the main file's frame
 The same map can be written with the keys in any order. `mapcan fmt FILE…` writes the keys of every
 node in one order, so that diffs of maps edited by different people and editors show only what changed;
 `mapcan fmt --check` exits 1 if a file is not in that order (for CI and a pre-commit hook). Included
-files are formatted with their map.
+files are formatted with their map. `--check` also notes signal positions written in another notation
+than the editors write (see [Shorthand position](#shorthand-position)); they do not fail the check.
 
 Only the order changes. Comments move with their key (a comment line just above a key belongs to it),
 and the author's choices stay: block or flow style (`{name: …}`), the position notation (`start_bit`
@@ -684,6 +699,7 @@ turned off with `--disable CODE` or `lint.disable`.
 | `dlc-missing` | error | Frame has no `length` (only CANopen service frames may omit it) |
 | `canopen-dlc` | warning | Length of a CANopen service frame does not match CiA 301 |
 | `frame-type-protocol` | warning | `canopen` set on a frame of a non-CANopen bus |
+| `byte-order-protocol` | warning | A big-endian signal spanning bytes on a CANopen or J1939 bus: both carry little-endian data (CiA 301, SAE J1939-71) |
 | `direction-deprecated` | warning | `direction` is set: it follows from the CANopen function and `sender`; a frame from outside the map goes to the frames of its bus. `mapcan migrate` does both |
 | `direction-mismatch` | warning | Direction conflicts with the frame's CANopen function |
 
@@ -697,7 +713,7 @@ turned off with `--disable CODE` or `lint.disable`.
 | `j1939-field-protocol` | warning | pgn/priority/destination/address/spn on a non-J1939 bus |
 | `j1939-spn-duplicate` | warning | The same SPN on several signals of the bus |
 | `j1939-tp` | info | A PGN longer than 8 bytes is sent with the J1939-21 transport protocol |
-| `canopen-od` | warning | Dictionary object on a signal outside a device's PDO, outside 0x2000..0x9FFF, or big-endian |
+| `canopen-od` | warning | Dictionary object on a signal outside a device's PDO, or outside 0x2000..0x9FFF |
 | `od-duplicate` | warning | The same dictionary object on several signals of a device |
 
 ### Sender and receivers

{mapcan-0.23.0 → mapcan-0.23.2}/docs/web.md

@@ -49,6 +49,8 @@ offers to save them before switching.
 
 The start screen also lists the bundled examples: pick one, choose where to save a copy, and it
 opens. The mapcan version is shown in the top bar next to the title and on the start screen.
+**File → Report an issue** (and the link on the start screen) opens a new GitHub issue with the
+versions of mapcan, the server's system and the browser filled in; the map itself is not sent.
 
 ### Security
 
@@ -110,13 +112,14 @@ The profile records who made which changes:
 |---|---|
 | **Tree** (left) | Document → buses → devices → frames → signals → flags and SDO exchanges. Nodes are labelled with their human-readable names (`title`), not identifiers: a device shows its abbreviation, if set, and its full name (`BMS · Battery management system`); a frame or signal without a name falls back to its identifier. Double-click a name (or a device abbreviation) to edit it. Buses and devices must have a full name: a new one gets a default name, and its name field opens in the tree right away so you can type the real one; a map without it reports `missing-title`. Frames show their CAN ID, signals the bits they occupy. A dot marks an error or warning in the node itself, a ring marks one in its children. Under a device, frames of other devices that it receives follow its own frames as links (↪, in italics), labelled with the sender (its short name if set) and the frame name; clicking one opens the original frame. **Delete** on such a link removes the device from the frame's receivers and keeps the frame itself. |
 | **Search** | By name, description or CAN ID (`0x196` or `406`). With several words, all of them must match. |
-| **Properties** | The form for the selected node. A value is applied on Enter or when the field loses focus. Validation messages appear under the field. The form shows only the fields that apply to the node: a frame on a CANopen bus hides **Direction** when its type sets it, an RX frame has no **Receivers** (the device itself receives it), a TX frame has no **Sender**, a bus frame has no **Direction**, and **Sender** and **Receivers** appear only when there are other devices on the bus. A CANopen service frame (NMT, Heartbeat, TIME, SDO) has no **Length** field: its length comes from its CANopen function. A field that is set in the YAML or has a validation message stays visible so it can be fixed. Elsewhere in the editor (page headings, breadcrumbs, frame, device and bus lists, sender and receivers) objects are shown by their names, with the identifier next to them in grey. Text fields (names, descriptions) are edited in the document language; translations into the other language written in the YAML are kept. The **?** next to a field label explains the setting, why it matters and which values are allowed (shown on hover; click to pin, Esc to close). |
+| **Properties** | The form for the selected node. A value is applied on Enter or when the field loses focus. Validation messages appear under the field. The form shows only the fields that apply to the node: a frame on a CANopen bus hides **Direction** when its type sets it, an RX frame has no **Receivers** (the device itself receives it), and **Receivers** appear only when there are other devices on the bus. There is no field for the sender: it follows from where the frame is written (its device, or outside the map for a frame of the bus); the master that sends a CANopen RX function written at its node stays `sender` in the YAML. A CANopen service frame (NMT, Heartbeat, TIME, SDO) has no **Length** field: its length comes from its CANopen function. A field that is set in the YAML or has a validation message stays visible so it can be fixed. Elsewhere in the editor (page headings, breadcrumbs, frame, device and bus lists, sender and receivers) objects are shown by their names, with the identifier next to them in grey. Text fields (names, descriptions) are edited in the document language; translations into the other language written in the YAML are kept. The **?** next to a field label explains the setting, why it matters and which values are allowed (shown on hover; click to pin, Esc to close). |
 | **Frame layout** | The bit map of the frame: rows are bytes, columns are bits 7…0. Cells are labelled with signal names and the flags of bit fields. |
 | **Frames** | The frame list on a bus or device page; ✕ in a row deletes the frame. **+ Frame** adds a frame to the list without changing the selected node. |
-| **Receives** | On a device page: the bus frames the device receives (its own RX frames and other devices' frames that list it as a receiver), with their senders. Below it, **Transmits frames of other devices** lists the frames it sends on behalf of other devices (`sender`). Both are computed from the frames; click a row to jump to the frame. On a frame page, **Sender** is picked from the bus devices and **Receivers** are toggled on and off; renaming a device updates both. ✕ in a row of another device's frame removes the device from its receivers. On an RX frame, **Frame of another device** picks a frame that is already described at its sender: the device is added to that frame's receivers and its own copy is removed (Ctrl+Z undoes it). The `rx-duplicate` message on such a frame has a button that does the same. |
+| **Devices** | The device list on a bus page. **+ Device** adds a device to the file that describes the bus. **+ Device in a new file** asks for a file, `devices/<name>.yaml` relative to the map by default, makes it with the device (`mapcan: 1`, `part_of` and the bus by name; the device is named after the file when that name is a free identifier on the bus) and adds it to `include` of the map: one undo step, and **Save** writes both files. A map edited by several people can keep one file per device this way, so changes to different devices do not meet in one file. Deleting such a device deletes its file, left empty, and its line of `include` (on Save; Ctrl+Z brings them back). |
+| **Receives** | On a device page: the bus frames the device receives (its own RX frames and other devices' frames that list it as a receiver), with their senders. Below it, **Transmits frames of other devices** lists the frames it sends on behalf of other devices (`sender`). Both are computed from the frames; click a row to jump to the frame. On a frame page, **Receivers** are toggled on and off; renaming a device updates them and `sender`. ✕ in a row of another device's frame removes the device from its receivers. On an RX frame, **Frame of another device** picks a frame that is already described at its sender: the device is added to that frame's receivers and its own copy is removed (Ctrl+Z undoes it). The `rx-duplicate` message on such a frame has a button that does the same. |
 | **Values / Flags** | Enum and bit field tables: value (decimal or `0x…`), name, description. **+ Flag** adds a row without leaving the signal page. |
 | **Validation** (bottom) | The same rules as `mapcan validate`. Click a message to jump to the node (or, on the YAML tab, to the line). While the YAML tab holds text that is not applied yet (for example, with a syntax error), the panel lists the messages for that text and marks them **YAML text not applied**. |
-| **YAML** | Edit the whole file as text. The text is validated as you type: lines with problems are marked in the gutter (hover a line number to read the message), and the first syntax error is shown in the YAML toolbar; click it to jump to its line. Once the text parses, it is applied automatically after a short pause, so the tree and the editor follow your typing; a whole run of typing is one undo step. Switching to the editor applies what is left (it stays on the YAML tab if there is a syntax error). Renaming a device in the text also updates `sender` and `receivers` of the bus frames, as renaming in the form does. Tab and Shift+Tab indent and outdent the selected lines, Enter keeps the indentation (one level deeper after `key:`), Backspace after spaces goes back to the previous tab stop (2 spaces); press Esc first to move focus with Tab. Ctrl+Enter applies the edit at once. While you type a key, a list offers the fields allowed at that place that are not set yet (required ones first), with the field description from the format schema; after `key:` it offers the values of enumerations (`encoding`, `protocol`, `byte_order`, `true`/`false`…). The same works inside a one-line `{...}` mapping (after `{` and after `, `), and a new `- ` list item also offers `{ }` to write the item on one line. Arrows choose, Enter or Tab inserts (a list or object field also opens its first level), Esc closes, Ctrl+Space shows the list on an empty line. |
+| **YAML** | Edit the whole file as text. The text is validated as you type: lines with problems are marked in the gutter (hover a line number to read the message), and the first syntax error is shown in the YAML toolbar; click it to jump to its line. Once the text parses, it is applied automatically after a short pause, so the tree and the editor follow your typing; a whole run of typing is one undo step. Switching to the editor applies what is left (it stays on the YAML tab if there is a syntax error). Renaming a device in the text also updates `sender` and `receivers` of the bus frames, as renaming in the form does. Tab and Shift+Tab indent and outdent the selected lines, Enter keeps the indentation (one level deeper after `key:`), Backspace after spaces goes back to the previous tab stop (2 spaces); press Esc first to move focus with Tab. Ctrl+Enter applies the edit at once. While you type a key, a list offers the fields allowed at that place that are not set yet (required ones first), with the field description from the format schema; after `key:` it offers the values of enumerations (`encoding`, `protocol`, `byte_order`, `true`/`false`…). The same works inside a one-line `{...}` mapping (after `{` and after `, `), and a new `- ` list item also offers `{ }` to write the item on one line. Arrows choose, Enter or Tab inserts (a list or object field also opens its first level), Esc closes, Ctrl+Space shows the list on an empty line. A map with included files (`include`) shows one file at a time: a node selected in the tree opens the file it is written in (a device of `devices/node.yaml`, a frame where its sender describes it), with the node's lines highlighted, and the list in the YAML toolbar switches between the map and its files (• marks a file with unsaved edits). The text of an included file is edited and applied the same way and goes to that file; **Save** writes it. On the editor tab, **Open the YAML of …** in the note above a node of an included file opens it. |
 | **Export** | Documents (PDF, HTML, Markdown, Excel) and development formats (DBC, C, Python), generated from the current state, including unsaved changes. Clicking a document opens a preview; for PDF, the template is chosen there: `mapcan` or ESKD (see [templates.md](templates.md)). ↓ on the right downloads the file directly. The document language (English or Russian; the map's language by default) is chosen in the menu and in the preview. The ESKD template is always in Russian. |
 | **Layout and document details** | In the document properties: logo (file upload), designation, letter, organization, city, title block signatures, approval blocks. |
 | **Git → Compare versions…** | Diffs the current map against a git revision (HEAD, a tag or a commit) or an uploaded file: changes to frames, signals, values and flags. **Add to history** writes the changelog into `document.history` and bumps the version. |
@@ -177,8 +180,9 @@ available at `http://127.0.0.1:8765/api/docs`.
 | POST | `/api/file/open`, `/api/file/new`, `/api/file/example`, `/api/file/save_as`, `/api/file/close` | File operations; `409 unsaved` means there are unsaved changes (pass `force: true` to proceed) |
 | GET | `/api/state` | Text, data, computed layout and diagnostics |
 | POST | `/api/ops` | `{"ops": [...]}`: apply operations atomically |
-| POST | `/api/text` | Replace the YAML text |
-| POST | `/api/check` | `{"text": ...}`: validate text without applying it; returns `{diagnostics}` |
+| POST | `/api/device_file` | `{"bus": ["buses", 0], "device": {...}, "file": "devices/node.yaml"}`: a new device in a new file, added to `include` |
+| POST | `/api/text` | `{"text": ..., "file": null}`: replace the YAML text of the map, or of an included file (`file`, relative to the map) |
+| POST | `/api/check` | `{"text": ..., "file": null}`: validate text without applying it; returns `{diagnostics}` (a message about an included file has `part`: its file, line and column) |
 | POST | `/api/undo`, `/api/redo` | Edit history |
 | POST | `/api/save` | `{"force": false}`; `409` means the file changed on disk |
 | POST | `/api/reload` | Reload the file from disk |

{mapcan-0.23.0 → mapcan-0.23.2}/examples/minimal.yaml

@@ -66,12 +66,11 @@ buses:
                 offset: -20
                 unit: °C
 
-              - name: speed           # big-endian: byte 5 is the high byte, byte 6 the low byte
+              - name: speed           # two bytes, little-endian (CANopen): byte 5 is the low byte
                 description: Speed
                 encoding: scaled
                 byte: 5
                 byte_length: 2
-                byte_order: big_endian
                 unit: rpm
 
               - name: counter         # arbitrary position: bits 56..59

{mapcan-0.23.0 → mapcan-0.23.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapcan"
-version = "0.23.0"
+version = "0.23.2"
 description = "A YAML map of CAN signals as the single source of truth: validation, Excel/PDF/Markdown/HTML, DBC, C/Python code"
 # readme: built from README.md with absolute links for PyPI (see fancy-pypi-readme below)
 dynamic = ["readme"]

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/__init__.py

@@ -1,6 +1,6 @@
 """mapcan: a YAML signal map as the single source of truth."""
 
-__version__ = "0.23.0"
+__version__ = "0.23.2"
 
 from .loader import load, loads  # noqa: E402
 from .model import MapCan  # noqa: E402

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/cli.py

@@ -261,7 +261,7 @@ def fmt(
     paths: list[Path] = typer.Argument(..., exists=True, dir_okay=False, help=_("Map files.")),
     check: bool = typer.Option(False, "--check", help=_("Do not write; exit code 1 if a file is not formatted.")),
 ) -> None:
-    from .fmt import FmtError, format_text
+    from .fmt import FmtError, format_text, position_notes
 
     unformatted, failed = [], False
     for f in _with_included(paths):
@@ -272,6 +272,11 @@ def fmt(
             typer.secho(f"{f}: {e}", fg=typer.colors.RED, err=True)
             failed = True
             continue
+        if check:
+            # Positions in another notation than the editors write (#117): a note, the map stays valid
+            for line, name, keys in position_notes(text):
+                typer.echo(_("{file}:{line}: note: signal {name!r}: the editors write its position as {keys}",
+                             file=f, line=line, name=name, keys=keys))
         if new == text:
             continue
         unformatted.append(f)

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/fmt.py

@@ -315,3 +315,31 @@ def format_text(text: str) -> str:
                         or new.count("#") != text.count("#")):
         raise FmtError(_("cannot format: the result would read differently; the file is left as it is"))
     return new
+
+
+def position_notes(text: str) -> list[tuple[int, str, str]]:
+    """Signals whose position is not written in the canonical notation the editors use (#117): (line from 1, signal,
+    the canonical keys as YAML). ``mapcan fmt`` does not rewrite them: they are reported by ``--check`` only."""
+    from .web.yamlops import canonical_position
+
+    try:
+        doc = make_yaml(text).load(text)
+    except Exception:  # noqa: BLE001 — not YAML: format_text reports it
+        return []
+    out = []
+
+    def frames(node: Any) -> list:
+        items = node.get("frames") if isinstance(node, CommentedMap) else None
+        return items if isinstance(items, CommentedSeq) else []
+
+    buses = doc.get("buses") if isinstance(doc, CommentedMap) else None
+    for bus in buses if isinstance(buses, CommentedSeq) else []:
+        devices = bus.get("devices") if isinstance(bus, CommentedMap) else None
+        owners = [bus, *(devices if isinstance(devices, CommentedSeq) else [])]
+        for frame in (f for o in owners for f in frames(o)):
+            signals = frame.get("signals") if isinstance(frame, CommentedMap) else None
+            for sig in signals if isinstance(signals, CommentedSeq) else []:
+                if (keys := canonical_position(sig)) is not None:
+                    written = ", ".join(f"{k}: {v}" for k, v in keys.items())
+                    out.append((sig.lc.line + 1, str(sig.get("name", "?")), written))
+    return out

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/launcher.py

@@ -252,7 +252,7 @@ def run(path: Path | None = None, *, window: bool = True, readonly: bool = False
 
     app = create_app(session, cwd=cwd.resolve(), readonly=readonly, check_updates=check_updates,
                      instance_token=token if single_instance else None, on_activate=on_activate,
-                     allowed_hosts=LOCAL_HOSTS)
+                     allowed_hosts=LOCAL_HOSTS, mode="app")
     server = ServerThread(app, host, port)
     try:
         server.start()

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/locale/ru.py

@@ -234,6 +234,8 @@ RU: dict[str, str] = {
         "direction кадра {name!r} противоречит его функции CANopen или отправителю: удалите его и укажите в sender "
         "устройство, которое передаёт кадр",
     "CANopen frame type on a non-CANopen bus": "Тип кадра CANopen на шине не CANopen",
+    "Big-endian signal on a CANopen or J1939 bus (they carry little-endian data)":
+        "Сигнал big-endian на шине CANopen или J1939 (они передают данные little-endian)",
     "sdo description on a frame that is not sdo_tx/sdo_rx": "Описание sdo у кадра не типа sdo_tx/sdo_rx",
     "Duplicate SDO exchange (command, index, subindex)": "Повтор SDO-обмена (команда, индекс, субиндекс)",
     "Name does not match the style rule (lint)": "Имя не соответствует правилу стиля (lint)",
@@ -356,6 +358,16 @@ RU: dict[str, str] = {
     "short label {short!r} is already used by device {other!r}": "обозначение {short!r} уже у устройства {other!r}",
     "frame {name!r} differs from {other!r} only in case: their C macros will collide":
         "кадр {name!r} отличается от {other!r} только регистром: в C-коде их макросы совпадут",
+    "Set the bitrate of the bus to estimate its load.": "Задайте скорость шины (bitrate), чтобы оценить её загрузку.",
+    "Set data_bitrate to estimate the load: frames with bit rate switching send their data at it.":
+        "Задайте data_bitrate, чтобы оценить загрузку: кадры с переключением скорости передают данные на ней.",
+    "Bus load unknown: no frame has a cycle or a minimum interval.":
+        "Загрузка неизвестна: ни у одного кадра нет периода или минимального интервала.",
+    "Estimated bus load: {load}": "Расчётная загрузка шины: {load}",
+    "At least: {counted} of {total} frames are counted; frames without a cycle or a minimum interval are not.":
+        "Не меньше: учтено кадров {counted} из {total}; кадры без периода и минимального интервала не учитываются.",
+    "Frames sent on an event are counted at their minimum interval, with worst-case bit stuffing.":
+        "Кадры по событию учитываются с минимальным интервалом, bit stuffing — по худшему случаю.",
     "estimated load of bus {bus!r} is {load:.0f}% (frames counted: {count}, {bitrate} bit/s; event frames at their "
     "minimum interval); keep it at or below {limit}%":
         "расчётная загрузка шины {bus!r} — {load:.0f} % (учтено кадров: {count}, {bitrate} бит/с; кадры по событию — "
@@ -470,7 +482,7 @@ RU: dict[str, str] = {
     "{name!r}: subindex without index": "{name!r}: subindex без index",
     "{name!r}: index {index:#06x} is outside the manufacturer and profile areas (0x2000..0x9FFF)":
         "{name!r}: индекс {index:#06x} вне областей производителя и профилей (0x2000..0x9FFF)",
-    "{name!r}: CANopen PDOs carry little-endian data": "{name!r}: PDO CANopen передаёт данные little-endian",
+    "{name!r}: {protocol} carries little-endian data": "{name!r}: {protocol} передаёт данные little-endian",
     "object {index:04X}:{sub:02X} is already mapped by {other}": "объект {index:04X}:{sub:02X} уже у сигнала {other}",
     "CANopen: index of the dictionary object mapped into the PDO.":
         "CANopen: индекс объекта словаря, отображённого в PDO.",
@@ -602,6 +614,12 @@ RU: dict[str, str] = {
     "could not save settings: {error}": "не удалось сохранить настройки: {error}",
     "file not found: {path}": "файл не найден: {path}",
     "file already exists: {path}": "файл уже существует: {path}",
+    "Enter the name of the file": "Введите имя файла",
+    "the name of an included file must end with .yaml or .yml":
+        "имя включаемого файла должно оканчиваться на .yaml или .yml",
+    "the path of an included file is relative to the map": "путь включаемого файла указывается относительно карты",
+    "include of the map is not a list": "include карты — не список",
+    "Save the map to a file first.": "Сначала сохраните карту в файл.",
     "{fmt} export error: {error}": "ошибка экспорта {fmt}: {error}",
     "the file is not UTF-8 encoded": "файл не в UTF-8",
     "could not read {name}: {error}": "не удалось прочитать {name}: {error}",
@@ -672,6 +690,10 @@ RU: dict[str, str] = {
     "Bit": "Бит",
     "Flag": "Флаг",
     "Byte": "Байт",
+    "Signal": "Сигнал",
+    "Position": "Положение",
+    "Size": "Размер",
+    "bit": "бит",
     "Export canceled: the map has errors ({errors}). Fix them and try again.":
         "Экспорт отменён: в карте есть ошибки ({errors}). Исправьте их и повторите.",
     "Save the map to a file before exporting.": "Сохраните карту в файл перед экспортом.",
@@ -866,6 +888,8 @@ RU: dict[str, str] = {
     "Do not write; exit code 1 if a file is not formatted.":
         "Не записывать; код выхода 1, если файл не отформатирован.",
     "{file}: not formatted, run mapcan fmt": "{file}: не отформатирован, выполните mapcan fmt",
+    "{file}:{line}: note: signal {name!r}: the editors write its position as {keys}":
+        "{file}:{line}: примечание: сигнал {name!r}: редакторы записывают его положение как {keys}",
     "part_of: the map {map!r} is not found": "part_of: карта {map!r} не найдена",
     "part_of: the map {map!r} does not include this file": "part_of: карта {map!r} не включает этот файл",
     "the map {map!r} has {n} error(s) outside this file: open it to see them":

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/lsp/analysis.py

@@ -21,7 +21,7 @@ from ..docmodel import fmt_num
 from ..i18n import _, normalize_language
 from ..loader import PART_OF_RE, LoadResult, SourceMap, loads, paused_gc
 from ..model import MapCan, enum_entries
-from ..validate import bus_load_text, check
+from ..validate import bus_load_note, bus_load_text, check
 
 Pos = tuple[int, int]          # 0-based (line, column)
 Path_ = tuple
@@ -446,7 +446,8 @@ def device_label(d: dict, lang: str) -> str:
 
 
 def map_tree(a: Analysis) -> list[dict]:
-    """Nodes: kind, label, ident, description, dir (frames), from (received frames), range, selection, children.
+    """Nodes: kind, label, ident, description, dir (frames), from (received frames), to (frames the device sends,
+    described at their receiver), range, selection, children.
 
     Labels are as in the web editor's tree: titles in the document language, the identifier (``ident``)
     only if there is no title. Built from the raw YAML; computed IDs and bits come from the model if the map parses.
@@ -484,7 +485,7 @@ def map_tree(a: Analysis) -> list[dict]:
     def model(path: Path_):
         return _find(a.map, path) if a.map is not None else None
 
-    def frame_node(f: dict, path: Path_) -> dict | None:
+    def frame_node(f: dict, path: Path_, devices: list) -> dict | None:
         loc = rng(path)
         if loc is None:
             return None
@@ -494,7 +495,12 @@ def map_tree(a: Analysis) -> list[dict]:
             sub = f"PGN {_hexw(f['pgn'], 4)}"
         elif isinstance(rf, M.Frame) and rf.can_id is not None:
             sub = _hex(rf.can_id, rf.extended)
-        node = {"kind": "frame", "label": display_name(f, lang), "ident": name_of(f), "description": sub,
+        label = display_name(f, lang)
+        # A frame described at its receiver (sender: another device): the label names the sender, as a link does
+        if isinstance(rf, M.Frame) and rf.device is not None and rf.sender_name not in (None, rf.device.name):
+            sender = next((x for x in devices if x.get("name") == rf.sender_name), None)
+            label = f"{device_label(sender, lang) if sender else rf.sender_name} · {label}"
+        node = {"kind": "frame", "label": label, "ident": name_of(f), "description": sub,
                 "dir": rf.direction if isinstance(rf, M.Frame) and rf.device is not None else None,
                 "children": [], **loc}
         for si, s in enumerate(_items(f.get("signals"))):
@@ -528,13 +534,15 @@ def map_tree(a: Analysis) -> list[dict]:
         if (bl := rng(bp)) is None:
             continue
         mbus = model(bp)
-        # The estimated bus load ("≥" when frames without a known period are not counted)
+        # The estimated bus load ("≥" when frames without a known period are not counted), and what it is
+        is_bus = isinstance(mbus, M.Bus)
         bnode = {"kind": "bus", "label": display_name(bus, lang), "ident": name_of(bus),
-                 "description": bus_load_text(mbus) if isinstance(mbus, M.Bus) else "", "children": [], **bl}
+                 "description": bus_load_text(mbus) if is_bus else "",
+                 "load_note": bus_load_note(mbus) if is_bus else "", "children": [], **bl}
+        devices = _items(bus.get("devices"))
         for fi, f in enumerate(_items(bus.get("frames"))):
-            if (fn := frame_node(f, bp + ("frames", fi))) is not None:
+            if (fn := frame_node(f, bp + ("frames", fi), devices)) is not None:
                 bnode["children"].append(fn)
-        devices = _items(bus.get("devices"))
         for di, d in enumerate(devices):
             dp = bp + ("devices", di)
             if (dl := rng(dp)) is None:
@@ -544,7 +552,7 @@ def map_tree(a: Analysis) -> list[dict]:
             dnode = {"kind": "device", "label": display_name(d, lang), "ident": name_of(d), "description": sub,
                      "children": [], **dl}
             for fi, f in enumerate(_items(d.get("frames"))):
-                if (fn := frame_node(f, dp + ("frames", fi))) is not None:
+                if (fn := frame_node(f, dp + ("frames", fi), devices)) is not None:
                     dnode["children"].append(fn)
             # Frames of other devices that the device receives: links after its own; the frame's title may
             # not tell whose it is, so the link's label names the sender
@@ -561,6 +569,20 @@ def map_tree(a: Analysis) -> list[dict]:
                     "ident": rf.name, "dir": "rx", "from": sender_label or rf.sender_name or "",
                     "description": _hex(rf.can_id, rf.extended) if rf.can_id is not None else "",
                     "children": [], **loc})
+            # Frames the device sends that are described at their receiver (sender: this device): links too, the
+            # label names the device they are described at
+            for rf in mbus.all_frames() if isinstance(mbus, M.Bus) else []:
+                if (rf.device is None or rf.device.name == d.get("name") or rf.sender_name != d.get("name")
+                        or (loc := rng(rf._path)) is None):
+                    continue
+                owner = next((x for x in devices if x.get("name") == rf.device.name), None)
+                owner_label = device_label(owner, lang) if owner else rf.device.name
+                frame = raw_at_path(raw, rf._path)
+                title = display_name(frame if isinstance(frame, dict) else {"name": rf.name}, lang)
+                dnode["children"].append({
+                    "kind": "frame", "label": f"{owner_label} · {title}", "ident": rf.name, "dir": "tx",
+                    "to": owner_label, "description": _hex(rf.can_id, rf.extended) if rf.can_id is not None else "",
+                    "children": [], **loc})
             bnode["children"].append(dnode)
         out.append(bnode)
     return out
@@ -765,7 +787,12 @@ def frame_markdown(frame: M.Frame) -> str:
 
 
 def frame_layout(frame: M.Frame) -> str:
-    """Bit map of a frame as a markdown table: rows are bytes, columns are bits 7…0."""
+    """The signals of a frame and its bit map as markdown tables.
+
+    The list of signals comes first: a hover shows the top of a long text, and the numbers in the map mean nothing
+    without it. Rows of the map are bytes, columns are bits 7…0; consecutive bytes with the same owners are one row,
+    so a frame of 64 bytes stays short.
+    """
     sigs = frame.layout
     if not sigs or frame.length == 0:
         return ""
@@ -773,13 +800,21 @@ def frame_layout(frame: M.Frame) -> str:
     for i, s in enumerate(sigs, 1):
         for b in occupied_bits(s.start_bit or 0, s.bit_length or 1, s.byte_order == "big_endian"):
             cells.setdefault(b, []).append(i)
+    legend = ["| # | " + _("Signal") + " | " + _("Position") + " | " + _("Size") + " |", "|---:|---|---|---:|"]
+    legend += [f"| {i} | `{s.name}` | {signal_bits(s)} | {s.bit_length or 1} " + _("bit") + " |"
+               for i, s in enumerate(sigs, 1)]
     rows = ["| " + _("Byte") + " | " + " | ".join(str(b) for b in range(7, -1, -1)) + " |",
             "|---:|" + ":-:|" * 8]
-    for byte in range(frame.length):
-        row = [",".join(map(str, cells.get(byte * 8 + bit, []))) or "·" for bit in range(7, -1, -1)]
-        rows.append(f"| {byte} | " + " | ".join(row) + " |")
-    legend = "\n".join(f"{i}. `{s.name}` — {signal_bits(s)}" for i, s in enumerate(sigs, 1))
-    return "\n".join(rows) + "\n\n" + legend
+    owners = [tuple(",".join(map(str, cells.get(byte * 8 + bit, []))) or "·" for bit in range(7, -1, -1))
+              for byte in range(frame.length)]
+    first = 0
+    for byte in range(1, frame.length + 1):
+        if byte < frame.length and owners[byte] == owners[first]:
+            continue
+        label = str(first) if byte - 1 == first else f"{first}–{byte - 1}"
+        rows.append(f"| {label} | " + " | ".join(owners[first]) + " |")
+        first = byte
+    return "\n".join(legend) + "\n\n" + "\n".join(rows)
 
 
 # --------------------------------------------------------------------------- #

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/lsp/edits.py

@@ -718,16 +718,8 @@ def add_node(a: Analysis, path: Path_, kind: str) -> TextChange | None:
                                             ("title", yaml_text(_default_title(a, "Шина", "Bus", buses))),
                                             ("protocol", "can")])
     if kind == "device" and len(path) == 2:
-        devices = raw_at(a, path + ("devices",)) or []
-        fields = [("name", _unique("device", _names(devices))),
-                  ("title", yaml_text(_default_title(a, "Устройство", "Device", devices)))]
-        protocol = (raw_at(a, path) or {}).get("protocol", "canopen")
-        if protocol == "canopen" and (nid := _free_number([d.get("node_id") for d in devices
-                                                          if isinstance(d, dict)], 1, 127)):
-            fields.append(("node_id", f"0x{nid:02X}"))
-        elif protocol == "j1939" and (sa := _free_number([d.get("address") for d in devices
-                                                         if isinstance(d, dict)], 0, 253)) is not None:
-            fields.append(("address", f"0x{sa:02X}"))
+        device = new_device(a, raw_at(a, path) or {}, raw_at(a, path + ("devices",)) or [])
+        fields = [(k, f"0x{v:02X}" if k in ("node_id", "address") else yaml_text(v)) for k, v in device.items()]
         return append_item(a, path, "devices", fields)
     if kind == "frame" and path and path[0] == "buses" and len(path) in (2, 4):
         return append_item(a, path, "frames", _new_frame(a, path))
@@ -736,6 +728,51 @@ def add_node(a: Analysis, path: Path_, kind: str) -> TextChange | None:
     return None
 
 
+def new_device(a: Analysis, bus: dict, devices: list) -> dict:
+    """Fields of a new device of a bus with these devices: a free name, title and CANopen node ID or J1939
+    address."""
+    out = {"name": _unique("device", _names(devices)),
+           "title": _default_title(a, "Устройство", "Device", devices)}
+    protocol = bus.get("protocol", "canopen")
+    if protocol == "canopen" and (nid := _free_number([d.get("node_id") for d in devices
+                                                      if isinstance(d, dict)], 1, 127)):
+        out["node_id"] = nid
+    elif protocol == "j1939" and (sa := _free_number([d.get("address") for d in devices
+                                                     if isinstance(d, dict)], 0, 253)) is not None:
+        out["address"] = sa
+    return out
+
+
+def device_file(a: Analysis, bus_path: Path_, file: str | None) -> dict:
+    """A new device of a bus in a file of its own (#136). Without ``file``: {file} with the default name of the
+    file. With it: {device, target, text, ops}: the device, the new file and its text, and the operations that
+    add it to ``include`` of the map (paths of the map). ValueError: why it cannot be made."""
+    from ..web.devicefile import (
+        default_device_file,
+        device_file_target,
+        device_file_text,
+        include_ops,
+        named_after_file,
+    )
+
+    data = a.data if isinstance(a.data, dict) else {}
+    bus = raw_at_path(data, bus_path)
+    if len(bus_path) != 2 or not isinstance(bus, dict) or not isinstance(bus.get("name"), str):
+        raise ValueError(_("path not found: {path}", path=list(bus_path)))
+    main = a.result.source.file
+    if not main or not Path(main).is_file():
+        raise ValueError(_("Save the map to a file first."))
+    devices = [d for d in bus.get("devices") or [] if isinstance(d, dict)]
+    device = new_device(a, bus, devices)
+    if file is None:
+        return {"file": default_device_file(device["name"])}
+    target, line = device_file_target(Path(main), file)
+    device = named_after_file(device, target, _names(devices))
+    raw = a.result.raw if isinstance(a.result.raw, dict) else {}
+    return {"device": device, "target": target, "ops": include_ops(raw.get("include"), line),
+            "text": device_file_text(Path(main), target, bus["name"], {**device, "frames": []})}
+
+
 class EditRefused(ValueError):
     """An edit that cannot be made; the message says why."""
 
@@ -801,10 +838,10 @@ def _add_signal(a: Analysis, path: Path_) -> TextChange | None:
     start, length, grown = place
     signals = raw_at(a, path + ("signals",)) or []
     fields = [("name", _unique("signal", _names(signals))), ("encoding", "raw")]
-    if length == 8 and start % 8 == 0:
-        fields += [("byte", str(start // 8)), ("byte_length", "1")]
-    else:
-        fields += [("start_bit", str(start)), ("bit_length", str(length))]
+    # The position in the notation the other editors write (#117)
+    from ..web.yamlops import layout_keys
+
+    fields +=[(k, str(v)) for k, v in layout_keys(start, length, False, "raw").items()]
     change = append_item(a, path, "signals", fields)
     if change is None or grown is None:
         return change
@@ -1208,6 +1245,8 @@ def set_field(a: Analysis, path: Path_, value) -> list[Edit]:
         return [minimal_edit(a.text, apply_ops(a, [op]))]
     if key == "canopen" and node_kind(path[:-1]) == "frame":
         return _set_frame_type(a, path, value)
+    if key == "sender" and node_kind(path[:-1]) == "frame":
+        return _set_sender(a, path, value)
     if not isinstance(raw_at(a, path[:-1]), dict):
         # A field of a nested mapping that does not exist yet (value.name of an SDO): the mapping is added with it
         parent = path[:-1]
@@ -1270,6 +1309,18 @@ def _set_frame_type(a: Analysis, path: Path_, value) -> list[Edit]:
     return edits
 
 
+def _set_sender(a: Analysis, path: Path_, value) -> list[Edit]:
+    """The sender of a frame; a device named as the sender does not receive the frame, so it leaves the receivers."""
+    receivers = raw_at(a, path[:-1] + ("receivers",))
+    if not value or not isinstance(receivers, list) or value not in receivers:
+        return _set_plain(a, path, value)
+    rest = [r for r in receivers if r != value]
+    ops = [{"op": "set", "path": list(path), "value": value},
+           {"op": "set", "path": list(path[:-1] + ("receivers",)), "value": rest} if rest
+           else {"op": "remove", "path": list(path[:-1] + ("receivers",))}]
+    return [minimal_edit(a.text, apply_ops(a, ops))]
+
+
 def _set_plain(a: Analysis, path: Path_, value) -> list[Edit]:
     """A scalar field without special rules: a new value, or ``None`` or "" to remove the key."""
     current = raw_at(a, path)

{mapcan-0.23.0 → mapcan-0.23.2}/src/mapcan/lsp/server.py

@@ -424,7 +424,11 @@ def edit_command(ls: MapcanServer, *args) -> dict:
     {error} (a signal that has no room in its frame) or {}.
 
     The edit goes to the file the node is written in (for a new node, its owner's; a new bus goes to the main
-    file): ``uri`` is there when that is another file of the map than the document."""
+    file): ``uri`` is there when that is another file of the map than the document. An included file that a
+    delete leaves adding nothing to the map (a device's own file, #136) goes instead: {delete: its uri, edits,
+    others}, the edits removing it from ``include`` (as mapcan.lsp.ops)."""
+    from ..web.devicefile import exclude_ops, part_is_empty
+
     params = _arg(args)
     uri = params.get("uri", "")
     a = ls.analysis(uri) if uri else None
@@ -449,6 +453,17 @@ def edit_command(ls: MapcanServer, *args) -> dict:
         change = None
     if change is None:
         return {}
+    if action == "delete" and view.own_file and part_is_empty(change.text):
+        from ..web.yamlops import OpError
+
+        raw = a.result.raw if isinstance(a.result.raw, dict) else {}
+        main = Path(a.result.source.file or "")
+        try:
+            out = ls.routed(a, exclude_ops(raw.get("include"), main, Path(view.own_file)), "edits")
+        except OpError:
+            out = {}
+        if out.get("edits") or out.get("others"):
+            return {**out, "delete": _file_uri(view.own_file)}
     e = E.minimal_edit(view.text, change.text)
     out = {"edit": {"range": [*e.start, *e.end], "text": e.text}, "cursor": list(change.cursor)}
     if view is not a:
@@ -456,6 +471,33 @@ def edit_command(ls: MapcanServer, *args) -> dict:
     return out
 
 
+@server.command("mapcan.lsp.deviceFile")
+def device_file_command(ls: MapcanServer, *args) -> dict:
+    """A new device of a bus in a file of its own (#136). Argument: {uri, path: path of the bus, file}.
+    Without ``file``: {file}, the default name of the file relative to the map. With it: {create: {uri, text},
+    cursor: the device's name in the new file, edits and others: the line of ``include`` (as mapcan.lsp.ops)},
+    or {error}."""
+    from ..web.yamlops import OpError
+
+    params = _arg(args)
+    a = ls.analysis(params.get("uri", ""))
+    if a is None:
+        return {"error": _("The document is not a mapcan map.")}
+    file = params.get("file")
+    try:
+        made = E.device_file(a, tuple(params.get("path") or ()), None if file is None else str(file))
+        if file is None:
+            return made
+        out = ls.routed(a, made["ops"], "edits")
+    except (ValueError, OpError) as e:
+        return {"error": str(e)}
+    lines = made["text"].splitlines()
+    # The device is the last named item: the bus comes before it
+    line = max(i for i, ln in enumerate(lines) if ln.lstrip().startswith("- name:"))
+    return {**out, "create": {"uri": made["target"].as_uri(), "text": made["text"]},
+            "cursor": [line, lines[line].index("name:") + len("name: ")]}
+
+
 def _params(params) -> tuple[str, tuple]:
     """(uri, path) from the request parameters {textDocument: {uri}, path}."""
     get = (lambda o, k: o.get(k)) if isinstance(params, dict) else (lambda o, k: getattr(o, k, None))