piston-judger

English | 繁體中文

English

A powerful wrapper for the Piston code execution engine, featuring an integrated judger to evaluate outputs and run test cases.

Credits / Acknowledgements

This project uses the Judge Server from Piston by engineer-man. Piston is a high-performance general purpose code execution engine.

The API design for the piston client object is inspired by node-piston by dthree.

Installation

npm install piston-judger

Usage

Basic Usage (Piston Client)

Execute code using the raw Piston client.

import { piston } from "piston-judger";

(async () => {
  // Initialize the client (optional: provide a custom Piston server URL)
  // Default server: https://emkc.org
  const client = piston({ server: "https://emkc.org" });

  // 1. Get available runtimes
  const runtimes = await client.runtimes();
  console.log(runtimes);

  // 2. Execute code
  const result = await client.execute("python", "3.10.0", {
    language: "python",
    version: "3.10.0",
    files: [
      {
        content: 'print("Hello, World!")',
      },
    ],
  });

  console.log(result);
  // Output: { language: 'python', version: '3.10.0', run: { stdout: 'Hello, World!\n', ... } }
})();

Advanced Usage (Piston Judger)

Execute code and judge the output against expected results.

import { pistonJudger, CompareMode } from "piston-judger";

(async () => {
  const judger = pistonJudger({ server: "https://emkc.org" });

  // Execute code
  const executionResult = await judger.execute("c", "10.2.0", {
    language: "c",
    version: "10.2.0",
    files: [
      {
        content: `
                #include <stdio.h>
                int main() {
                    printf("1\\n");
                    return 0;
                }
                `,
      },
    ],
  });

  // Compare the result
  const judgeResult = judger.judge(executionResult, {
    expectedOutput: "1",
    compareMode: CompareMode.LOOSE, // LOOSE ignores trailing whitespace/newlines
  });

  console.log(judgeResult);
  /*
    {
        status: 'AC',
        message: 'Accepted',
        actualOutput: '1\n',
        expectedOutput: '1',
        details: { ... }
    }
    */
})();

Judger Status Codes

The judger returns a status field indicating the result of the execution and comparison:

• AC (Accepted): The output matches the expected output.
• WA (Wrong Answer): The output does not match the expected output.
• CE (Compilation Error): The code failed to compile.
• RE (Runtime Error): The code executed but crashed or returned a non-zero exit code.
• TLE (Time Limit Exceeded): The execution time exceeded the specified limit.
• MLE (Memory Limit Exceeded): The memory usage exceeded the specified limit.
• OLE (Output Limit Exceeded): The output size exceeded the limit.
• EXE (Execution Error): General execution error (e.g., Piston API failure).

Return Object Structure

When using judger.judge(), the returned object contains the following fields:

interface JudgeResult {
  status: JudgeStatus; // 'AC' | 'WA' | 'CE' | 'RE' | 'TLE' | 'MLE' | 'OLE' | 'EXE'
  message: string; // Human-readable status message (e.g., "Accepted")
  actualOutput: string; // The actual stdout produced by the code
  expectedOutput: string; // The expected output used for comparison
  details: {
    memory: number; // Memory usage (bytes)
    runTime: number; // Execution time (ms)
    signal: string | null; // Signal that terminated the process (if any)
    stderr: string; // Standard error output (for debugging CE/RE)
  };
}

繁體中文

這是一個針對 Piston 程式碼執行引擎的強力封裝，內建判題器 (Judger)，可用於評估程式輸出與測試案例比對。

來源說明 / 銘謝

本專案使用由 engineer-man 開發的 Piston 作為 Judge Server (判題伺服器)。 Piston 是一個高效能的通用程式碼執行引擎。

The API design for the piston client object is inspired by node-piston by dthree.

安裝方式

npm install piston-judger

使用方式

基本使用 (Piston Client)

使用原生的 Piston 客戶端來執行程式碼。

import { piston } from "piston-judger";

(async () => {
  // 初始化客戶端 (可選：提供自定義 Piston 伺服器網址)
  // 預設伺服器: https://emkc.org
  const client = piston({ server: "https://emkc.org" });

  // 1. 取得支援的語言環境
  const runtimes = await client.runtimes();
  console.log(runtimes);

  // 2. 執行程式碼
  const result = await client.execute("python", "3.10.0", {
    language: "python",
    version: "3.10.0",
    files: [
      {
        content: 'print("Hello, World!")',
      },
    ],
  });

  console.log(result);
  // 輸出: { language: 'python', version: '3.10.0', run: { stdout: 'Hello, World!\n', ... } }
})();

進階使用 (Piston Judger)

執行程式碼並將輸出與預期結果進行比對 (判題)。

import { pistonJudger, CompareMode } from "piston-judger";

(async () => {
  const judger = pistonJudger({ server: "https://emkc.org" });

  // 執行程式碼
  const executionResult = await judger.execute("c", "10.2.0", {
    language: "c",
    version: "10.2.0",
    files: [
      {
        content: `
                #include <stdio.h>
                int main() {
                    printf("1\\n");
                    return 0;
                }
                `,
      },
    ],
  });

  // 進行判題
  const judgeResult = judger.judge(executionResult, {
    expectedOutput: "1",
    compareMode: CompareMode.LOOSE, // LOOSE 模式會忽略行末空白與換行
  });

  console.log(judgeResult);
  /*
    {
        status: 'AC',
        message: 'Accepted',
        actualOutput: '1\n',
        expectedOutput: '1',
        details: { ... }
    }
    */
})();

判題狀態碼 (Judger Status Codes)

判題器回傳的 status 欄位代表執行與比對的結果：

• AC (Accepted): 程式輸出與預期輸出相符。
• WA (Wrong Answer): 程式輸出與預期輸出不符。
• CE (Compilation Error): 程式編譯失敗。
• RE (Runtime Error): 程式執行期間發生錯誤或崩潰 (非零退出碼)。
• TLE (Time Limit Exceeded): 執行時間超過限制。
• MLE (Memory Limit Exceeded): 記憶體使用量超過限制。
• OLE (Output Limit Exceeded): 輸出大小超過限制。
• EXE (Execution Error): 一般執行錯誤 (例如 Piston API 連線失敗)。

回傳物件結構

使用 judger.judge() 時，回傳的物件包含以下欄位：

interface JudgeResult {
  status: JudgeStatus; // 'AC' | 'WA' | 'CE' | 'RE' | 'TLE' | 'MLE' | 'OLE' | 'EXE'
  message: string; // 易讀的狀態訊息 (例如 "Accepted")
  actualOutput: string; // 程式實際產生的 stdout
  expectedOutput: string; // 用於比對的預期輸出
  details: {
    memory: number; // 記憶體使用量 (bytes)
    runTime: number; // 執行時間 (ms)
    signal: string | null; // 終止程序的訊號 (若有)
    stderr: string; // 標準錯誤輸出 (用於除錯 CE/RE)
  };
}