kahl

R⁷RS Scheme parser combinator library for decoding BARE messages.

Status

With the exception of floating-point numbers (f32 and f64), all types from draft-devault-bare-01 are supported. The BARE schema language is currently not supported, but may be supported in future version of this library. Additionally, this hasn't been tested extensively and the API may still change.

Usage

Depends on your Scheme implementation. I have tested this with CHICKEN Scheme and chibi-scheme. For simple experiments, simply use the following commands:

$ git clone https://github.com/nmeum/kahl
$ cd kahl
$ chibi-scheme
> (import (kahl))
> (parse (parse-struct parse-u8 parse-u8) #u8(23 42))
#(23 42)

Tests require (chibi test) and can be run as follows:

$ ./run-tests.scm

Extended Example

Consider the following BARE schema definition:

type Customer {
	name: string
	email: string
	orders: []{
		orderId: i64
		quantity: i32
	}
}

Messages of this type can be parsed using the following Scheme code:

(import (kahl))

;; Define a parser for the Customer type.
(define parse-customer
  (parse-struct
    parse-string ;; name
    parse-string ;; email
    (parse-list  ;; orders
      (parse-struct
        parse-i64
        parse-i32))))

;; Create a parse stream for the file customer.bin
;; and use the parse-customer parser to parse it.
(let ((s (make-parse-stream "customer.bin")))
  (parse parse-customer s))

Refer to the documentation for more information on individual procedures.

Documentation

This library is documented using Scheme Scribble syntax as implemented by chibi scribble. Documentation can be generated using chibi-doc(1). To generate HTML documentation run:

$ chibi-doc -h kahl > kahl.html

If you want to improve the existing documentation, take a look at the Scribble quick start guide. Commands supported in the default Chibi-Scheme doc environment can be obtained by importing (chibi doc) and running (make-default-doc-env).

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.