Crate dfraw_json_parser

source ·
Expand description

dfraw_json_parser provides a way to turn raw files from Dwarf Fortress into JSON. It’s currently useful for getting some basic information from from a limited set of raw types:

  • creatures
  • plants
  • inorganics (rocks, ores, etc)
  • materials
  • syndromes
  • graphics (sprites and tile pages, some layer support)
  • limited template support, creature variations support, and select XX support

§How It Works

It functions using a regular expression to break apart the tokens and then checks the key in the token against a long list of ones it knows about. Any matches are utilized to build its own representation of the raw. Optionally you can turn this result into JSON using the serde_json library. Or I guess turn it into anything serde supports.

§Tauri Support

This library was built to provide raw parsing for another project, Overseer’s Reference Manual, which creates a tauri app that lets the user look at the raws on their machine in a searchable and filterable manner. The “tauri” feature flag enables functions which will emit parsing progress back to the tauri window.

§Glossary of Terms

§Raw

A raw is a definition used by Dwarf Fortress to create creatures, things and objects in the world. They can be used to also define how things interact. They are composed of a variety of tokens inside a raw file, starting with an identifier token of [#type#:#identifier#]. Raws can also select and modify other raws using a [SELECT:#identifier#] token.

§Raw File

A raw file is a single text file (with .txt extension) which has the first line as the raw file identifier, and then defines the type of raw file using the [OBJECT:#type#] token. The file can contain any number of raws of that type.

§Raw File Module, Raw Module

Since Dwarf Fortress 50, raws are organized into directories. (Previously they were in a flat structure.) This was done to facilitate the steam workshop.

§Raw Module Location, Module Location

Raw file module folders are located in 3 locations that this library recognizes:

  • $df_game_dir/data/vanilla: the vanilla raws are here
  • $df_game_dir/data/installed_mods: the workshop mods which have been used in generating a world are here. They are considered installed because they are in use by at least one world. (Note: these are never removed even if you delete all worlds which use them.)
  • $df_game_dir/mods: the workshop mods are stored here to be available when creating a world

§Info Text File

In each raw module, there is an info.txt file which contains information about that module, like author, version, earliest compatible version (for updating in existing saves), and information for the steam workshop if it is a mod downloaded from the steam workshop.

Re-exports§

Modules§

  • parser
    The parser module contains the functions for parsing raws and info files.
  • util
    This has utility functions for file operations and directory traversal.

Structs§

  • ParseResult
    A parsing result that contains the parsed raws and info files.
  • ParserOptions
    Option struct for passing to any parse function.

Enums§

  • ParserError
    The errors that may happen. Represents an error that occurred while parsing a raw file

Functions§

  • build_search_string
    The function build_search_string takes a raw_object that implements the Searchable trait and returns a string representation of the object for searching purposes.
  • parse
    Given the supplied ParserOptions, parse the raws and return a vector of boxed dynamic raw objects.