Map to file

boolean map_to_file( aggregate map , string filename )

boolean map_to_file( aggregate map , string filename , boolean conditions_to_save )

Saves a map as a file, and returns a boolean of the operation's success. Additionally, map_to_file() can also host a boolean conditional, so that the saving operation will only be executed when it evaluates as true.

When map_to_file() saves, if the specified filename does not exist, it will create a new file of that name, and store the data inside of it. If map_to_file()'s specified save filename already exists, all data inside of the file will be overwritten, and it will only contain the elements in the saved map at the time of execution. In other words, saving over a file will destroy the data stored within it, and replace it with the specified map (at the time of saving). It is also worth note that saved map data is not directly tied to any particular map - only to its key and slice variable types.

If map_to_file() is called from within a script, it will automatically save the resulting file in the KoLMafia\Scripts\ directory. However, if map_to_file() is called from within a library function, the resulting file will be saved in the KoLMafia\Data\ directory. For reference, file_to_map() calls load similarly.

When saved in a file, map data takes on the form:

[key1]        [key2 (if multi-key)]        [...]        [slice1]        [slice2 (if multi-slice (a record))]       [...]

As map_to_file() is KoLMafia's only local (HD) I/O extension, it is an invaluable tool for the scripter; useful for everything from saving script states for resumes, data for use/analysis/backup, and even script de-bugging. However, for those wishing to use map_to_file() for the purposes of saving script states or data, the building of fail-safes against failed loads (such as regular backups), and regular re-evaluations of stored data for inaccuracies, particularly for the purpose of guarding against failed saves.

(Usage Example) Generating data from a user, then calling map_to_file() in the script to save it for later:

#The "What do you like?" script, v9.23b

#First, a declaration of the custom class (for use as the map's slices)
record personal_preference {
   string item_name;
   boolean like_it;
};

#Next, we fill out the .item_name field of the map slices we're using. These will be used later as a plugin for the questions.

personal_preference[int] likes_and_dislikes;
likes_and_dislikes[1].item_name = "Toffee";
likes_and_dislikes[2].item_name = "Sunshine";
likes_and_dislikes[3].item_name = "Onions";
likes_and_dislikes[4].item_name = "Sleep Deprivation";
likes_and_dislikes[5].item_name = "The Kingdom of Loathing";

#We set up a loop with a 'counter' variable, and tell it to go from "q = 1" all the way to "q = [Number of keys in the map]"
for q from 1 upto count(likes_and_dislikes) {
   
   #We create a pop-up confirmation "dialogue box", which (by its KoLMafia definition) will present the user with yes/no options
   if( user_confirm( "Do you like "+likes_and_dislikes[q].item_name+"?" ) == true ) likes_and_dislikes[q].like_it = true;
}

print( "Survey completed successfully! We appreciate your input!" , "Green" );

#Finally, we save the map (questions, answers, and all) to "user_preference.txt" in the KoLMafia\Scripts\ directory,
#While enclosing it in an if() statement, so that were the save to fail, a message notifying the user of the failure will be printed
if( map_to_file( likes_and_dislikes , "user_preference.txt" ) == false ) print( "Your completed survey failed to save." , "Red" );