Strategic Primer Subset Programs User Documentation

Over the last few years of the current campaign of Strategic Primer, I’ve occasionally had situations where I had a “world map” and players’ “known world” maps, but the latter weren’t quite right according to the former. I needed a way to find these discrepancies so I could fix them. So I wrote a program to test whether one map was a “strict subset” of another. Today’s post is documentation of—a “user’s guide” for—this tool.

There are actually two versions of the “subset app,” one that runs in a terminal window and one that wraps that in its own window. As with the exploration program, to start either program, invoke the “viewer” binary executable and pass “-s” or “–subset” as a command-line option, and additionally pass “-c” or “–cli” to get the command-line version.

In addition to these switches, both versions require the user to pass at least two filenames as command-line arguments: first the “master” map that the others will be tested against, and thereafter at least one “subordinate” map.

Subset program before printing resultsAfter either program parses and loads the “master” map, it prints a line explaining what to look for in the output to come. (The “graphical” version is merely a wrapper around the command-line version. It adds colors to indicate each final verdict, but is otherwise essentially identical.)

For each “subordinate” map, then, it first prints the filename and reads and parses the file. If there are any errors that prevent the file from being read, in theory it’ll print some message describing the error, followed by “FAIL” (in red in the GUI). (I say “in theory” because in practice it’s possible to make it print a stack trace to the console and hang the GUI, rather than showing the error “properly,” if you’re trying to make it error out without writing broken but well-formed XML.)

If there aren’t any errors, it’ll test whether the current “subordinate” map is a “strict subset” of the “master” map. Now, “strict subset” doesn’t really mean strict subset; there are certain fixtures that are ignored—caches, for example, because when a player finds one it’s supposed to be removed from the main map, and left in the player’s map only to show where a cache was found. But other than caches, “text” (notes from me indicating something that doesn’t fit into any of the existing categories), and traces (or tracks) of animals, anything that’s in the subordinate map at any place that isn’t in the same place in the main map “sticks out,” and causes the program to print “WARN” (in the GUI this is in yellow). If there are no such out-of-place fixtures, the program prints (in green if in the GUI) “OK”.

The program also “warns” rather than returning either an error or success if the maps’ sizes don’t match.

subset_2Originally, I made this “fail-fast.” It would run essentially silently, and the first out-of-place fixture would make it return the result without checking any other locations. But that’s not really helpful, so now it prints a “complete” list of things that are out of place before printing the result.

While all this is, as you might expect, rather slow—reading and parsing a map file isn’t a trivial process, and the more of the “master” map the “subordinate” map includes the longer subset-testing takes—if it seems to hang after printing the explanatory first line, that’s a bug I fixed when I encountered it in preparing this post; you’ll need to update to a version later than 0.4.2670, or use the command-line version rather than the GUI.

If you use this program and run into any (other) problems, please report them either in the issue tracker or by contacting me directly.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s