Crate kamo_macros

Macros for the kamo crate.

This crate is not meant to be used directly. It is used by the kamo crate to provide the sexpr!, sexpr_file!, and sexpr_script! macros.

The macros are used to parse a string literal into a single or an array of kamo::value::Values. The macros are defined as follows:

• sexpr!(<mutator>, <expression>) - A macro for parsing a single s-expression from a string. It returns a kamo::value::Value.

• sexpr_file!(<mutator>, <filename>) - A macro for parsing multiple s-expressions from a file. It returns an array of kamo::value::Values. The array may be empty.

• sexpr_script!(<mutator>, <expressions>) - A macro for parsing multiple s-expressions from a string. It returns an array of kamo::value::Values. The array may be empty.

The macros all take an optional MutatorRef identifier. This is used to allocate values on the heap. If the expression does not contain any values that need to be allocated on the heap, then the Mutator identifier can be omitted.

The syntax for the macros is as defined by the Scheme standard R7RS for the read procedure. The syntactic definition is the <datum> in section 7.1.2 External representations of the standard.

The syntax deviations from the standard are:

• The extactness (#e and #i) of numbers is not supported. Floating-point numbers are always inexact and integers are always exact.

• Numbers may only be signed 64-bit integers or IEEE 754 double precision floating-point numbers. The standard allows for arbitrary precision integers, rationals and complex numbers.

• Labels are not supported.

• The #; comment syntax is only supported in the macros which parse multiple s-expressions. The #; comment syntax may not be nested.

• Character literals defined by a hex escape sequence may have 1 to 6 digits. The standard excepts 1 or more digits. The code must be a valid Unicode code point.

The parser is implemented with the pest crate. The grammar is defined in src/sexpr/sexpr.pest. This is necessary because the combination parser library defined in kamo::parser cannot be used here. It would be cyclic dependency. There will be an implementation of a parser for s-expressions in the kamo::form module in the future. It will be based on the kamo::parser crate and will be used by the scheme interpreter.

Examples

use kamo::{mem::Mutator, sexpr, value::{print, Value}};
  
let m = Mutator::new_ref();
let value = sexpr!(m, "(1 2 3)");
  
assert_eq!(print(value).to_string(), "(1 2 3)");

use kamo::{sexpr_file, value::{print, Value}};
  
let m = Mutator::new_ref();
let values: &[Value] = &sexpr_file!(m, "tests/macros/values.scm");
  
assert_eq!(values.len(), 3);
assert_eq!(print(values[0].clone()).to_string(), "()");
assert_eq!(print(values[1].clone()).to_string(), "100");
assert_eq!(print(values[2].clone()).to_string(), "#t");

let values: &[Value] = &sexpr_file!("tests/macros/empty.scm");
assert_eq!(values.len(), 0);

use kamo::{mem::Mutator, sexpr_script, value::{print, Value}};
  
let m = Mutator::new_ref();
let values: &[Value] = &sexpr_script!(m, "(define a 1)\n(define b 2)\n(+ a b)");
  
assert_eq!(values.len(), 3);
assert_eq!(print(values[0].clone()).to_string(), "(define a 1)");
assert_eq!(print(values[1].clone()).to_string(), "(define b 2)");
assert_eq!(print(values[2].clone()).to_string(), "(+ a b)");

let values: &[Value] = &sexpr_script!("");
assert_eq!(values.len(), 0);

Macros

• sexpr
  Parse a string of a single s-expression into a kamo::value::Value.
• sexpr_file
  Parse a file of s-expressions into an array of kamo::value::Values.
• sexpr_script
  Parse a string of s-expressions into an array of kamo::value::Values.