The Math API

This is a very simple API which specifies four mathematical operations and several modes of error handling. It is the model API for Catechesis examples.

Version

This is version 1.000 of 9 Jul 2010.

Data Formatting

The send object should be formatted thus:

  { "command":"OPERATION",
    "operands":[ x, y, ..., z ] }

Where OPERATION is one of the operations defined below, and x, y, ..., z are the values to be acted upon..

The returned data (and the expect value) should be formatted thus:

  { "command":"OPERATION", "result":RESULT }

Where OPERATION is the operation specified in the sent object, and RESULT is the result of evaluating the given operation with the given operands.

In the case of an error, the value of the "result" key should be the string "ERROR", and a third key, "err_msg", should be added. It will hold the human-readable message describing the problem.

  { "command":"OPERATION", "result":"ERROR", "err_msg":"MESSAGE" }

Operations

There are five valid operations:

add

Expects two integer operands. The operands will be added together and the result returned.

subtract

Expects two integer operands. The second will be subtracted from the first and the result returned.

multiply

Expects two integer operands. The operands will be multiplied together and the result returned.

divide

Expects two integer operands. The first will be divided by the second and the result returned.

quit

A special case which instructs the program to terminate execution. Has no operands.

Errors

If no command is found, err_msg should be set to "No command found. Invalid message".

If an unrecognized command is found, err_msg should be set to "Unknown command: COMMAND".

If the value of operands does not evaluate to a list, err_msg should be set to "The value of operands must be usable as a list".

If an operand is missing, err_msg should be set to "Missing operand: OPERATION requires X but Y were found".

If an operand is not an integer where it is required to be, err_msg should be set to "Non-integer operand found: OPERAND".

If the second operand of a divide command is zero, err_msg should be set to "Division by zero is undefined".