Enum FileFormat 

#[non_exhaustive]
pub enum FileFormat {
    SokobanSLC,
    Xsb,
    Txt,
    Hsb,
    Tsb,
    SokobanYASC,
    Json,
}

All supported Sokoban file formats.

Depending on file format, following restrictions apply:

File extension	restrictions
.sok	Any Tessellation puzzles, allows mixing different Tessellation in the same file
.hsb	Only Hexoban puzzles
.tsb	Only Trioban puzzles
.xsb	Only Sokoban puzzles
.txt	Only Sokoban puzzles
.slc	Only Sokoban puzzles
.json	Any Tessellation puzzles, allows mixing different Tessellation in the same file

If file format restricts Tessellation of Puzzle in it, sokoban_elements will:

• refuse to save Puzzle of different Tessellation into these files
• assume exact Tessellation for Puzzle loaded from these files

If file format doesn’t restrict Tessellation of Puzzle in it, sokoban_elements will allow and implement it too.

Todo

• make writing of metadata optional
• make writer for individual Puzzles
  • with optional metadata
  • with optional saved games

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

SokobanSLC

XML format associated with Sokoban for Windows.

Files typically end with .slc extension.

This is lossy format:

• it doesn’t support writing any tessellation except Sokoban
• it doesn’t support writing Sokoban+, saved games, notes, etc…
• Collection writer reports error if trying to write Puzzle that is not Sokoban, but it silently skips writing unsupported data for supported tessellation.

Xsb

XSokoban file format.

Files typically end with .xsb extension.

This is lossy format:

• it doesn’t support writing any tessellation except Sokoban
• it doesn’t support writing Sokoban+, saved games, notes, etc…
• Collection writer reports error if trying to write Puzzle that is not Sokoban, but it silently skips writing unsupported data for supported tessellation!

Txt

Same as FileFormat::Xsb, different file extension.

Files typically end with .txt extension.

This is lossy format:

• it doesn’t support writing any tessellation except Sokoban
• it doesn’t support writing Sokoban+, saved games, notes, etc…
• Collection writer reports error if trying to write Puzzle that is not Sokoban, but it silently skips writing unsupported data for supported tessellation!

Hsb

File format base on Xsb but for Hexoban puzzles.

Files typically end with .hsb

This is lossy format:

• it doesn’t support writing any tessellation except Hexoban
• it doesn’t support writing Sokoban+, saved games, notes, etc…
• Collection writer reports error if trying to write Puzzle that is not Hexoban, but it silently skips writing unsupported data for supported tessellation!

Tsb

File format base on Xsb but for Trioban puzzles.

Files typically end with .tsb

This is lossy format:

• it doesn’t support writing any tessellation except Trioban
• it doesn’t support writing Sokoban+, saved games, notes, etc…
• Collection writer reports error if trying to write Puzzle that is not Trioban, but it silently skips writing unsupported data for supported tessellation.

SokobanYASC

Plain text format defined by SokobanYASC.

Files typically end with .sok extension.

This is most versatile file format because it supports saving complete Collection, Puzzle and SavedGame info along with Sokoban+, differing Tessellations in the same file, author and similar metadata etc..

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::         Sokoban (c) by Falcon Co., Ltd., Japan         ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::                    File Format 0.17                    ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::                                                        ::
:: File Notes                                  Optional   ::
:: Puzzle 1                                    Required   ::
::    Title                                    Optional*  ::
::    Board                                    See legend ::
::    Puzzle Notes                             Optional   ::
::    Saved Game or Solution 1                 Optional   ::
::      Title                                  Optional*  ::
::      Moves                                  See legend ::
::      Notes                                  Optional   ::
::    Saved Game or Solution 2                 Optional   ::
::    ... (more saved games and solutions)                ::
:: Puzzle 2                                    Optional   ::
:: ... (more puzzles)                                     ::
::                                                        ::
:: Remarks:                                               ::
::                                                        ::
:: File Notes                                             ::
::   File notes consist of unstructured text and          ::
::   key/value properties, such as "Author: Name". Lines  ::
::   beginning with "::" are comments meant to be read    ::
::   only by a person examining the file in a text        ::
::   editor, and should not be displayed by the Sokoban   ::
::   program.                                             ::
::                                                        ::
::   The optional but recommended property                ::
::   "Collection: Name" assigns a name to the puzzle      ::
::   collection. When a collection is copied from the     ::
::   internet, for example, and pasted into a Sokoban     ::
::   program, this information allows the collection to   ::
::   be saved with the proper name.                       ::
::                                                        ::
:: Titles                                                 ::
::   A title line is the last non-blank text line before  ::
::   a board, a saved game, or a solution, provided the   ::
::   line is preceded  by a blank line or it is the only  ::
::   text line at this position in the file.              ::
::                                                        ::
::   Title lines are optional unless a single or a last   ::
::   text line from a preceding puzzle, saved game,       ::
::   solution, or file header can be mistaken for a title ::
::   line.                                                ::
::                                                        ::
:: Puzzle Notes                                           ::
::   Two special key/value pairs are supported in puzzle  ::
::   notes: "Title" and "Author", hence, titles can       ::
::   either come from a title line or from a key/value    ::
::   pair.                                                ::
::                                                        ::
::::::::::::::::::::::::::: Board ::::::::::::::::::::::::::
:: Legend.................:      :.................Legend ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Wall...................: #  # :...................Wall ::
:: Pusher.................: p  @ :.................Pusher ::
:: Pusher on goal square..: P  + :..Pusher on goal square ::
:: Box....................: b  $ :....................Box ::
:: Box on goal square.....: B  * :.....Box on goal square ::
:: Goal square............: .  . :............Goal square ::
:: Floor..................:      :..................Floor ::
:: Floor..................: -  _ :..................Floor ::
::                                                        ::
:: Remarks:                                               ::
::                                                        ::
::   The first and the last non-empty square in each row  ::
::   must be a wall or a box on a goal. An empty interior ::
::   row is written with at least one "-" or "_".         ::
::                                                        ::
::   Boards may be run-length encoded (RLE), e.g.,        ::
::   "###----p.#" may be encoded as "3#4-p.#", and        ::
::   "#-#-#-##-#-#-#" may be encoded as "2(3(#-)#)".      ::
::   A row cannot be split over multiple lines.           ::
::                                                        ::
::   Rows may be combined on a single line by using "|"   ::
::   as a row separator, e.g., "--3#|3#-#|#pb.#|5#".      ::
::   A "|" at the end of a line is optional and may be    ::
::   omitted.                                             ::
::                                                        ::
::::::::::::::::::::::::::: Moves ::::::::::::::::::::::::::
:: Legend.................:      :.................Legend ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Move pusher up.........: u  U :.......Push/pull box up ::
:: Move pusher down.......: d  D :.....Push/pull box down ::
:: Move pusher left.......: l  L :.....Push/pull box left ::
:: Move pusher right......: r  R :....Push/pull box right ::
:: Begin jump.............: [  ] :...............End jump ::
:: Begin pusher change....: {  } :......End pusher change ::
:: Current position.......: *  * :.......Current position ::
::                                                        ::
:: Remarks:                                               ::
::                                                        ::
::   Moves may be run-length encoded, e.g., "3r4U" means  ::
::   "rrrUUUU", and "2(3(dr)R)" means "drdrdrRdrdrdrR".   ::
::   Each line must, however, have at least one proper    ::
::   non-digit character. Spaces between moves are        ::
::   allowed.                                             ::
::                                                        ::
::   Jumps and pulls: Only in reverse mode saved games    ::
::   and solutions.                                       ::
::                                                        ::
::   Reverse mode saved games and solutions must begin    ::
::   with a jump, even if it is empty. An example:        ::
::   "[]U[rr]d".                                          ::
::                                                        ::
::   Pusher changes: Only in puzzles with multiple        ::
::   pushers, e.g., Multiban. Moves inside the braces     ::
::   depict the relative movement to get from the         ::
::   currently active pusher to the next active pusher.   ::
::   At game start, a "{...}" sequence activates the      ::
::   pusher relative to the top-left pusher. An example:  ::
::   "{rddd}Urr{uul}uLU". If the top-left pusher is the   ::
::   first active pusher, then the empty "{}" can be      ::
::   omitted.                                             ::
::                                                        ::
::   The current position is optional and defaults to the ::
::   position after the last move.                        ::
::                                                        ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Json

JSON serialized Collection, available with the json cargo feature.

Files typically end with .json extension.

The document is exactly what serde_json produces for a Collection - there is no envelope and no version field - written pretty printed. Like SokobanYASC it is lossless and unrestricted: it stores complete Collection, Puzzle and SavedGame data along with Sokoban+, and it allows mixing Tessellations in one file. See the # Serde sections of those types for the shape of each.

Unlike the other formats, this one has no options:

• WriterSettings::print_visible_floor, WriterSettings::rle_encode and WriterSettings::wrap_savegame_lines_at are ignored. print_visible_floor has to be: boards are always serialized with visible floors, because trimming them loses board width.
• ReaderSettings::legacy_sokoban_plus is ignored. Sokoban+ is stored as typed arrays rather than as text, so it has no 99 marker to reinterpret.

Two reading quirks are worth knowing:

• A board or saved game that fails to parse is reported as JsonSyntaxError, not as BoardSyntaxError, because serde flattens the underlying error into a message. To tell malformed JSON apart from JSON this crate’s types rejected, downcast Error::source to serde_json::Error and inspect its classify().
• Every field of Collection is optional, so any JSON object at all reads as a valid - possibly empty - collection. That is not specific to this format: a .sok file with no board in it also reads as an empty collection.

Implementations

impl FileFormat

pub fn file_extension(&self) -> &str

File extension for given file format.

pub fn restricted_to_tessellation(&self) -> Option<Tessellation>

Some if file format restricts allowed Tessellation, otherwise None.

pub fn from_file_extension(path: impl AsRef<Path>) -> Option<Self>

Some if there exists a FileFormat for file extension from path, otherwise None.

pub fn read<R>( src: &mut R, settings: ReaderSettings, ) -> Result<Collection, IoReadError>

where R: Read + BufRead + Seek,

Loads Collection.

⚠️ Expects source is UTF-8 encoded, but doesn’t validate that expectation.

Examples

Reading from file:

use std::fs::File;
use std::io::BufReader;
use std::path::Path;

use sokoban_elements::*;

let path = Path::new("Original and Extra.sok");
let mut reader = BufReader::new(File::open(path)?);
let settings = ReaderSettings::default();
let collection = FileFormat::read(&mut reader, settings)?;

Reading from in-memory string:

use std::io::Cursor;

use sokoban_elements::*;

let mut settings = ReaderSettings::default();
settings.file_format = FileFormat::Xsb;

let data: String = "sokoban collection data read from elsewhere...".to_string();
let mut reader = Cursor::new(data.as_bytes());

let collection = FileFormat::read(&mut reader, settings)?;
let puzzle = &collection.puzzles[0];

pub fn read_from_path( src_file_path: impl AsRef<Path>, settings: Option<ReaderSettings>, ) -> Result<Collection, IoReadError>

Loads Collection from file.

⚠️ ReaderSettings::file_format is ignored and is instead constructed from src_file_path.

pub fn write<W>( dest: &mut W, collection: &Collection, settings: WriterSettings, ) -> Result<(), IoWriteError>

where W: Write,

Writes Collection.

Assumes dest is not buffered.

Examples

Write collection to file:

use std::fs::File;
use std::path::Path;

use sokoban_elements::*;

let collection = Collection::new();

let settings = WriterSettings::default();
let file_with_extension =
    format!("Original and Extra.{}", settings.file_format.file_extension());
let path = Path::new(&file_with_extension);
let mut file = File::create(path)?;

FileFormat::write(&mut file, &collection, settings)?;

Write collection to in-memory string:

use std::io::Cursor;

use sokoban_elements::*;

let collection = Collection::new();

let settings = WriterSettings::default();
let mut bytes: Vec<u8> = Vec::new();
let mut writer = Cursor::new(&mut bytes);

FileFormat::write(&mut writer, &collection, settings)?;

let collection_text = String::from_utf8(bytes).unwrap();

Write collection to stdout

use sokoban_elements::*;

let collection = Collection::new();
let settings = WriterSettings::default();
let mut stdout = std::io::stdout();
FileFormat::write(&mut stdout, &collection, settings)?;

pub fn save_to_file( &self, collection: &Collection, dest_file_path: impl AsRef<Path>, settings: Option<WriterSettings>, ) -> Result<(), IoWriteError>

Writes Collection to file.

⚠️ WriterSettings::file_format is ignored and is instead constructed from dest_file_path.

Trait Implementations

impl Clone for FileFormat

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for FileFormat

impl Debug for FileFormat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for FileFormat

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for FileFormat

impl Hash for FileFormat

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for FileFormat

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for FileFormat

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for FileFormat