~subsetpark/mago

d9821e125ebacb7ffab0338f4c4277171cf036d8 — Zach Smith 3 years ago cb660ed
add README
1 files changed, 39 insertions(+), 0 deletions(-)

A README.md
A README.md => README.md +39 -0
@@ 0,0 1,39 @@
{:title "Mago"
 :description "A minimal frontmatter library for Janet"}
 
%%%

# Mago

`mago` is an extremely simple format and library for writing text
documents with arbitrary metadata and parsing them in pure Janet.

This file is a Mago document; a Markdown text file with a Janet struct
at the beginning and a separator string, followed by the rest of the
body.

# Demo

Here's an example of how to use it:

```
Janet 1.13.1-e9f6c4f linux/x64 - '(doc)' for help
repl:1:> (import mago)
@{mago/parse @{:private true} mago/peg @{:private true} _ @{:value <cycle 0>} mago/default-peg @{:private true} mago/default-separator @{:private true}}
repl:2:> (mago/parse (slurp "README.md"))
{:body "\n\n# Mago\n\n`mago` is an extremely simple format and library for writing text\ndocuments with arbitrary metadata and parsing them in pure Janet.\n\nThis file is a Mago document; a Markdown text file with a Janet struct\nat the beginning and a separator string, followed by the rest of the\nbody.\n" :front {:description "A minimal frontmatter library for Janet" :title "Mago"}}
repl:3:> 
```

In other words, `mago/parse` will take a string, split it on the
separator string, and then parse the frontmatter as a Janet data
structure.

It produces a simple struct where `:front` contains the parsed data
structure and `:body` contains the rest of the document.

# Usage

This allows us to encode text file metadata similarly to Jekyll or
Multimarkdown. However, it has the advantage, within the Janet
ecosystem, of not requiring any shelling out to an external program.