#Proton (1.0.0-rc2 SemVer)
Proton is a protocol for Student Robotics match scoring scripts.
##Execution
-
A proton compliant program MUST be either a script including a
#!line or be a binary. -
A proton compliant program MUST be capable of being exec'd on a supported platform. This typically means that it has the executable bit set.
-
A proton compliant program MUST run on Linux.
-
A proton compliant program MUST NOT have any side effects beyond printing to STDERR, STDOUT and having a return code. This precludes: modifying its input, writing to a database or any other kind of I/O.
-
A proton compliant program MUST always give the same output for a given input.
##Inputs
Note: A TLA is defined as a string matching the regex [a-zA-Z]{3}[a-zA-Z0-9]*.
-
A proton compliant program MUST consume a single argument which is the path to a YAML file containing a computerised interpretation of a Student Robotics scoresheet.
1.0 A proton compliant program MUST be able to read a file from both absolute and relative paths.
1.1 A proton compliant program MUST accept YAML files with the proton format, these are of the form:
match_number: integer
arena_id: integer or string representing arena identity
teams: dictionary with 2-4 key value pairs:
TLA: dictionary with key value pairs:
zone: an integer between 0 and 3 inclusive
disqualified: an optional boolean, defaulting to false
present: an optional boolean, defaulting to true
any other key value pairs representing data about scoring specific
to the year and game.
1.2 A proton compliant program MUST exit with 1 if the input is malformed
YAML or does not comply with rule 1.1
-
A proton compliant program MUST consume YAML from stdin if it is not given a filename.
-
A proton compliant program MAY refuse to process an input if it detects nested scoring values it is unable to process. If this occurs it MUST exit with 2.
##Outputs
-
A proton compliant program MUST print a YAML dictionary to STDOUT if it succeeds.
1.1 The output must be of the form:
version: string representing version of the proton protocol implemented i.e. (1.0.0)
match_number: an integer representing the match number
arena_id: integer or string representing arena identity
scores: dictionary with exactly as many keys there were teams in the input
TLA: dictionary with exactly the key value pairs
score: numeric value, representing team's score (game points).
present: boolean, value from the input
disqualified: boolean, value from the input
zone: integer, the zone the team was in
-
A proton compliant program MUST exit with 0 if it succeeds.
-
A proton compliant program's output to STDOUT MUST be considered unusable if it fails.
-
A proton compliant program MAY print to STDERR under any circumstances.
##Examples
###Valid inputs
match_number: 3
arena_id: A
teams:
CLF:
squares : [[1,2,1],[1,0,1],[0,0,0]]
PSC:
squares : [[0,0,0],[0,2,0],[0,p,0]]
BGR:
squares : [[0,0,0],[3,0,0],[0,0,0]]
QEH1:
squares : [[0,0,0],[6,0,0],[0,0,0]]match_number: 4
arena_id: B
teams:
CLF:
present : false
squares : [[1,2,1],[1,0,1],[0,0,0]]
PSC:
squares : [[0,0,0],[0,2,0],[0,p,0]]
QEH:
squares : [[0,0,0],[6,0,0],[0,0,0]]###Invalid inputs
match_number: 3
arena_id: A
teams:
1:
present : false
squares : [[1,2,1],[1,0,1],[0,0,0]]
PSC:
squares : [[0,0,0],[0,2,0],[0,p,0]]
BGR:
squares : [[0,0,0],[3,0,0],[0,0,0]]
QEH:
squares : [[0,0,0],[6,0,0],[0,0,0]]match_number: 3
arena_id: B
teams:
CLF:
present : 1.0
squares : [[1,2,1],[1,0,1],[0,0,0]]
PSC:
squares : [[0,0,0],[0,2,0],[0,p,0]]
BGR:
squares : [[0,0,0],[3,0,0],[0,0,0]]
QEH:
squares : [[0,0,0],[6,0,0],[0,0,0]]###Valid responses
version: 1.0.0
match_number: 3
arena_id: A
scores:
CLF:
score: 41.0
present: true
disqualified: false
zone: 0
PSC:
score: 12.0
present: true
disqualified: false
zone: 1
BGR:
score: 7.0
present: true
disqualified: false
zone: 2
QEH:
score: 18.0
present: true
disqualified: false
zone: 3
#with exit code 0
#with exit code 1
#with exit code 2
###Invalid responses
No match number
version: 1.0.0
scores:
CLF:
score: 41.0
present: true
disqualified: false
PSC:
score: 12.0
present: true
disqualified: false
QEH:
score: 18.0
present: true
disqualified: false
BGR:
score: 7.0
present: true
disqualified: false
#with exit code 0
Many missing values
version: 1.0.0
scores:
#with exit code 0
Missing match number and arena ID
version: 1.0.0
scores:
CLF:
score: 41.0
present: true
disqualified: false
PSC:
score: 12.0
present: true
disqualified: false
BGR:
score: 7.0
present: true
disqualified: false
QEH:
score: 18.0
present: true
disqualified: false
#with exit code 1