[−][src]Crate tweep

Tweep is a parser for the Twee 3 interactive fiction format

What is Twee?

Twee is "a text format for marking up the source code of Twine stories." It is an alternate way to produce interactive fiction stories for the Twine 2 platform, using plain text files instead of a graphical environment. The specification for Twee 3, supported by tweep, can be found here

Goals

The goal of tweep is to provide a fully standards-compliant Twee 3 parser that provides helpful warning and error messages for bad practices and common mistakes, which can be used as a backend for a compiler as well as other novel applications of the Twee 3 format.

What it's not

A compiler - while a corresponding compiler front end is in the works, this is not it. tweep only produces rust objects, not html
A Twee v1 or v2 parser - currently, there are no plans for supporting any version of the Twee specification other than Twee 3

Getting started

To use tweep in your Rust project, simply add the following to your Cargo.toml:

[dependencies]
tweep = "0.2"

For basic parsing, the main entry point into tweep is through the Story struct, which provides utility methods for parsing out a complete story from a String or a Path representing a file or directory. When given a directory, tweep will parse all files ending in .tw or .twee and merge them into a single output story. For more advanced parsing, such as if the tags or metadata attached to a special passage is needed, StoryPassages provides the same interface, but provides Passage objects in places where usually unnecessary information is stripped out.

Examples

use tweep::Story;
let input = r#":: StoryTitle
RustDoc Sample Story

:: StoryData
{
 "ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
 "format": "SugarCube",
 "format-version": "2.28.2",
 "start": "My Starting Passage",
 "tag-colors": {
   "tag1": "green",
   "tag2": "red",
   "tag3": "blue"
 },
 "zoom": 0.25
}

:: My Starting Passage [ tag1 tag2 ]
This is the starting passage, specified by the start attribute of StoryData.
Alternately, we could remove that attribute and rename the passage to Start.

It has tags and links to:
 [[Another passage]]
 [[Here too!|Another passage]]
 [[A third passage<-And a different passage]]

:: Another passage {"position":"600,400","size":"100,200"}
This passage has some metadata attached to it

:: A third passage [tag3] { "position": "400,600" }
This passage has both tags and metadata. The size attribute of the metadata
isn't overridden, so it will be set to the default value.
"#.to_string();

// Parse the input into an Output<Result<Story, ErrorList>>
let out = Story::from_string(input);
assert!(!out.has_warnings());

// Move the Result out of the Output
let (res, _) = out.take();
assert!(res.is_ok());

// Get the Story object
let story = res.ok().unwrap();

// StoryTitle and StoryData contents are parsed into special fields
assert_eq!(story.title.unwrap(), "RustDoc Sample Story");
assert_eq!(story.data.unwrap().ifid, "D674C58C-DEFA-4F70-B7A2-27742230C0FC");

// Other passages are parsed into a map, keyed by the passage name
assert_eq!(story.passages["My Starting Passage"].tags(), &vec!["tag1", "tag2"]);
let metadata = story.passages["A third passage"].metadata();
assert_eq!(metadata["size"], "100,100");
assert_eq!(metadata["position"], "400,600");

Structs

Error	An error with an owned `ErrorKind` and `Position`
ErrorList	A wrapper type for a list of `Error`s
FullContext	A context that represents a span of twee code with a beginning, end, and contents, along with a file name and some helper functions
Output	Represents the output of an operation along with a `Vec` of any `Warning`s generated by the operation.
PartialContext	A Context that holds only an optional file name and 1-indexed start position
Passage	A complete Twee passage, including header and content
PassageHeader	A passage header, along with associated `Position`, tags, and metadata
Position	One-indexed, line and column numbers to be used within a `Context`
ScriptContent	The content of a `Passage` tagged with `script`, containing script data.
Story	A parsed Twee story
StoryData	The content of a special passage with the name StoryData that contains a JSON blob with various information about the story.
StoryPassages	A parsed Twee story, that stores the full `Passage` object of each field
StoryTitle	The content of a special passage with the `StoryTitle` name, which will be used as the title for a parsed story
StylesheetContent	The contents of a `Passage` tagged with `stylesheet`, containing CSS data.
TwineContent	The contents of a Twine passage.
TwineLink	A link to a twee passage contained within a twee passage
TwinePassage	A special Twine passage to be used in `Story`s without the need to go through an enum to get the passage content
Warning	A warning with a `WarningKind`, `Position`, and optionally a reference to another `Position`

Enums

ErrorKind	An enum of the types of errors that can be generated by `tweep`
PassageContent	An enum of the types of content that can be inside a `Passage`
PositionKind	Indicates absolute/relative position
WarningKind	An enum of the types of warnings that can be produced by `tweep`

Type Definitions

Context

The output context type for Errors and Warnings. If the feature full-context is enabled, this will be a FullContext which will include the ability to retrieve the associated source Twee v3 code. Otherwise, it will be a PartialContext which will only include the file name and a starting location for the error/warning