parseknife

Extensible Kotlin parsing library | Site | Docs

Usage

Using ParseKnife primarily revolves around Rules, creating them, and using them to produce Tokens from Sources.

Making Rules

Rules are Kotlin classes that implement a shared abstraction.

So you can make rules by constructing those classes, there also exists a helper object for this: r

E.g. r.or(r.regex("x|yz"), r.eof()), AndRule('a', 'b'), RegexRule("[0-9]+")

Making Tokens

Tokens are subsections of source with associated metadata as well as nested children.

The Parser abstraction uses Rules to produce Tokens.

It's generic, so it can be extended to return any information transformed from those Tokens.

Rules also directly expose a makeToken(Cursor): Token

* A note on RegexRules: Capture-groups are stored as children, with named groups including a "groupName" key in their meta.

Using Metadata

Their exists a meta property, mapping String keys to Any?s, on both Tokens and Rules.

The metadata of a Rule is generally applied to all root Tokens produced by that Rule.

Convenience methods have been added for using this metadata:

• withMeta(key: String, value: Any?): this accomplishes a sort of "builder" pattern
• query(maxDepth: Int? = null, meth: (Token) -> Boolean) searches breadth-first

Parser Parser

Also included is a parser that parses these parsers for you, so you don't have to parse through this parsing documentation to make your parser.

You can use it via metaParser. Here is its source for itself.

whitespace = /\s+/;

character = /'(?<content>\\.|[^'])'/;
regex = /\/(?<content>(\\.|[^\/])*)\//;
string = /"(?<content>(\\.|[^'])*)"/;

endOfFile = "$eof";
integer = /[0-9]+/;
ruleName = /[a-zA-Z_]+/;
group = '(' or ')';

decorator = /[+?*!^]*/;
termValue = integer
    | character
    | string
    | regex
    | group
    | ruleName;
term = (termValue decorator)^;

and = (term (whitespace term)^*)^;
or = and ('|' and)*;

rule = ruleName '=' or ';';
language = rule+;

Download

Latest release: v0.0.1

Direct download links are bundled with this release for jars containing both the compiled library and its sources.

Gradle (Kotlin)

repositories {
  // ...
  mavenCentral()
  maven { url = uri("https://jitpack.io") }
}
dependencies {
  // ...
  implementation("com.github.pickeloe5:parseknife:0.0.1")
}

Gradle (Groovy)

repositories {
  // ...
  mavenCentral()
  maven { url 'https://jitpack.io' }
}
dependencies {
  // ...
  implementation 'com.github.pickeloe5:parseknife:0.0.1'
}

Maven

<repositories>
  <!-- ... -->
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>
<dependencies>
  <!-- ... -->
  <dependency>
    <groupId>com.github.pickeloe5</groupId>
    <artifactId>parseknife</artifactId>
    <version>0.0.1</version>
  </dependency>
</dependencies>

JitPack has some information about configuring other dependency managers.