Skip to content

davegurnell/spandoc

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 

Spandoc

Write Pandoc filters in Scala. Very early release. Still in development.

Copyright 2016 Dave Gurnell. Licensed Apache 2.

Scala 2.12 Scala 2.13

Requirements

Spandoc requires:

  • Pandoc (tested with Pandoc 2.9.1.1);
  • Ammonite (to create Spandoc shell scripts).

Getting Started

Use Spandoc in an Ammonite and use it with Pandoc's --filter parameter:

echo 'Lorem ipsum' | pandoc --to=html --filter=my-filter.sc
# <p>LOREM IPSUM</p>

Here's an example script:

// Filename: my-filter.sc
#!/usr/bin/env amm

interp.load.ivy("com.davegurnell" %% "spandoc" % "<<VERSION>>")

@
import spandoc._, ast._, transform._

// An AST transform that uppercases inline text:
val uppercase = TopDown.inline {
  case Str(str) => Str(str.toUpperCase)
}

// Run the transform on stdin, printing the result to stdout:
transformStdin(uppercase)

How to Create Transforms

A transform is simply a function of the following type:

import spandoc.ast.Pandoc

type TransformFunc = Pandoc => Pandoc

Spandoc provides some helper classes to assist in the creation of transforms:

  • spandoc.transform.Transform is a class that breaks the transform down into smaller components: Block nodes, Inline nodes, and so on;

  • spandoc.transform.BottomUp implements Block and Inline transforms in a bottom-up traversal order that processes every node in the AST;

  • spandoc.transform.TopDown implements Block and Inline transforms in a top-down traversal order that allows you to shortcut transformation of subtrees.

You can create simple transforms using the methods on the companion objects of BottomUp and TopDown (as in the example above), or you can extend either type to create a more complex transform:

object transform extends BottomUp[cats.Id] {
  override def blockTransform = {
    // Change all ordered lists to bulleted lists:
    case OrderedList(_, items) => BulletList(items)
  }

  override def inlineTransform - {
    // Uppercase all body text:
    case Str(str) => Str(str.toUpperCase)
  }
}

Transforms can be monadic, which is typically useful to thread a State monad through the AST. See the examples directory for use cases like this.

About

Write Pandoc filters in Scala.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages