Does file_to_map() ever return false?

philmasterplus

Active member
file_to_map() is extremely forgiving. It will return true if:
  • The file does not exist
  • The file's contents do not match the map used
  • The file is a binary file (e.g. KoLmafia's own JAR file)
  • The file path is empty or invalid (e.g. "!@#$%^")
  • The file path is actually a directory (e.g. "data/")
  • The file path is outside KoLmafia's root directory
  • The file path is a nonexistent URL (e.g. "http://www.please-return-false.com/")
@MCroft discovered that using "http://" causes the script to abort. Nevertheless, the return value is unhelpful.

This behavior has been around for a long time. I checked as far as KoLmafia v12.0 (released on 2008), and file_to_map() still returned true for nonexistent files. I therefore assume it's not a bug.

Is the return value relevant at all? It seems the function always returns true.
 

fronobulax

Developer
Staff member
First I see recent fingerprints of yours on the wiki entry so thank you for helping to keep the wiki useful and up to date.

I see two cases where it would return false. One is if there is a problem, at the Java level, with getting a reader. Last time I looked at the readers I seem to remember that they were determined not to return null and there was a belief/convention that the caller would rather have a reader that is empty than make the caller distinguish between file not found, file cannot be accessed or any of the other things that can impede file IO.

The second case is when the reader cannot read which I think means something like the map has x delimited fields and the data has one or more lines with y delimited fields and x != y.

There was also a time when Boolean returns for ash functions were expected to be true unless there was an ash level error, I think.

The behavior has been around and the work around in ash has been to use the count function. If the count is zero then something went wrong and that is all the script really needs.

So what you are seeing is a deliberate convention - observed at the Java level and imposed on scripters. "Don't worry about file I/O and similar issues. Just allow for the possibility of no data being read". The false is not especially helpful but might help handle the case where there was data but not the right data.

Basically, working as designed and the design can be justified although there are always alternatives.
 

philmasterplus

Active member
First I see recent fingerprints of yours on the wiki entry so thank you for helping to keep the wiki useful and up to date.

You're welcome!

Also, thank you for the insight. I love learning about past design decisions and other historical tidbits.

I suppose it would be safe to declare that (1) the status quo is intentional, and (2) we should check both the return value and the count(), just in case.
 
Top