kahl

  1# kahl
  2
  3R⁷RS Scheme parser combinator library for decoding [BARE][bare web] messages.
  4
  5## Status
  6
  7With the exception of floating-point numbers (`f32` and `f64`), all
  8types from [`draft-devault-bare-01`][draft-devault-bare-01] are
  9supported. The BARE schema language is currently not supported, but may
 10be supported in future version of this library. Additionally, this
 11hasn't been tested extensively and the API may still change.
 12
 13## Usage
 14
 15Depends on your Scheme implementation. I have tested this with
 16[CHICKEN Scheme][chicken scheme] and [chibi-scheme][chibi github].
 17For simple experiments, simply use the following commands:
 18
 19	$ git clone https://github.com/nmeum/kahl
 20	$ cd kahl
 21	$ chibi-scheme
 22	> (import (kahl))
 23	> (parse (parse-struct parse-u8 parse-u8) #u8(23 42))
 24	#(23 42)
 25
 26Tests require [`(chibi test)`][chibi test] and can be run as follows:
 27
 28	$ ./run-tests.scm
 29
 30## Extended Example
 31
 32Consider the following [BARE schema][bare schema] definition:
 33
 34	type Customer {
 35		name: string
 36		email: string
 37		orders: []{
 38			orderId: i64
 39			quantity: i32
 40		}
 41	}
 42
 43Messages of this type can be parsed using the following Scheme code:
 44
 45	(import (kahl))
 46
 47	;; Define a parser for the Customer type.
 48	(define parse-customer
 49	  (parse-struct
 50	    parse-string ;; name
 51	    parse-string ;; email
 52	    (parse-list  ;; orders
 53	      (parse-struct
 54	        parse-i64
 55	        parse-i32))))
 56
 57	;; Create a parse stream for the file customer.bin
 58	;; and use the parse-customer parser to parse it.
 59	(let ((s (make-parse-stream "customer.bin")))
 60	  (parse parse-customer s))
 61
 62Refer to the documentation for more information on individual procedures.
 63
 64## Documentation
 65
 66This library is documented using Scheme Scribble syntax as implemented by
 67[chibi scribble][chibi scribble]. Documentation can be generated using
 68`chibi-doc(1)`. To generate HTML documentation run:
 69
 70	$ chibi-doc -h kahl > kahl.html
 71
 72If you want to improve the existing documentation, take a look at the
 73[Scribble quick start guide][racket scribble]. Commands supported in the
 74default Chibi-Scheme doc environment can be obtained by importing
 75[`(chibi doc)`][chibi doc] and running `(make-default-doc-env)`.
 76
 77## License
 78
 79This program is free software: you can redistribute it and/or modify
 80it under the terms of the GNU General Public License as published by
 81the Free Software Foundation, either version 3 of the License, or
 82(at your option) any later version.
 83
 84This program is distributed in the hope that it will be useful,
 85but WITHOUT ANY WARRANTY; without even the implied warranty of
 86MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 87GNU General Public License for more details.
 88
 89You should have received a copy of the GNU General Public License
 90along with this program. If not, see <https://www.gnu.org/licenses/>.
 91
 92[bare web]: https://baremessages.org/
 93[draft-devault-bare-01]: https://datatracker.ietf.org/doc/html/draft-devault-bare-01
 94[bare schema]: https://datatracker.ietf.org/doc/html/draft-devault-bare-01#section-3
 95[langsec web]: https://langsec.org/
 96[bratus parser]: https://www.usenix.org/publications/login/spring2017/bratus
 97[chibi parse]: https://synthcode.com/scheme/chibi/lib/chibi/parse.html
 98[chibi test]: https://synthcode.com/scheme/chibi/lib/chibi/test.html
 99[chibi scribble]: https://synthcode.com/scheme/chibi/lib/chibi/scribble.html
100[chibi doc]: https://synthcode.com/scheme/chibi/lib/chibi/doc.html
101[racket scribble]: https://docs.racket-lang.org/scribble/getting-started.html
102[chicken scheme]: https://call-cc.org
103[chibi github]: https://github.com/ashinn/chibi-scheme