zakarya/puzzles
1
0
Fork 0
mirror of git://git.tartarus.org/simon/puzzles.git synced 2025-04-21 16:05:44 -07:00
Code Issues Packages Projects Releases Wiki Activity

Document the asserted printable ASCII nature of many strings

Browse Source 
The exception is the random seed string, which we lightly document as
non-ASCII.
This commit is contained in:
Ben Harris
2022-10-19 09:04:06 +01:00
parent 7f4d038258
commit 0ce67c7c3f
1 changed files with 15 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
devel.but
View File

@ -466,8 +466,8 @@ from the game, and before passing it on to the front end.
\c char *(*encode_params)(const game_params *params, bool full); \c char *(*encode_params)(const game_params *params, bool full);
The job of this function is to take a \c{game_params}, and encode it The job of this function is to take a \c{game_params}, and encode it
in a string form for use in game IDs. The return value must be a in a printable ASCII string form for use in game IDs. The return value must
newly allocated C string, and \e{must} not contain a colon or a hash be a newly allocated C string, and \e{must} not contain a colon or a hash
(since those characters are used to mark the end of the parameter (since those characters are used to mark the end of the parameter
section in a game ID). section in a game ID).
@ -745,8 +745,8 @@ ensuring solubility and uniqueness as appropriate.
As input it is given a \c{game_params} structure and a random state As input it is given a \c{game_params} structure and a random state
(see \k{utils-random} for the random number API). It must invent a (see \k{utils-random} for the random number API). It must invent a
puzzle instance, encode it in string form, and return a dynamically puzzle instance, encode it in printable ASCII string form, and
allocated C string containing that encoding. return a dynamically allocated C string containing that encoding.
Additionally, it may return a second dynamically allocated string in Additionally, it may return a second dynamically allocated string in
\c{*aux}. (If it doesn't want to, then it can leave that parameter \c{*aux}. (If it doesn't want to, then it can leave that parameter
@ -867,8 +867,8 @@ allocations contained within it.
\c char *(*encode_ui)(const game_ui *ui); \c char *(*encode_ui)(const game_ui *ui);
This function encodes any \e{important} data in a \c{game_ui} This function encodes any \e{important} data in a \c{game_ui}
structure in string form. It is only called when saving a structure in printable ASCII string form. It is only called when
half-finished game to a file. saving a half-finished game to a file.
It should be used sparingly. Almost all data in a \c{game_ui} is not It should be used sparingly. Almost all data in a \c{game_ui} is not
important enough to save. The location of the keyboard-controlled important enough to save. The location of the keyboard-controlled
@ -969,8 +969,8 @@ was made (i.e. no new \c{game_state} needs to be created).
\b Returning anything else indicates that a move was made and that a \b Returning anything else indicates that a move was made and that a
new \c{game_state} must be created. However, instead of actually new \c{game_state} must be created. However, instead of actually
constructing a new \c{game_state} itself, this function is required constructing a new \c{game_state} itself, this function is required
to return a string description of the details of the move. This to return a printable ASCII string description of the details of the
string will be passed to \cw{execute_move()} move. This string will be passed to \cw{execute_move()}
(\k{backend-execute-move}) to actually create the new (\k{backend-execute-move}) to actually create the new
\c{game_state}. (Encoding moves as strings in this way means that \c{game_state}. (Encoding moves as strings in this way means that
the mid-end can keep the strings as well as the game states, and the the mid-end can keep the strings as well as the game states, and the
@ -1103,8 +1103,8 @@ it may return \cw{NULL}. If it does this, it must also set
\q{Solution not known for this puzzle}); that error message is not \q{Solution not known for this puzzle}); that error message is not
expected to be dynamically allocated. expected to be dynamically allocated.
If this function \e{does} produce a solution, it returns a move string If this function \e{does} produce a solution, it returns a printable
suitable for feeding to \cw{execute_move()} ASCII move string suitable for feeding to \cw{execute_move()}
(\k{backend-execute-move}). Like a (non-empty) string returned from (\k{backend-execute-move}). Like a (non-empty) string returned from
\cw{interpret_move()}, the returned string should be dynamically \cw{interpret_move()}, the returned string should be dynamically
allocated. allocated.
@ -3427,6 +3427,9 @@ currently exist and this function will return \cw{NULL}.
The returned string, if it is non-\cw{NULL}, is dynamically allocated. The returned string, if it is non-\cw{NULL}, is dynamically allocated.
Unlike the descriptive game ID, the random seed can contain characters
outside the printable ASCII set.
\H{midend-can-format-as-text-now} \cw{midend_can_format_as_text_now()} \H{midend-can-format-as-text-now} \cw{midend_can_format_as_text_now()}
\c bool midend_can_format_as_text_now(midend *me); \c bool midend_can_format_as_text_now(midend *me);
@ -3538,6 +3541,8 @@ visually activate and deactivate a redo button.
Calling this function causes the mid-end to convert its entire Calling this function causes the mid-end to convert its entire
internal state into a long ASCII text string, and to pass that internal state into a long ASCII text string, and to pass that
string (piece by piece) to the supplied \c{write} function. string (piece by piece) to the supplied \c{write} function.
The string will consist of printable ASCII characters and line
feeds.
Desktop implementations can use this function to save a game in any Desktop implementations can use this function to save a game in any
state (including half-finished) to a disk file, by supplying a state (including half-finished) to a disk file, by supplying a