Difference between revisions of "Map to file"
imported>Out of practice (Created (after extensive texting) an accurate and detailed explaination of the map_to_file() command, its quirks, its data storage format, and original example usage code) |
(Not the only I/O functions anymore) |
||
(9 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | + | {{ | |
+ | #vardefine:name|map_to_file}}{{ | ||
+ | #vardefine:return_type|boolean}}{{ | ||
− | + | FunctionPage| | |
+ | name={{#var:name}}| | ||
+ | function1={{Function| | ||
+ | name={{#var:name}}| | ||
+ | aggregate={{#var:aggregate}}| | ||
+ | return_type={{#var:return_type}}| | ||
+ | return_also={{#var:return_also}}| | ||
+ | parameter1={{Param|aggregate|map_to_save}}| | ||
+ | parameter2={{Param|string|file_to_save}}| | ||
+ | }}| | ||
− | + | function2={{Function| | |
+ | name={{#var:name}}| | ||
+ | aggregate={{#var:aggregate}}| | ||
+ | return_type={{#var:return_type}}| | ||
+ | return_also={{#var:return_also}}| | ||
+ | parameter1={{Param|aggregate|map_to_save}}| | ||
+ | parameter2={{Param|string|file_to_save}}| | ||
+ | parameter3={{Param|boolean|compact}}| | ||
+ | p1desc={{Pspan|map_to_save}} is the map to save data from| | ||
+ | p2desc={{Pspan|file_to_save}} is the filename to save to| | ||
+ | p3desc={{Pspan|compact}} is an (optional) flag; if omitted or true, record values are written on a single line of the file when possible, rather than one field per line| | ||
+ | }}| | ||
− | + | function_description=Saves the data in the {{pspan|map_to_save}} to the {{pspan|file_to_save}} in your KoLmafia "data" directory. The {{pspan|compact}} parameter exists only for backwards compatibility; there is no need to use it in new code (but if you do use it, you must pass the same value to [[file_to_map|file_to_map()]] to successfully read any records within your map). This function returns the operation's success. If {{pspan|file_to_save}} already exists, this function will override (not append) the file's contents with the new data. It's also worth noting that, once saved, the data in {{pspan|file_to_save}} is not tied to any particular map; it can be loaded into another map or slice, as long as the datatypes are compatible.</p> | |
− | + | <p>This function and <code>[[file_to_map|file_to_map()]]</code> are invaluable for an ASH scripter wishing to save any script settings or information too complex to easily fit in a user preference. However, caution should be used, as a single failed operation of this function could result in the loss of all such data. For anything difficult to re-create, or too important to lose, the script author should be careful to save backups and check for function success during such operations.| | |
+ | code1={{CodeSample| | ||
+ | title=Code Sample| | ||
+ | description=This sample saves a simple map of a user's responses to questions.| | ||
+ | code= | ||
+ | <syntaxhighlight> | ||
+ | boolean [string] answers; | ||
+ | answers["Chocolate"] = user_confirm( "Do you like chocolate?" ); | ||
+ | answers["CuteKittens"] = user_confirm( "Do you like cute kittens?" ); | ||
+ | answers["ThisGame"] = user_confirm( "Do you like KoL?" ); | ||
+ | if (map_to_file( answers , "WhatYouLike.txt" )) | ||
+ | print( "Your answers were saved successfully." ); | ||
+ | else | ||
+ | print( "There was a problem saving your answers." ); | ||
+ | </syntaxhighlight>| | ||
+ | moreinfo= | ||
+ | If the user answered No, Yes, Yes to the questions, they should now have a file that contains: | ||
+ | <pre> | ||
+ | Chocolate false | ||
+ | CuteKittens true | ||
+ | ThisGame true | ||
+ | </pre> | ||
+ | }}| | ||
− | + | see_also={{SeeAlso|buffer_to_file|file_to_array|file_to_buffer|file_to_map}}| | |
+ | }} | ||
− | + | [[Category:Miscellaneous Functions]] | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Latest revision as of 05:51, 21 December 2020
Function Syntax
boolean map_to_file(aggregate map_to_save ,string file_to_save )
boolean map_to_file(aggregate map_to_save ,string file_to_save ,boolean compact )
- map_to_save is the map to save data from
- file_to_save is the filename to save to
- compact is an (optional) flag; if omitted or true, record values are written on a single line of the file when possible, rather than one field per line
Saves the data in the map_to_save to the file_to_save in your KoLmafia "data" directory. The compact parameter exists only for backwards compatibility; there is no need to use it in new code (but if you do use it, you must pass the same value to file_to_map() to successfully read any records within your map). This function returns the operation's success. If file_to_save already exists, this function will override (not append) the file's contents with the new data. It's also worth noting that, once saved, the data in file_to_save is not tied to any particular map; it can be loaded into another map or slice, as long as the datatypes are compatible.
This function and file_to_map()
are invaluable for an ASH scripter wishing to save any script settings or information too complex to easily fit in a user preference. However, caution should be used, as a single failed operation of this function could result in the loss of all such data. For anything difficult to re-create, or too important to lose, the script author should be careful to save backups and check for function success during such operations.
Code Sample
This sample saves a simple map of a user's responses to questions.
boolean [string] answers;
answers["Chocolate"] = user_confirm( "Do you like chocolate?" );
answers["CuteKittens"] = user_confirm( "Do you like cute kittens?" );
answers["ThisGame"] = user_confirm( "Do you like KoL?" );
if (map_to_file( answers , "WhatYouLike.txt" ))
print( "Your answers were saved successfully." );
else
print( "There was a problem saving your answers." );
If the user answered No, Yes, Yes to the questions, they should now have a file that contains:
Chocolate false CuteKittens true ThisGame true