Getting started
Official Bark reference entry point. Install, run your first .woof file, and how to read the rest of these docs.
About these docs
Most pages use grammar tables with three columns:
- Line: something you can write
- Parses as: AST shape (for people reading the Java/Python source)
- Need to know: runtime rules that bite you in stories
Expression shorthand in tables: Field(she, items), StashAccess(cookie_jar, COUNT), Binary(PLUS, …).
What Bark is
Bark is a dog-themed esoteric language. You write .woof files that read like short stories. An interpreter runs them. Hobby project, not production.
An example. Periods and words like is or has are optional filler:
I have a labrador.
She is 2.
She has 3 toys.
Her name is "Bimba".
she woofs how many toys she has
That prints 3.
Two interpreters
jbark (Java) and pbark (Python) accept the same .woof syntax and should produce the same output. Jbark is canonical if they some some reason ever diverge.
Install
Python (pbark): The easiest way to run .woof files (Python 3.10+):
pip install pbark
pbark story.woof
That installs the pbark command. Same flags as jbark (--help, --version, --strict, --quiet, --list-breeds, --list-objects). Read from stdin with pbark and no filename.
Java (jbark): Add the library from Maven Central if you embed Bark in a Java app:
repositories { mavenCentral() }
dependencies {
implementation("dev.klomptech:bark:1.0.0")
}
That ships the parser and interpreter as a library. It does not install a global bark shell command. You call jbark from your own Java code. For a standalone CLI without writing Java, use a GitHub Release zip or a clone (see below).
Java (jbark) CLI
Release (after unzipping GitHub Releases; Java 25+):
| Command | Need to know |
|---|---|
bark story.woof | Run a file (./bark on Mac/Linux) |
bark | Read from stdin until EOF |
bark --help or bark -h | Show usage |
bark --version or bark -version | Show version and a dog fact |
bark --list-breeds | List every breed in breeds.txt |
bark --list-objects | List every object in objects.txt |
bark --strict story.woof | Warn on story-only lines that do nothing |
bark --quiet story.woof | Hide startup banner and goodbye |
Windows: bark.cmd instead of bark. The launchers wrap java -jar bark-*-all.jar.
From a clone (developers):
./gradlew run --args="examples/woof/tutorial.woof"
After ./gradlew shadowJar: ./bin/bark examples/woof/tutorial.woof (or ./gradlew dist then ./build/dist/bark …).
Python (pbark) from a clone
If you are hacking on pbark itself.
cd pbark && pip install -e .
./bin/pbark ../examples/woof/tutorial.woof
Or: python3 -m pbark examples/woof/tutorial.woof from the repo root (after install).
| Command | Need to know |
|---|---|
pbark story.woof | Run a file |
pbark | Read from stdin until EOF |
pbark --help or pbark -h | Show usage |
pbark --version or pbark -version | Show version and a dog fact |
pbark --list-breeds | List every breed in breeds.txt |
pbark --list-objects | List every object in objects.txt |
pbark --strict story.woof | Warn on story-only lines that do nothing |
pbark --quiet story.woof | Hide startup banner and goodbye |
Tests: cd pbark && pip install -e ".[dev]" && pytest tests/ -q
How lines work
Usually one statement per line. Multiline when / while / for each / trick bodies are the main exception. They run from then until bury (or enough, goodnight, …).
How hearing works
The runtime only reacts to registered names, keywords, and values. Everything else is story glue, like a dog ignoring blah name blah walk blah until it hears walk. See Writing stories for the author view.
Basics
| Line | Parses as | Need to know |
|---|---|---|
| (empty line) | skipped | Blank lines are fine |
bark "hello" | Print[BARK, …] | One statement per line |
| Story-only prose with no heard words | ignored | Use --strict to warn |
Heard means: registered names, keywords (when, bark, holds, …), numbers, strings, booleans (yes, nope, …), null words (empty, nothing, …).
Ignored means everything else (I, have, a, the, some, …).
Assign glue (between subject and value): is, has, have, was, were, becomes, became.
Browser playground on this site
The Try it page offers a Python playground so you can try out the language yourself. Check the examples if you require inspiration.
Example programs to run
After pip install pbark:
pbark goodboy.woof
pbark bimba.woof
pbark tutorial.woof
Or from a Java clone:
./gradlew run --args="examples/woof/goodboy.woof"
./gradlew run --args="examples/woof/bimba.woof"
./gradlew run --args="examples/woof/tutorial.woof"
./gradlew run --args="examples/woof/counter-tradition.woof"
./gradlew run --args="examples/woof/loops.woof"
More on the examples page.