search

racket / scribble

Other
197 stars 91 forks source link

Contract issues in scribble/bnf #170

Closed LiberalArtist closed 6 years ago

LiberalArtist commented 6 years ago

I'm opening an issue to note some problems with contracts in scribble/bnf. First of all, none of the exports of the module enforce their contracts. Adding them, though, will be more difficult because the contracts in the documentation are incorrect.

I discovered the lack of contracts when I got a very ugly error message from the guts of BNF. (I'd passed it a deeply nested quasiquoted list, and I'd left out a , somewhere.) When I initially tried to make a wrapper with define/contract, I then discovered that (BNF-seq) produces "", which is not an element?, even though the documentation both says that BNF-seq will produce an element? and says that the arguments to BNF must be (cons element? (listof (or/c block? element?))), though obviously (BNF (cons (nonterm "example") (list (BNF-seq)))) actually works just fine.

If I get a chance, I'll try to figure out what the contracts for these functions actually should be and update both the code and the docs accordingly.

LiberalArtist commented 6 years ago

I think one source of the confusion in the docs may be that scribble/bnf uses element? from scribble/struct (which I'd never read about before), even though the documentation linked to the version of element? from scribble/core. It might be nice to replace the use of scribble/struct, but that seemed like it should be a different pull request.