From b3f9cdf372c7cf5a3bbc8590d608ce7e849c3c4b Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Fri, 12 Feb 2021 17:08:55 -0800 Subject: [PATCH] docs: Add statics development documentation Hopefully the new section will be helpful, given that it can be a bit confusing to get started with Statix. With this commit, the background is established and the stage is set to dive into type checking. --- mkdocs.yml | 1 + trans/statics.stx | 48 ++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6726b34..e316a98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: fostr language nav: - README.md - tests/basic.md +- trans/statics.md - implementation.md plugins: diff --git a/trans/statics.stx b/trans/statics.stx index 7772698..fa795fe 100644 --- a/trans/statics.stx +++ b/trans/statics.stx @@ -2,7 +2,53 @@ module statics imports signatures/fostr-sig -// see docs/implementation.md for details on how to switch to multi-file analysis +/** md +Title: Adding Program Analysis with Statix + +## Development of fostr static analysis + +This section is more documentation of Spoofax in general and Statix +in particular than of fostr itself, but is being maintained here in case +it could be either helpful to someone getting started with Statix or +helpful in understanding how the static characteristics of fostr were designed. + +As mentioned in the [Overview](../README.md), I don't like to program and a +corollary of that is never to use a facility unless/until there's a need for +it. So the first few rudimentary passes at fostr simply declared every program +to be "OK" from the point of view of Statix: +```statix +{! "\git docs/statix_start:trans/statics.stx" extract: + start: programOk + stop: (.*TopLevel.*) +!} +``` + +Then I reached the point at which the grammar was basically just +```SDF3 +// Start.TopLevel = +// Ex.Sequence = sq:Ex+ {layout: align-list sq} +// Ex.Terminated = <;> +{! "\git docs/statix_start:syntax/fostr.sdf3" extract: + start: TermEx.Terminate + stop: (.*bracket.*) +!} +``` +(The first three clauses are in comments because they approximate fostr's +grammar; it actually uses a few more sorts for sequences of +expressions, to acheive fostr's exact layout rules.) + +This was the first point at which there were two different types that might +need to be written to standard output (Int and String), and although of course +the dynamically-typed Python and Javascript code generated dealt with both fine, +the Haskell code needed to differ depending on the +type of the item written (and I hadn't even started OCaml code generation at +that point since I knew it would be hopeless without statically typing fostr +programs). + +So it was time to bite the bullet and add type checking via Statix to fostr. +**/ + +// see docs/implementation.md for detail on how to switch to multi-file analysis rules // single-file entry point