#Proton (2.0.0-rc1 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 one or more arguments which are the paths to YAML files containing computerised interpretations of Student Robotics scoresheets.
1.0 A proton compliant program MUST be able to files 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 any filenames.
-
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 list to STDOUT if it succeeds.
-
Each element of the list must be a YAML dictionary.
2.1 The dictionaries 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 contain the exact number of outputs in the output list as it was given inputs, or one output in the list if the input was accepted from STDIN.
-
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: 2.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: 2.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: 2.0.0
scores:
#with exit code 0
Missing match number and arena ID
- version: 2.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
A dictionary at root level, not a list
version: 2.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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent