The Chisel Method: how we make parser development finish.

Chisel is a way of running a parser project, not a product and not a piece of software. We use it on every parser we build, we have published it, and we teach it to client teams who take over maintenance afterwards. Everything below is the method itself, in the order you would encounter it.

The problem it solves

Ask three people when a parser for a legacy language is finished and you will get three answers. That is not carelessness; it is that the usual answers do not survive contact with the work. “When it handles the language” assumes the language is written down. “When it handles our code” assumes somebody has decided which code. “When we stop finding bugs” has no end at all.

The obvious alternative is to make the specification the goal: support everything the language reference describes. It sounds rigorous and it fails for three specific reasons.

• Many legacy languages have no written specification. The languages people most need parsers for are exactly the ones that were never standardized, or whose vendor documentation described a dialect nobody actually runs.
• Progress against a specification cannot be measured. “Three of twenty chapters covered, so we are at fifteen per cent” is not a measurement. Verifying that a chapter is genuinely covered is a manual reading exercise, and it cannot be automated.
• Specifications are open to interpretation. The engineering team and the client can read the same paragraph and disagree about what conformance means — usually at the point where one of them wants to declare the work complete.

A parser that is ninety-five per cent right is worthless, because you cannot tell which five per cent it is wrong about. So the goal has to be something a machine can check.

The two checks

Everything in the method rests on these, so they are worth stating precisely. Both are run against the validation set agreed in step 01.

• Check one — parse every example. The parser produces a syntax tree for every file in the validation set. This proves it can read the whole set, with nothing excluded for being inconvenient.
• Check two — validate the tree for every construct. The abstract syntax tree built for each language construct in the set is inspected and confirmed correct. This proves the model is right, not merely that parsing did not throw.

When both pass, the parser is complete. The first version is delivered and the maintenance phase begins. If you later want files added to the validation set, that is not a bug report — it is a new goal, agreed as one, with its own scope and its own price.

Frictionless development

The second pillar is about the daily experience of building the parser, and it exists because a method that produces the right answer slowly is not much of a method. Two principles govern it.

• The team always knows what to do next. At any moment the current phase and the current failing item determine the next task. Nobody has to stop and decide what the priority is, because the checks decide it.
• The tooling removes the repetitive parts. An issue reported in a tool navigates straight to the offending point in the source. If running the parser requires a rebuild, the rebuild starts by itself. Every step that a machine can take is taken by a machine, so the engineers spend their time on the constructs that are genuinely hard.

Because both phases are measured against a fixed set, progress through the whole process can be expressed as a percentage that means something. We use it for planning, and we report it to you rather than describing the work as “going well”.

Frictionless adoption

A parser is never the end product. It is a component in a pipeline, and it produces value only once it is inside one. The third pillar is the work of getting it there, and it has three parts.

• Connectivity. Every parser we build is based on Starlasu and produces an abstract syntax tree in a shared shape, so our parsers interoperate with each other and with the ones already in our catalog. The trees support LionWeb, the open interoperability standard, and they are reachable through bindings from Java, Kotlin, Python, TypeScript and C# — so the team consuming the parser does not have to adopt the language it was written in.
• Documentation. The documentation is generated from the parser rather than written alongside it, which is what keeps it describing the tree you actually receive after the third round of changes.
• Teachability. The method is designed to be taught. That means we can keep a team able to maintain your parser, and it means we can train your own team to take it over. Either way you are not dependent on the availability of one person.

“The supplied software has vastly increased the quality of our development and made us far more efficient. Compared to other projects this was very good, with no unnecessary overhead during the project. The communication was excellent and the consistent use of GitHub was great as we knew the status of all bug fixes.”

What it changes for you

• The goal is agreed before the money is. Scope arguments in parser projects almost always come from a goal that was never written down. Here it is written down, in the form of a file list and two checks, before development starts.
• Progress is a number you can read. Not a status color and not a narrative. The proportion of the validation set that parses, and the proportion of constructs whose trees have been validated.
• Integration is part of the job, not a follow-on quote. Connectivity, documentation and handover are inside the method rather than outside it.
• You are not locked to us afterwards. Starlasu is Apache-2.0 and public, the documentation describes the real tree, and the method is teachable — which is what makes taking maintenance in-house a real option rather than a polite fiction.

Honest limits

• No validation set, no method. If you cannot supply representative files, Chisel has nothing to measure against and we cannot give you a fixed goal. This is the one thing that genuinely blocks a start, and it is worth resolving before anything else.
• The set defines the scope, which cuts both ways. A construct that appears nowhere in the validation set is not covered by the goal. That is the honest consequence of having a goal at all, and it is why choosing the set is a step with your name on it too.
• Complete does not mean finished forever. Passing both checks means the first version ships. Real estates keep producing new files; adding them is maintenance, and it is a new goal each time.

If you would rather start from the practice than from the method, the overview pages are Parsers and transpilers, custom parser development and the Language Engines we license. To talk about something other than a parser, use the language engineering discovery form.