You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
sogaiu cfc0e986fd Add unref to 0.all-the-names 4 weeks ago
examples Add unref to 0.all-the-names 4 weeks ago
margaret Add implementation for unref 2 months ago
support Use single file version of judge-gen 2 months ago
test Update judge-gen 2 months ago
README.adoc Update README 2 months ago
notes.txt Update notes 2 months ago
project.janet Rename vendor dir to support 2 months ago

README.adoc

This aims to be a pure-Janet implementation of Janet’s peg/match.

Background

While reading bakpakin’s How Janet’s PEG module works, started typing the code in and evaluating it, next thing I knew…​

Status

In progress, see Specials Implementation Status for details.

Why?

  • Aid in understanding Janet’s PEG system

  • Generate example PEG specials usages

  • Experiment with adding diagnostic info / tracing

  • Experiment with additional constructs

Setup

  • Clone this repository and cd to the relevant directory

  • Ensure janet and jpm are on your PATH

  • Install if you like: jpm install

Usage

meg/match is an attempt at implementing peg/match, so for example:

(import margaret/meg)

(meg/match ~(capture (some "smile")) "smile!")

should work.

There is some support for diagnostic output via the dynamic variable :meg-debug.

To try it, do:

(setdyn :meg-debug true)

or for more detailed info:

(setdyn :meg-debug {:captures true
                    :peg true
                    :text true})

before calling meg/match.

Output format is still evolving but likely will support at least:

  1. capture stack

  2. tags

  3. specials execution order

Testing

Run all tests by:

  • jpm test from the project directory of margaret

There are currently tests for:

Some of the tests were adapted / copied from Janet’s tests.

Specials Implementation Status

Each of the 48 Janet PEG specials has an initial implementation with tests. Specifically, that includes:

Implementation Notes

In many cases an attempt to follow the original peg.c implementation by bakpakin was made. Some motivations for doing so include:

  1. If peg.c changes, tracking those changes may be easier.

  2. If an experimentally added special in margaret proves useful, it might be easier to port it to peg.c.

  3. Arriving at a correct implementation might be easier because comparing it with a similar one is more meaningful.

  4. Debugging information obtained here might be more relevant when trying to understand a situation in the original peg.c context.

  5. Reading margaret’s implementation might be an easier place to start if one wants to study peg.c.

Some differences include:

  1. peg.c creates a bytecode representation before execution and some information (e.g. tag names) is not retained. In at least one case, some uses of range get compiled to the same type of bytecode instruction used by set.

  2. peg.c has protections for too much recursion.

Acknowledgments

Thanks to (at least) the following folks:

  • ahungry

  • andrewchambers

  • bakpakin

  • crocket

  • goto-engineering

  • GrayJack

  • ikarius

  • jcmkk3

  • LeafGarland

  • leahneukirchen

  • LeviSchuck

  • MikeBeller

  • nate

  • pepe

  • pyrmont

  • Saikyun

  • skuza

  • subsetpark

  • swlkr

  • tami5

  • uvtc

  • yumaikas

…​and other Janet community members :)