feat(dsl): standard library — the map actor & traffic lights (p7-s5) - #101
Merged
Conversation
Translates two more chapters of the §8 standard library into bundled DSL source: §8.12.2's `map` actor and all of §8.15's traffic lights. They land together because `map.traffic_light_groups` and `map.traffic_light_control` are §8.15 types, so pairing the chapters removes a deferral seam. §8.12.2 — the top-level road-network actor with its six fields, the 18 conversion and creation methods §8.12.2.1 prints as `extend map:` prototypes, and the 12 search-space modifiers of §8.12.2.2 in the §7.2.2.2.9 prefixed form. §8.15 — `traffic_light_bulb`, `traffic_light` and `traffic_light_group` with their state and semantic-state methods, `traffic_light_stop_line` as a `route_element`, `traffic_light_phase`/`traffic_light_cycle`, the `traffic_light_controller` actor with its seven §8.15.9 actions, and five enums including the 45-member `bulb_icon`. Adds translation worksheets under docs/dev/stdlib-worksheets/: one line per declaration with the DSL spelling it produced and a note wherever the printed text needed a judgement call. Reading a worksheet is far cheaper than re-reading a chapter, and it is the record a reviewer can check against the specification. Two places where the standard contradicts itself, resolved by asking which surface the rest of the chapter corroborates: - §8.15.4.2.1 prints `extend traffic_light:` for the *group's* `state_equal`, while its heading, its prose and Table 319 all place the method on the group. The lone printed receiver loses. - Table 337 names `set_group_bulb_state`'s first parameter `traffic_light` of type `traffic_light` though its description says "group". The parameter table is what a conforming scenario is written against, so the printed name and type are carried verbatim — the same rule that keeps §8.14.1.3's rounded conversion factors (ADR-0029). Adding the map made `left` reachable from ordinary scenario text, where it is a member of both `side_left_right` and `junction_direction`; §7.3.3's `side_left_right!left` is now required and is pinned. Found while probing the new surface, reported as #100 rather than fixed here: an actor-associated modifier cannot be *applied*, because the parser keeps the actor prefix in the declared name while the application site looks up the bare name. The defect predates this chapter — §8.7's two modifiers have it too — and it is what §8.9's movement modifiers (#46) need fixed first. The declarations are well-formed and are pinned; the broken application is not. 1270 gtest (+11), 184 pytest. The library still checks with zero diagnostics of any severity. Refs #43
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Slices 43e + 43h of #43, paired: the
mapactor'straffic_light_groupsandtraffic_light_controlfields are §8.15 types, so landing the two chapterstogether removes a deferral seam rather than creating one.
What lands
§8.12.2 — the
mapactor. The top-level holder of the abstract roadnetwork: six fields, the 18 conversion and creation methods §8.12.2.1 prints as
extend map:prototypes, and the 12 search-space modifiers of §8.12.2.2 in the§7.2.2.2.9 prefixed form.
§8.15 — traffic lights.
traffic_light_bulb,traffic_lightandtraffic_light_groupwith their state and semantic-state methods,traffic_light_stop_lineas aroute_element,traffic_light_phaseandtraffic_light_cycle, thetraffic_light_controlleractor with its seven§8.15.9 actions, and five enums including the 45-member
bulb_icon.Translation worksheets
New:
docs/dev/stdlib-worksheets/. One file per translated chapter, one lineper declaration — kind, name, base, fields with types, plus a
⚠note whereverthe printed text needed a judgement call.
Most of §8 is printed as parameter tables, so turning a chapter into library
source is a translation and the expensive part is the reading, not the writing.
A worksheet captures that reading once. It is committed because it is the record
a reviewer can check against the specification without re-deriving the mapping,
and because re-reading a worksheet is much cheaper than re-reading a chapter.
Two places the standard contradicts itself
Resolved by asking which surface the rest of the chapter corroborates:
extend traffic_light:for the group'sstate_equal, while its heading, its prose and Table 319 all place the methodon
traffic_light_group. The lone printed receiver loses.set_group_bulb_state's first parametertraffic_lightof type
traffic_light, though its description says "the traffic lightgroup affected". Here the parameter table is the surface a conforming
scenario is written against, so the printed name and type are carried
verbatim — the same rule that keeps §8.14.1.3's rounded conversion factors
(ADR-0029).
A new qualification an author will meet
Adding the map made
leftreachable from ordinary scenario text, where it is amember of both
side_left_right(§8.12.14) andjunction_direction(§8.12.22).§7.3.3 therefore requires
side_left_right!left. Same rule aslane_type!driving, on a word an author is far more likely to reach for; bothhalves are pinned.
Reported, not fixed: #100
Probing the new surface surfaced a resolver defect: an actor-associated modifier
cannot be applied.
my_map.lane_side(...)reports "unknown modifier'lane_side'", because the parser keeps the actor prefix in the declared name
(
map.lane_side) whilecheck_modifier_applicationlooks up the bare name.Unassociated modifiers are unaffected.
It predates this chapter — §8.7's
stationary_object.locationandvehicle.tow_trailerhave it too — and it is what §8.9's movement modifiers(p8-s3, #46) will need fixed first. Filed as #100 rather than folded into a
translation PR. The declarations are well-formed and are pinned by
TheMapModifiersAreAssociatedWithTheMap; nothing pins the broken application,because that is not the behaviour we want to keep.
Tests
frontends/dsl/tests/dsl_stdlib_test.cpp, +11 cases: the traffic-light enums,structs, methods and actions; the stop line's
route_elementparentage; the mapactor's fields, its 18 method signatures and its 12 modifiers; a field sharing
its name with its type; the
leftambiguity in both directions; and anend-to-end scenario in the shape of §8.15.10's examples.
1270 gtest (+11), 184 pytest.
TheBundledLibraryChecksCleanstill assertszero diagnostics of any severity — not zero errors, because a warning inside the
library would appear in every user's output.
Docs:
osc-dsl-coverage.md(the §8.12.2 and §8.15 sub-module rows),frontends/dsl/README.md, and the two worksheets.Refs #43