Map to file: Difference between revisions

From Kolmafia
Jump to navigation Jump to search
VisualWikitext
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:
'''[[boolean]] map_to_file( [[aggregate]] map , [[string]] filename )'''
{{
#vardefine:name|map_to_file}}{{
#vardefine:return_type|boolean}}{{


'''[[boolean]] map_to_file( [[aggregate]] map , [[string]] filename , [[boolean]] conditions_to_save )'''
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}}|
}}|


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.
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|
}}|


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.
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>


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.  
<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>
}}|


<p>''When saved in a file, map data takes on the form:''<pre>[key1]        [key2 (if multi-key)]        [...]        [slice1]        [slice2 (if multi-slice (a record))]      [...]</pre></p>
see_also={{SeeAlso|buffer_to_file|file_to_array|file_to_buffer|file_to_map}}|
}}


 
[[Category:Miscellaneous Functions]]
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.
 
 
<p>''(Usage Example) Generating data from a user, then calling map_to_file() in the script to save it for later:''<pre>#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" );
</pre></p>

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

See Also

buffer_to_file() | file_to_array() | file_to_buffer() | file_to_map()

Retrieved from "https://wiki.kolmafia.us/index.php?title=Map_to_file&oldid=8839"