File to map

boolean file_to_map( string file_to_load , aggregate map_to_fill )

boolean file_to_map( string file_to_load , aggregate map_to_fill , boolean condition_for_loading )

Loads a map from a saved file, and returns a boolean of the operation's success. While all that is required to execute file_to_map() is the saved file's name and a compatible map, it can also contain a conditional that must evaluate as true to execute the file-map load.

If file_to_map() is called from within a script, it will automatically load the specified filename from the KoLMafia\Scripts\ directory (map_to_file()'s automatic in-script save location). If file_to_map() is called from within a library function, it will load the specified filename from the KoLMafia\Data\ directory (the save location of map_to_file() when run within a library function).

A script example of loading a pre-defined map from a file:

#Loading (and displaying) an arbitrary map from a file
string[int] favorite_things;

if( file_to_map( "ponies_and_candycanes.txt" , favorite_things ) == true )
{
   print( "All of your favorite things have come here to KoLMafia to play! Yay! There's:" , "#FF6666" );
   for cycle from 1 upto (count(favorite_things)-1)
   {
      print( ""+favorite_things[cycle]+", and..." , "#FF00CC" );
   }
   print( ""+favorite_things[count(favorite_things)]+", oh my!" , "#FF00CC" );
}
else
{
   print( "Your favorite things failed to load. Apparently they don't love you back." , "Red" );
}

Would obviously produce a different output depending on what you had saved in the list. For example, were the contents of "ponies_and_candycanes.txt":

1      Sunshine
2      Cabbage
3      Computers
4      The Sound of Music
5      Paddington Bear

Would yield an output of:

All of your favorite things have come here to KoLMafia to play! Yay! There's:
Sunshine, and...
Cabbage, and...
Computers, and...
The Sound of Music, and...
Paddington Bear, oh my!

Formatting Needed