7 — Changing an API

Due Sunday, 28 February, midnight Tuesday, 1 March, noon

Guy Steele (Scheme, Java, Fortress) said that "behind every API lurks a programming language."

Your software architect has determined that he made a serious mistake with the design of the API for 6 — Incremental refinement, the second step. Since APIs are difficult-to-impossible to change once they have escaped "into the wild," he is determined to change it immediately before anything goes wrong.

Here is his reasoning. While the API may support the player with the silly deterministic strategy from last time, the proper way to formulate the result is not in terms of concrete players and species, but it terms of "pointers" to the given players and species. That way a player can pick players and species without any ambiguity and without adhering to a pre-determined strategy.

In contrast to the player and species choices, the results for fat-tissue traits already live up to this level of flexibility. A player does not just say "fill up this species’ fat-tissue card" but also specifies the number of food tokens to be taken. Once you install a player with a different strategy, that player may take however much food is desired, not necessarily enough to fill up the capacity of the card.

Task 1 Design an echo program—name it xstream—that accepts JSON from STDIN and writes it back to STDOUT. Your program does not have to preserve white space. When STDIN is closed, the program adds a JSON object with one field, labeled "count" whose value is the number of JSON expressions read and written.

Effect When the program encounters text that does not live up to the JSON specification, the program may throw an exception.

One Bonus Point If your program shuts down cleanly for text that violates the JSON specification, you get one bonus point.

Delivery Create a folder named Streaming and place the xstream executable into this folder.

One Bonus Point Also place a compile script into this folder.

question		answer
Can we please get a recording of the demo?		The recording below shows inputs in pink and outputs in purple:     $ ./xstream     1     1     [1,     2]     [1,2]     {"a":3}     {"a":3}     []{"b"     []     :     4     }     {"b":4}     {"count":5} Note how output appears as soon as STDIN contains a complete JSON object or array even if the same line already contains the beginning of the next JSON element.
What does "shut down cleanly" mean?		It terminates with exit status 0, i.e., successfully. In Java or Python, it doesn’t let an exception terminate the execution.
How does a user close STDIN?		Press ^D (control d) when you are working on the Linux delivery machines. If you are developing on another platform, you need to use different controls for your manual runs (not tests). For example, on Windows, use ^Z.
Is xstream supposed to print the JSON objects when the ‘stream’ is closed (end of file)		No, as you could see in my demo, your program prints each JSON expressions as soon as it is read. Tony adds that "if a program is connected to your program (via pipe), it should be able to send the two bytes [ and ] and expect to read an empty array on STDOUT from your program immediately (which is its SDTIN).
What separates JSON expressions?		In this course, the rule is that JSON objects and arrays are recognizable as such without separation via white space (space, tab, newline, etc). In contrast, booleans, numbers, and strings must be separated by white space to be recognized as separate JSON objects. Thus, 34 is the number thirtyfour and 3 4 denotes two numbers.

Task 2 Fix the mistakes in your solution of 5 — Incremental refinement, a minimal start discovered via our test fest. The revised test fest matrix respects the rules of the game for all tests.

question		answer
Should we fix the mistakes for the code base of 5 — Incremental refinement, a minimal start?		You need to fix the mistakes for the evolving code base that will become the complete Evolution game platform.

Task 3 Modify your method from 6 — Incremental refinement, the second step so that the result describes the chosen feeding via indexes into the sequences of given players and species.

While the data representation of your method changes, the information it delivers remains the same. Hence the infer-able knowledge also remains the same.

Task 4 Adjust your test harness from 6 — Incremental refinement, the second step so that it respects the following modified JSON specification.

Delivery Use the instructions from 6 — Incremental refinement, the second step for the deliverable artifacts of all but the first task.