Sexpresso

Sexpresso is c++ centric s-expression parser library. It uses value types and move semantics and thus manages to completely avoid calling new/delete, so it’s probably free from memory leaks!

Sexpresso aims to be very simple, nodes are parsed either as s-expressions or strings, even a number would be parsed a string, so if you expect a node to be a number, please convert the string to a number!

How to use

By default Sexpresso uses pike style which means that it does not include any header files in its headers by default. If you wanna keep using pike style you’ll have to locate the line in the header you are about to include that will look something like this:

#ifdef SEXPRESSO_OPT_OUT_PIKESTYLE
#ifndef SEXPRESSO_HEADER
#define SEXPRESSO_HEADER
#include <vector>
#include <string>
#include <cstdint>
// #include "sexpresso.hpp"
#endif
#endif

And copy all of the includes before you include the actual header. If you don’t wanna do this and use header guards which can add extra processing time for the pre-processor, and all in all more unclearness of what includes what (since it ends up being a big chain), you can define SEXPRESSO_OPT_OUT_PIKESTYLE for the pre-processor.

After that you can move onward!

Parsing

auto parsetree = sexpresso::parse(mysexpr);

This code will parse the std::string in mysexpr and return a Sexp struct value. There are two main things you can do with this value you can:

1. Turn it back to a string with parsetree.toString()
2. Query it using parsetree.getChildByPath("path/to/node")

Number 2 might be slightly confusing, how does it follow the path? Well if you’ve ever used lisp, you know that the command in an s-expression is the first element. The same thing here determines where it goes looking for values. For example if you have an s-expression such as

(my-values (sweet baby jesus) (hi mom) just-a-thing)

You can query it like:

auto sub = parsetree.getChildByPath("my-values/sweet");

and

auto sub = parsetree.getChildByPath("my-values/hi");

Note that you get the sexpr node that contains the value you were looking for as its first value. The sexpr then simply holds an std::vector of all the sub-values. However, it might not always use the vector, if it’s simply a string value like just-a-thing in the above example, then the vector will be empty, and you need to access the string value instead.

if(sub->isSexp()) {
  std::cout << sub->value.sexpr[1];
} else {
  std::cout << sub->value.str;
}

// or

switch(sub->kind) {
case sexpresso::SexpValueKind::SEXP:
  std::cout << sub->value.sexpr[1];
  break;
case sexpresso::SexpValueKind::STRING:
  std::cout << sub->value.str;
}

Sexpresso provides a comfortable way to iterate only over the “arguments of a s-expression. For example if we have an s-expression like (hi 1 2 3) then the arguments are 1, 2 and 3. If we’ve parsed and stored that s-expression in a variable called hi, we iterate over its arguments like this:

for(auto&& arg : hi.arguments()) {
  // ..
}

// or 
for(auto&& it = hi.arguments().begin(); it != hi.arguments().end(); ++it) {
  // ..
}

You can also check if the arguments are empty and how many there are with the empty and size methods of the SexpArgumentIterator class.

WARNING Be REALLY careful that your query result does not exceed the lifetime of the parse tree:

Sexp* sub;
{
auto sexp = sexpresso::parse(mysexpr);
sub = sexp.getChildByPath("my-values/just-a-thing")
} // sexp gets destroyed here
cout << sub.toString(); // BAD!

Serializing

Sexp structs have an addChild method that takes a Sexp method. Furthermore, Sexp has a constructor that takes a std::string, so this should make it really easy to build your own Sexp objects from code that you can serialize with toString.

auto myvalues = sexpresso::Sexp{"my-values"};

auto sweet = sexpresso::Sexp{"sweet"};
sweet.addChild("baby");
sweet.addChild("jesus");

auto hi = sexpresso::Sexp{"hi"};
hi.addChild("mom");

auto justathing = sexpresso::Sexp{"just-a-thing"};

auto myvaluesholder = sexpresso::Sexp{};
myvaluesholder.addChild(std::move(myvalues));
myvaluesholder.addChild(std::move(sweet));
myvaluesholder.addChild(std::move(hi));
myvaluesholder.addChild(std::move(justathing));

auto sexp = sexpresso::Sexp{};
sexp.addChild(myvaluesholder);

// sexp should now hold the same s-expression we wrote in text earlier
std::cout << sexp.toString();

Important

The outermost s-expression does not get surrounded by paretheses when calling toString, as it treats a string as being implicitly surrounded by parentheses. This is so that you can have multiple s-expressions in the “root” of your code, and serialization goes back to text the same way it came in. That’s why we have the sexp in the above code example. If we simply called toString on myvaluesholder we would get

my-values (sweet baby jesus) (hi mom) just-a-thing

instead of

(my-values (sweet baby jesus) (hi mom) just-a-thing)

Cool? Cool.

S-expression primer

Confused? I mean what iiiis an s-expression?

s-expressions come from the lisp family of programming languages, it is an incredibly simple notation for lists, however, since these lists can be nested it also means that they are great for representing hierarchies as well, which makes it an excellent replacement for XML or JSON.

The notation is simply to surround the elements, separated by whitespace in parentheses, like this:

(here we have an s-expression)

What you see here is a list of 5 symbols: here, we, have, an and s-expression. Like I said you can also put s-expressions inside s-expressions to create hierarchies:

(my-objects 
  (object-a (name "isak andersson") 
            (countries swe uk)) 
  (object-b (name "joe bain")
            (countries uk)))

And as you could see earlier in the How to use section you can query this hierachy easily with this library. Say that this s-expression is stored in a variable called objs, you can query it like this:

auto joe = objs.getChildByPath("my-objects/object-b/name");

FAQ

Why should I use s-expressions

because they are more elegant and simple than XML or JSON. Much less work required to parse. And they look nice! (subjective)

Contributing

This library is public domain (CC0). Generally speaking by default, you have copyright on anything you make. So you have to explicitly give up copyrights in order to put something in the public domain. In this repository, please add your signature to CONTRIBUTORS.txt when contributing.

Future direction

Make it a header-only library instead perhaps?