ScoreLang

A domain-specific language (DSL) for describing football/soccer league tournaments and computing statistics.

ScoreLang lets you define leagues, teams, players, and match results in a human-readable format, then automatically generates points tables, top scorers, assist leaders, and discipline statistics.

Features

• Declarative DSL - Define leagues, teams, players, and matches in a clean, readable syntax
• Full match tracking - Goals with types (open play, penalty, free kick, header, own goal, tap-in), assists, cards, stoppage time
• Automatic statistics - Points tables, top scorers, top assists, discipline stats
• Multiple output formats - ASCII tables, JSON, CSV
• Programmatic API - Use as a library in your own projects

Installation

npm install scorelang

Or clone and build from source:

git clone https://github.com/yourusername/scorelang.git
cd scorelang
npm install
npm run build

Quick Start

Create a file called tournament.sl:

league "Premier League" {
    season "2024-25"
    
    teams {
        MUN: "Manchester United"
        ARS: "Arsenal"
    }
    
    players {
        MUN: [Rashford #10, Bruno #8]
        ARS: [Saka #7, Odegaard #8]
    }
}

match @1 {
    date: 2024-08-17
    venue: "Old Trafford"
    
    MUN 2 - 0 ARS
    
    goals {
        45+2' Rashford (MUN) -> PK
        78'   Bruno (MUN)    -> open_play, assist: Rashford
    }
    
    cards {
        32' Saka (ARS) -> yellow
    }
}

Run it:

npx scorelang tournament.sl

Output:

Premier League 2024-25 - Points Table

Pos  | Team                     | P    | W    | D    | L    | GF   | GA   | GD    | Pts  
-----+--------------------------+------+------+------+------+------+------+-------+------
1    | Manchester United        | 1    | 1    | 0    | 0    | 2    | 0    | +2    | 3    
2    | Arsenal                  | 1    | 0    | 0    | 1    | 0    | 2    | -2    | 0    

CLI Usage

# Show points table (default)
scorelang tournament.sl

# Show specific statistics
scorelang tournament.sl --scorers    # Top scorers
scorelang tournament.sl --assists    # Top assists
scorelang tournament.sl --cards      # Discipline stats
scorelang tournament.sl --all        # All statistics

# Output formats
scorelang tournament.sl --format json
scorelang tournament.sl --format csv > output.csv

# Debug options
scorelang tournament.sl --tokens     # Dump lexer tokens
scorelang tournament.sl --ast        # Dump parsed AST

CLI Flags

Flag	Alias	Description
--table	-t	Show points table
--scorers	-s	Show top scorers
--assists	-a	Show top assists
--cards	-c	Show discipline stats
--all		Show all statistics
--format	-f	Output format: table, json, csv
--tokens		Dump lexer tokens (debug)
--ast		Dump parsed AST (debug)

Programmatic API

import { analyzeTournament, parseSource, interpret } from 'scorelang';

const source = `
league "My League" {
    season "2024"
    teams {
        ABC: "Team ABC"
        XYZ: "Team XYZ"
    }
    players {
        ABC: [Player1 #10]
        XYZ: [Player2 #7]
    }
}

match @1 {
    date: 2024-01-01
    venue: "Stadium"
    ABC 1 - 0 XYZ
    goals {
        55' Player1 (ABC) -> open_play
    }
}
`;

// Full analysis in one call
const { league, analytics } = analyzeTournament(source);

console.log(analytics.pointsTable);
console.log(analytics.topScorers);

// Or step by step
import { tokenize } from 'scorelang';

const tokens = tokenize(source);      // Lexer
const ast = parseSource(source);      // Parser
const result = interpret(ast);        // Interpreter

DSL Syntax Reference

League Declaration

league "League Name" {
    season "2024-25"
    
    teams {
        CODE: "Full Team Name"
    }
    
    players {
        CODE: [PlayerName #jersey, AnotherPlayer #number]
    }
}

Match Declaration

match @ID {
    date: YYYY-MM-DD
    venue: "Stadium Name"
    
    HOME score - score AWAY
    
    goals {
        MM' Scorer (TEAM) -> type
        MM' Scorer (TEAM) -> type, assist: Assister
        MM+SS' Scorer (TEAM) -> type    // Stoppage time
    }
    
    cards {
        MM' Player (TEAM) -> yellow
        MM' Player (TEAM) -> red
    }
}

Goal Types

Type	Description
open_play	Goal from open play
PK	Penalty kick
free_kick	Direct free kick
header	Header goal
own_goal	Own goal
tap_in	Tap-in goal

Time Format

• 45' - Regular time (minute 45)
• 45+2' - Stoppage time (45th minute + 2 minutes added)

Comments

// Single line comments are supported

Architecture

src/
├── lexer/          # Tokenizer
│   ├── tokens.ts   # Token types and keywords
│   └── lexer.ts    # Lexer implementation
├── parser/         # Parser
│   ├── ast.ts      # AST node definitions
│   └── parser.ts   # Recursive descent parser
├── interpreter/    # Interpreter & analytics
│   ├── model.ts    # Runtime model types
│   ├── interpreter.ts  # AST → Model
│   └── analytics.ts    # Statistics computation
├── cli/            # Command-line interface
│   ├── app.ts      # Stricli app definition
│   ├── commands.ts # CLI commands
│   └── formatter.ts    # Output formatters
├── api/            # Public API
│   └── index.ts    # Exports
└── bin/
    └── cli.ts      # CLI entry point

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Run in development (with Bun)
bun run src/bin/cli.ts tournament.sl

Points Calculation

Standard football league points:

• Win: 3 points
• Draw: 1 point
• Loss: 0 points

Table sorting: Points → Goal Difference → Goals For

License

MIT