- 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.
As this & file_to_map() are KoLmafia's only I/O functions, they 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.
This sample saves a simple map of a user's responses to questions.If the user answered No, Yes, Yes to the questions, they should now have a file that contains:
Chocolate false CuteKittens true ThisGame true