docs: Add statics development documentation
All checks were successful
continuous-integration/drone/push Build is passing

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.
This commit is contained in:
Glen Whitney 2021-02-12 17:08:55 -08:00
parent 904f651897
commit b3f9cdf372
2 changed files with 48 additions and 1 deletions

View File

@ -2,6 +2,7 @@ site_name: fostr language
nav: nav:
- README.md - README.md
- tests/basic.md - tests/basic.md
- trans/statics.md
- implementation.md - implementation.md
plugins: plugins:

View File

@ -2,7 +2,53 @@ module statics
imports signatures/fostr-sig 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>
// Ex.Sequence = sq:Ex+ {layout: align-list sq}
// Ex.Terminated = <<Ex>;>
{! "\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 rules // single-file entry point