Sok format
From Sokoban Wiki
(Difference between revisions)
(→Implementation of the file format) |
(→Implementation of the sok format) |
||
| Line 240: | Line 240: | ||
= Implementation of the sok format = | = Implementation of the sok format = | ||
| + | |||
| + | The advantage of the free formatted .sok file format is that it hardly uses any key words or specific tags (like in xml). Therefore the files can even be manipulated manually without causing problems. | ||
| + | <br> | ||
| + | From Brian Damgaard on yahoo group:<br> | ||
| + | <div style="background-color:#F0FFF0;padding:5px;border:1px solid green;"> | ||
| + | It only requires a few extra code lines and can easily be implemented with a normal and efficient one-pass parser. The only special thing the program must do is to take into account that: | ||
| + | * At the time the parser reads level notes, it's not known whether 1) the last text line belongs to the notes for the current level, or 2) it's the title line for the next level. | ||
| + | * Resolving that question can first take place when the parser sees the next level (it's board). | ||
| + | * At that point, a non-fool-proof-but-in-practice-more-than-good-enough separation can be made. If the last text line in the notes from the preceding level is a single line (not part of a multi-line paragraph) then it's a title. | ||
| + | |||
| + | Some refinements can be implemented. For instance, in YASC, the line isn't considered a title if the line contains ":" because it typically signals a key-value pair. Again, it's not fool-proof, but in practice it's perfectly all right. There won't be more than, say, 1 in 50,000 true levels. where this logic fails. | ||
| + | |||
| + | The easiest way to describe a .sok file parser is with pseudo-code, concentrating on file-header, boards, titles, and notes, but omitting snapshots: | ||
| + | |||
| + | ..set state to fileHeader | ||
| + | ..while more lines do | ||
| + | .....case state of | ||
| + | .......fileHeader......if...next line is a board-line then | ||
| + | ............................change state to newLevel | ||
| + | ............................check if file-header contains | ||
| + | ..............................a title for first level | ||
| + | .......................else add next line to file-header | ||
| + | ............................and advance | ||
| + | .......................(break, for C-programmers) | ||
| + | .......newLevel........create new level | ||
| + | .......................set level-title to the stored title, if any | ||
| + | .......................repeat | ||
| + | .........................add next line to board-lines and advance | ||
| + | .......................until eof or the next line isn't a board-line | ||
| + | .......................set state to levelNotes | ||
| + | .......................(break, for C-programmers) | ||
| + | .......levelNotes......if...next line is a board-line then | ||
| + | ............................change state to newLevel | ||
| + | ............................check if level-notes contains a title | ||
| + | ..............................for next level | ||
| + | ........................else add next line to level-notes and advance | ||
| + | .....endcase | ||
| + | ..endwhile | ||
| + | </div> | ||
| + | |||
| + | <br> | ||
| + | Note: Some programs like Sokoban YASC resctrict the level titles to valid Windows file names. This means characters like these ": \ * ? [ ] ; < > | / " are ignored in the level title. This however it not part of the sok-file format. | ||
| + | |||
| + | Answer from Eric Sunshine in yahoo group:<br> | ||
| + | <div style="background-color:snow;padding:5px;border:1px solid orange;"> | ||
| + | If you would like to support other cases, such as when much or all of | ||
| + | the meta-data appears before the puzzle, then you likely will need to | ||
| + | implement a more complex heuristic for determining which non-puzzle data | ||
| + | belongs to each puzzle. SokoSave Mobile takes this approach, trying very | ||
| + | hard to intuit which information belongs with which puzzle, since many | ||
| + | older collections are formatted in ways not compatible with the .sok | ||
| + | format. To do this, SokoSave Mobile implements heuristics based directly | ||
| + | on the SokoSplit utility (with a few small bug fixes): | ||
| + | http://www.high-speed-software.com/sokosave/sokosavedesktop/sokosplit/ | ||
| + | |||
| + | Here is a brief description of the heuristic. For each puzzle, perform | ||
| + | the following steps in order: | ||
| + | |||
| + | 1. If there is a blank line immediately before the puzzle, assign it to | ||
| + | the puzzle. | ||
| + | |||
| + | 2. Assign all following unassigned non-blank lines to the puzzle. | ||
| + | |||
| + | 3. Assign all preceding unassigned non-blank lines to the puzzle. These | ||
| + | lines precede the blank line (if present) assigned to the puzzle in step 1. | ||
| + | |||
| + | 4. Assign all following unassigned lines (blank or not) to the puzzle. | ||
| + | |||
| + | 5. Optional: Clean up by trimming leading and trailing blank lines from | ||
| + | the collected meta-data. (Internal blank lines are retained.) | ||
| + | |||
| + | This heuristic works correctly with all of the old puzzle collections I | ||
| + | have sitting around which were downloaded years ago, as well as with | ||
| + | modern collections available for download. The heuristic also is a | ||
| + | superset of the YASC .sok parsing, so it works properly with those | ||
| + | collections, as well. | ||
| + | |||
| + | </div> | ||
Revision as of 18:38, 28 July 2010
Contents |
Header added to the level files by the program "Sokoban YASC"
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: :: Sokoban (c) by Falcon Co., Ltd., Japan :: :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: :: File Format 0.14 :: :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: :: :: :: File Header :: :: Raw File Notes Optional :: :: File Notes Optional :: :: Game Type Optional :: :: Macros Optional :: :: Level 1 Required :: :: Title Optional* :: :: Board See legend :: :: Level Notes Optional :: :: Game 1 Optional :: :: Title Optional* :: :: Moves See legend :: :: Game Notes Optional :: :: Game 2 Optional :: :: ... (more games) :: :: Level 2 Optional :: :: ... (more levels) :: :: :: :: Remarks: :: :: :: :: File Header :: :: The different types of information may be written in :: :: any order. :: :: :: :: Raw File Notes :: :: Raw file notes are only intended for someone looking :: :: at the raw file in a text editor. These lines begin :: :: with "::". :: :: :: :: File Notes :: :: File notes are the remaining lines when all other :: :: information is removed from the file header, e.g., :: :: raw file notes and macros. :: :: :: :: As an example, file notes can contain general :: :: properties written as key/value pairs, such as :: :: "Author: Name". :: :: :: :: The optional but recommended property :: :: "Collection: Name" assigns a name to the puzzle :: :: collection. When a collection is copied from a :: :: website or e-mail and pasted into a Sokoban program, :: :: this information allows the collection to be saved :: :: with the proper name. :: :: :: :: Game Type :: :: The type applies to all levels in the file. If it is :: :: not specified, the default value is "Sokoban". :: :: :: :: The type is written as "Game: X" or "Game=X". :: :: An example: "Game: Hexoban". :: :: :: :: Macros :: :: Macros are key/value pairs separated by "=". :: :: An example: "Copyright=These levels are (c) by NN". :: :: :: :: The value of a key/value pair can be inserted in :: :: level notes and game notes by writing the key :: :: enclosed by "<#" ... "#/>". This applies to both :: :: types of key/value pairs, ":" and "=", but in :: :: contrast to ":" pairs, macros are not considered :: :: a part of the file notes. :: :: :: :: An example of macro usage: "<#Copyright#/>". :: :: The use of key/value pairs is case-insensitive. :: :: :: :: Macro-definitions are single-lined. To insert a :: :: line-break in the expanded text, write "\n". :: :: :: :: Titles :: :: A title line is the last non-blank text line before :: :: a level or a game, 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 level, game, or file :: :: header can be mistaken for a title line. :: :: :: :: Level Notes :: :: Two special key/value pairs are supported in level :: :: 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............: . o :............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. A board cannot :: :: have empty rows. :: :: :: :: Boards may be run-length encoded (RLE), e.g., :: :: "###----@.#" may be encoded as "3#4-@.#", and :: :: "#-#-#-##-#-#-#" may be encoded as "2(3(#-)#)". :: :: A row cannot be split over multiple physical lines. :: :: :: :: Rows may be combined on a single physical line by :: :: using "|" as a row separator, e.g., :: :: "--3#|3#-#|#@$.#|5#". A "|" at the end of a physical :: :: 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 :: :: Jump start.............: [ ] :...............Jump end :: :: Current position.......: * * :.......Current position :: :: :: :: Remarks: :: :: :: :: Moves may be run-length encoded, e.g., "3r3U" means :: :: "rrrUU", 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 games. :: :: :: :: Reverse mode games must start with a jump, even if :: :: it is empty. An example: "[]UU[ddlll]DDllR". :: :: :: :: Current position is optional and defaults to the :: :: position after the last move. :: :: :: :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Date Created: Date of Last Change: 2010-01-26 17:44:01 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Macros The macro feature allows levels to share a common text such as a copyright notice. An example: Copyright=Copyright (c) 3642 by xyz@paris.mars Demo Level 01 ######## # # #@ $ # # $ # # . . # ######## This demo level is trivial, but it suffices to demonstrate the file-format. A Sokoban program can add key/value pairs within the notes, such as: Author: nn Website: http://www.nn.net Solution/Moves (rurrdD)(uLulDD) The title of a snapshot does not bear any special meaning. This snapshot just happens to be the best solution found (so far). The demo-program automatically saves best solutions. Snapshot 7/0 urrrrdd This is an example of a snapshot saved by the user. Later he/she can continue work on this path. Snapshot 9/2 urrrrddLL*ruulDD Another snapshot saved by the user. The '*' indicates current position, i.e., the last moves were taken back, but are still available for the "redo" function. Demo Level 02 ######## # .# #@ $ # # $ # # . * # ######## Just another trivial demo level. The number of levels in a file is limited by available memory only. A macro example, inserting the text defined in the copyright-macro: <#Copyright#/> Solution/Moves (rRRR)(drU)(dlLLulD) Reverse Mode Snapshot 13/6 [rrrd]UU(rLLL)(drD) This is an example of a reverse mode snapshot. Reverse mode snapshots always have a leading jump-sequence, even if it is empty. An example: "[]Ulld...". Demo Level 03 ######## # # # $ # # $ # # + . # ######## Solution/Moves (rrruul)(Lr)(Duull)(DD)
Implementation of the sok format
The advantage of the free formatted .sok file format is that it hardly uses any key words or specific tags (like in xml). Therefore the files can even be manipulated manually without causing problems.
From Brian Damgaard on yahoo group:
It only requires a few extra code lines and can easily be implemented with a normal and efficient one-pass parser. The only special thing the program must do is to take into account that:
- At the time the parser reads level notes, it's not known whether 1) the last text line belongs to the notes for the current level, or 2) it's the title line for the next level.
- Resolving that question can first take place when the parser sees the next level (it's board).
- At that point, a non-fool-proof-but-in-practice-more-than-good-enough separation can be made. If the last text line in the notes from the preceding level is a single line (not part of a multi-line paragraph) then it's a title.
Some refinements can be implemented. For instance, in YASC, the line isn't considered a title if the line contains ":" because it typically signals a key-value pair. Again, it's not fool-proof, but in practice it's perfectly all right. There won't be more than, say, 1 in 50,000 true levels. where this logic fails.
The easiest way to describe a .sok file parser is with pseudo-code, concentrating on file-header, boards, titles, and notes, but omitting snapshots:
..set state to fileHeader ..while more lines do .....case state of .......fileHeader......if...next line is a board-line then ............................change state to newLevel ............................check if file-header contains ..............................a title for first level .......................else add next line to file-header ............................and advance .......................(break, for C-programmers) .......newLevel........create new level .......................set level-title to the stored title, if any .......................repeat .........................add next line to board-lines and advance .......................until eof or the next line isn't a board-line .......................set state to levelNotes .......................(break, for C-programmers) .......levelNotes......if...next line is a board-line then ............................change state to newLevel ............................check if level-notes contains a title ..............................for next level ........................else add next line to level-notes and advance .....endcase ..endwhile
Note: Some programs like Sokoban YASC resctrict the level titles to valid Windows file names. This means characters like these ": \ * ? [ ] ; < > | / " are ignored in the level title. This however it not part of the sok-file format.
Answer from Eric Sunshine in yahoo group:
If you would like to support other cases, such as when much or all of the meta-data appears before the puzzle, then you likely will need to implement a more complex heuristic for determining which non-puzzle data belongs to each puzzle. SokoSave Mobile takes this approach, trying very hard to intuit which information belongs with which puzzle, since many older collections are formatted in ways not compatible with the .sok format. To do this, SokoSave Mobile implements heuristics based directly on the SokoSplit utility (with a few small bug fixes): http://www.high-speed-software.com/sokosave/sokosavedesktop/sokosplit/
Here is a brief description of the heuristic. For each puzzle, perform the following steps in order:
1. If there is a blank line immediately before the puzzle, assign it to the puzzle.
2. Assign all following unassigned non-blank lines to the puzzle.
3. Assign all preceding unassigned non-blank lines to the puzzle. These lines precede the blank line (if present) assigned to the puzzle in step 1.
4. Assign all following unassigned lines (blank or not) to the puzzle.
5. Optional: Clean up by trimming leading and trailing blank lines from the collected meta-data. (Internal blank lines are retained.)
This heuristic works correctly with all of the old puzzle collections I have sitting around which were downloaded years ago, as well as with modern collections available for download. The heuristic also is a superset of the YASC .sok parsing, so it works properly with those collections, as well.
