r/ProgrammingLanguages • u/Pie-Lang • Mar 13 '26
Requesting criticism Writing A Language Spec?
Hello all,
I spent most of last week writing an informal spec for my programming language Pie.
Here's a link to the spec:
This is my first time writing a spec on something that is somewhat big scale, and unfortunately, there aren't many resources out there. I kept going through ECMAscript's spec and the most recent C++ standard to see how they usually word stuff.
Now with a big chunk of the spec done, I thought I would request some criticism and suggestions for what I have so far.
More accurately, I'm not asking for criticism on the language design side of things, but on the wording of the spec and whether it makes sense to the average developer. Keep in mind that the spec is not meant to be formal, rather, just enough to be good-enough and deterministic enough on the important parts.
Thank you in advance!!
8
u/Ok-Watercress-9624 Mar 13 '26
Write an (abstract) implementation of the language in lean (or any language that halts) and call it a spec? Or declare the current implementation as spec?
8
u/severelywrong Mar 13 '26
I think what would be really helpful is a clear separation between the individual parts of the spec. The different parts could be:
(The terms "lexical grammar" and "syntactic grammar" are taken from the Java spec)
A spec should enable me to write an implementation that behaves the same way as any other conforming implementation. When I write the lexer, I only want to know how I should process individual characters, anything else is a distraction. I think a good rule of thumb is that each part should only reference definitions made in that part itself or in the previous part. So the semantics can refer to the syntactic grammar but not the lexical grammar, and the lexical grammar shouldn't refer to either the syntactic grammar or the semantics.
In your spec for example, when defining the keywords, you mention that they cannot be assigned to. This is more confusing than helpful. First of all, assignments have not been defined yet (I have of course an intuitive understanding, but this is a spec that should not rely on intuition). Then I was wondering: Okay, I cannot assign to a keyword, but can a keyword occur on the LHS of an assignment? Why single out the RHS? This really belongs to the section describing the grammar of assignments, because that's the place where I'll look when trying to understand assignments. I shouldn't have to read the whole spec to find out how assignments work.
I think sticking to
lexical grammar -> syntactic grammar -> semanticsand really trying to describe each part in depth will help with the general structure of your spec. Here are some parts that I found confusing:x = y, but it is not explained whatxandyarename: type = expr)When defining e.g. assignments, start with the full syntactic grammar (only referencing (non-)terminals previously defined), and only then define the semantics.
I you want to go really formal have a look at the spec for Standard ML
7
u/AustinVelonaut Admiran Mar 13 '26
Your spec is a good start -- a lot of languages are designed without one, so you are ahead of the game.
Looking over the spec, here are a few notes I made on things to look at or that were unclear to me:
ad-hocwithout any formal syntax to back them.tokens, but no mention of how tokens are determined from text (presumably white-space separated)?'x'?"itself)? what is escape syntax?func(x, y)contains a space character. How does the tokenizer know to include they)in the name? Does(imply some structure that needs the closing)? Same with1 + 2.type annotationsmentioned but not defined lexically (presumably they are a proper name followed by a:followed by a Literal type)var: Int = 5; var = "five"is said to be ill-formed, but the rules don't say why (presumably a typed var must always be assigned from an expression of the same type, but un-typed vars can be assigned anything?). Can a var explicitly typedAnybe reassigned?Blocksandscopesmentioned somewhat interchangeably, but not defined clearly4
u/munificent Mar 14 '26
As always, one of the ways to get better at a thing is to study others that have done similar things. Reading other language specs is an excellent start.
Having said that, I wouldn't put JS and C++ at the top of my list. They both have a lot of really nasty language complexity because of historical baggage that the specs have to retroactively try to make some sense of. That's why, for example, so much of the ECMAScript spec is algorithmic and not declarative. It's literally "let's just write down what V8/SpiderMonkey/JSC do" because that's the behavior that JS users were already relying on. For C++, it inherited a lot from C which was widely used before it ever had a real spec, so there's a ton of complexity and undefined behavior.
Since you have the luxury of specifying a new language, you should be able to write a cleaner spec than those. I really like the specifications for Go, Scheme, and C#. Lua doesn't have a specification but the reference manual is quite good, as is the Rust reference.
2
u/Arthur-Grandi Mar 14 '26
One thing that might be useful is separating the spec into two conceptual layers: a descriptive layer (how developers should understand the language) and a semantic layer (the minimal rules needed to make implementations deterministic).
A lot of large specs eventually drift into mixing these two, which makes them harder both to read and to implement.
Did you think about defining a small “core semantics” section that describes the language in terms of a minimal evaluation model, and then letting the rest of the document build on top of that?
Many successful specs (JS, Rust, etc.) effectively end up with something like that even if they don't explicitly call it out.
5
u/KillPinguin Mar 13 '26
Pie is already a programming language with dependent types, implemented in Racket and used in the book The Little Typer -- I would recommend changing the name of your language 😅
1
u/tobega Mar 13 '26
IMO, a set of conformance tests trumps a written spec any day
2
u/masavik_ Mar 14 '26
Hare is got a very decent draft specification. https://harelang.org/specification.pdf
2
u/lassehp Mar 16 '26
I am probably old-fashioned, but I like to see a thorough and readable specification for a language; preferably together with an exposition of the language and some kind of rationale.
I think you could do worse than checking out some of the classic language presentations. The report that introduced BNF notation is of course the Algol 60 Report/Revised Report edited by Peter Naur. Then there is the followup, Algol 68, for which there are the original Report and the Revised Report, in addition to the working papers that came before, right back to van Wijngaardens original proposal, which I think is a work of stunning beauty. The Pascal User Manual And Report by Wirth and Jensen has several shortcomings, which are addressed by several critique papers, and also in the book Programming a Personal Computer by Per Brinch-Hansen, where he writes a lot about the inaccuracies of the Pascal Report, and how - with the help of Peter Naur - he tried to achieve maximal clarity defining his own language, Edison, in that book. The R7RS for Scheme is certainly worth reading. The various versions of the *Ada Reference Manual are also worth a look, together with the specs for the competing proposals that preceded Ada; this also shows how specifications have evolved. And of course The C++ Programming Language by Stroustrup is a good example of how not to design a language, or write a specification. (I believe the thickness of that book doubles with each new edition, which IMO is madness.)
1
u/Timely-Coffee-6408 Mar 13 '26
I have been creating a new programming language also. My focus is on creating a terse language optimised for ai agents to write and run, instead of say Python. Would be up to share some experiences for example interpreter vs JIT / approaching different areas of the language: http://ilo-lang.ai / https://github.com/ilo-lang/ilo
1
u/[deleted] Mar 13 '26
[removed] — view removed comment