@jutge.org/toolkit 4.2.3 → 4.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/sty/judgeit.sty +9 -13
- package/dist/index.js +547 -693
- package/docs/problem-anatomy.md +145 -147
- package/package.json +9 -10
- package/toolkit/doctor.ts +1 -0
- package/toolkit/generate.ts +6 -1
- package/toolkit/make.ts +1 -1
- package/toolkit/upload.ts +2 -4
package/docs/problem-anatomy.md
CHANGED
|
@@ -4,26 +4,36 @@ This document describes the anatomy of a common problem in [Jutge.org](https://j
|
|
|
4
4
|
|
|
5
5
|
## Terminology
|
|
6
6
|
|
|
7
|
-
A **problem** is a programming exercise meant to be solved by writing a program. All the elements of a problem are stored in a problem folder. Problems are meant to be uploaded to
|
|
7
|
+
A **problem** is a programming exercise meant to be solved by writing a program. All the elements of a problem are stored in a problem folder. Problems are meant to be uploaded to Jutge.org where users can submit their solutions to be evaluated. The New Jutge Toolkit is a command line app to create, manage, and upload problems in Jutge.org.
|
|
8
8
|
|
|
9
|
-
The task of the problem is described in the **problem statement**. Problem statements may be available in several human languages
|
|
9
|
+
The task of the problem is described in the **problem statement**. Problem statements may be available in several human languages. One of them is considered the **original language** of the problem, and the others are considered **translations**. Problem statements are written in LaTeX format and are processed to generate PDF, HTML, Markdown, and text files that are shown to users. Problem statements may include text, math, figures, code snippets, test cases, etc. Jutge.org provides LaTeX macros to organize and facilitate the writing of problem statements.
|
|
10
10
|
|
|
11
|
-
A problem contains a **golden solution**, which is a program that solves the problem correctly. The golden solution is used to generate the correct outputs for the test cases of the problem. A problem may also contain several alternative solutions in different programming languages. When a user submits a solution to a problem in some programming language, the system selects the most appropriate solution to evaluate the submission against.
|
|
11
|
+
A problem contains a **golden solution**, which is a program that solves the problem correctly. The golden solution is used to generate the correct outputs for the test cases of the problem. A problem may also contain several alternative solutions in different programming languages. When a user submits a solution to a problem in Jutge.org with some programming language, the system selects the most appropriate solution to evaluate the submission against.
|
|
12
12
|
|
|
13
|
-
A problem contains several **test cases**, each consisting of an input file and a correct output file. The test cases are used to evaluate the correctness of user submissions. Some test cases are **public** and
|
|
13
|
+
A problem contains several **test cases**, each consisting of an input file and a correct output file. The test cases are used to evaluate the correctness of user submissions. Some test cases are **public** and might be shown to users, while others are **private** and are hidden from users. Public test cases may be marked as **sample** test cases and are included in the problem statement to illustrate the input/output format and clarify the problem. The correct output file for each input test case is generated automatically by running the golden solution on that input file. Alternative solutions are checked against the test cases to ensure they produce the same outputs as the golden solution.
|
|
14
14
|
|
|
15
|
-
Test cases are usually written by hand or generated using **test
|
|
15
|
+
Test cases are usually written by hand or generated using **test case generators**. A test case generator is a program that produces input files for test cases, often using randomization or specific patterns to cover different scenarios. Generator programs help create a diverse set of test cases that thoroughly test the correctness and efficiency of user submissions.
|
|
16
16
|
|
|
17
|
-
By default, the correctness of user submissions is evaluated by comparing their output files with the correct output files bit
|
|
17
|
+
By default, the correctness of user submissions is evaluated by comparing their output files with the correct output files bit by bit. However, some problems may use custom **checkers** to evaluate the correctness of submissions. Some predefined checkers are available: the elastic checkers do not care about the order of the output lines, the epsilon checker allows for small numerical differences, etc. In addition, custom checkers can be implemented as external programs. An external checker is a program that takes the input file, the user's output file, and the correct output file as input and produces a verdict (Accepted, Wrong Answer, Presentation Error, etc.) based on specific criteria defined for the problem.
|
|
18
18
|
|
|
19
19
|
Some problems may include **scoring** information, which specifies how many points are awarded for passing certain test cases or groups of test cases. This allows problems to have partial credit for submissions that pass some but not all test cases.
|
|
20
20
|
|
|
21
|
-
Most problems are meant to be solved by a complete program that reads from standard input and writes to standard output. However, some problems may require users to implement specific functions or methods that will be called by a provided **main program**. In such cases, the problem specifies the function signature and behavior that users must implement. In addition, some problems may provide a **code template**, which is a code skeleton that users can fill in with their own implementation. This might be helpful to guide users on how to structure their solution, to provide utility functions or to check they are able to integrate their code correctly.
|
|
21
|
+
Most problems are meant to be solved by a complete program that reads from standard input and writes to standard output. However, some problems may require users to implement specific functions or methods that will be called by a provided **main program**. In such cases, the problem specifies the function signature and behavior that users must implement. In addition, some problems may provide a **code template**, which is a code skeleton that users can fill in with their own implementation. This might be helpful to guide users on how to structure their solution, to provide utility functions, or to check they are able to integrate their code correctly.
|
|
22
22
|
|
|
23
|
-
A certain class of programming languages can have their input test cases be replaced by expressions that are evaluated directly rather than read. This is the case for the RunPython, RunHaskell or RunClojure programming languages.
|
|
23
|
+
A certain class of programming languages can have their input test cases be replaced by expressions that are evaluated directly rather than data that is read. This is the case for the RunPython, RunHaskell, or RunClojure programming languages.
|
|
24
24
|
|
|
25
25
|
A problem may also contain **awards**, which are images and text that users receive when they solve the problem for the first time. These awards are meant to motivate users and recognize their achievements.
|
|
26
26
|
|
|
27
|
+
There are four types of problems in Jutge.org:
|
|
28
|
+
|
|
29
|
+
- **Standard problems**: The most common type of problems, where users submit complete programs that read from standard input and write to standard output. This type of problem also includes **function problems**: Problems where users must implement specific functions or methods that will be called by a provided main program.
|
|
30
|
+
|
|
31
|
+
- **Graphic problems**: Similar to standard problems but involve graphical output to file `output.png` rather than standard output, typically (but not necessarily) solved using Python's graphical libraries.
|
|
32
|
+
|
|
33
|
+
- **Games**: Problems where users must implement an AI to play a game against other users or predefined strategies. These problems often involve turn-based gameplay and require users to implement specific functions to decide their moves. These are not covered in this document.
|
|
34
|
+
|
|
35
|
+
- **Quizzes**: Problems where users must answer multiple-choice questions. These are not covered in this document.
|
|
36
|
+
|
|
27
37
|
## Problem structure
|
|
28
38
|
|
|
29
39
|
A problem is a folder with `.pbm` extension that can be structured in two ways:
|
|
@@ -67,46 +77,24 @@ A problem is a folder with `.pbm` extension that can be structured in two ways:
|
|
|
67
77
|
└── problem.yml
|
|
68
78
|
```
|
|
69
79
|
|
|
70
|
-
The above structures are just two examples of the structure that a problem can have and therefore should only be considered as a guideline. The purpose of all the files is explained later
|
|
80
|
+
The above structures are just two examples of the structure that a problem can have and therefore should only be considered as a guideline. The purpose of all the files is explained later in this file.
|
|
71
81
|
|
|
72
82
|
The first method is preferred whenever possible, as it avoids duplication of files and is easier to maintain. The second method is discouraged and should be used only when absolutely necessary, for instance when the test cases or the solutions differ between languages.
|
|
73
83
|
|
|
74
|
-
## Problem files TODO
|
|
75
|
-
|
|
76
|
-
A problem should contain the following files:
|
|
77
|
-
|
|
78
|
-
- `solution.*`: One or more solutions to the problem in different languages. See [Solutions](#solutions) for more information.
|
|
79
|
-
- `handler.yml`: Contains the information of how to handle the problem. See [Handler](#handler) for more information.
|
|
80
|
-
- `tags.yml`: Contains all the tags associated to the problem as a YAML list of words. Only for instructors, can be left empty. See [Tags](#tags) for more information.
|
|
81
|
-
- `*.inp`: All the input test sets. See [Test cases](#test-cases) for more information.
|
|
82
|
-
- `*.cor`: All the correct files. Those are generated automatically by the toolkit from the `solution.*` file. See [Test cases](#test-cases) for more information.
|
|
83
|
-
- `problem.lang.tex`: Statement LaTeX file for language `lang`. See [Problem statement](#problem-statement) for more information.
|
|
84
|
-
- `problem.lang.yml`: Contains the problem information in language `lang`. See [Problem metadata](#problem-metadata) for more information.
|
|
85
|
-
- `problem.lang.pdf`: Formatted PDF statement for language `lang`. These are generated automatically by the toolkit.
|
|
86
|
-
|
|
87
|
-
Additionally, the problem can contain the following optional files:
|
|
88
|
-
|
|
89
|
-
- `award.png`: Image of the award users will obtain when they get the problem accepted for the first time. See [Awards](#awards) for more information.
|
|
90
|
-
- `award.html`: HTML description of the award users will obtain when they get the problem accepted for the first time. See [Awards](#awards) for more information.
|
|
91
|
-
- `code.*`: Code provided in the problem to users that is given as a solution template (a function with blanks to be filled, for example).
|
|
92
|
-
- `distiller.yml`: File used to specify the parameters of the distillation process. See [Distilled test cases](#distilled-test-cases) for more information.
|
|
93
|
-
- `scores.yml`: File that describes the scoring of a problem. See [Scoring](#scoring) for more information.
|
|
94
|
-
- `*.ops`: File used to specify some limits for the correction of the problem. See [Test options](#test-options) for more information.
|
|
95
|
-
|
|
96
84
|
## Problem statement
|
|
97
85
|
|
|
98
|
-
Problem
|
|
86
|
+
Problem statements are stored in LaTeX files named `problem.lang.tex`, where `lang` denotes the ISO 639-1 code of the language for which the statement is given (currently `ca`, `en`, `es`, `fr`, `de` for Catalan, English, Spanish, French, and German respectively). Problem statements make use of certain macros.
|
|
99
87
|
|
|
100
88
|
### Structure
|
|
101
89
|
|
|
102
90
|
The typical structure of a problem statement is the following:
|
|
103
91
|
|
|
104
92
|
```latex
|
|
105
|
-
\Problem{The title of the problem using LaTeX}
|
|
93
|
+
\Problem{The title of the problem using \LaTeX}
|
|
106
94
|
|
|
107
95
|
\Statement
|
|
108
96
|
|
|
109
|
-
|
|
97
|
+
A section that provides the statement of the problem.
|
|
110
98
|
|
|
111
99
|
\medskip
|
|
112
100
|
|
|
@@ -114,27 +102,27 @@ Different paragraphs should be separated by the \medskip command.
|
|
|
114
102
|
|
|
115
103
|
\Input
|
|
116
104
|
|
|
117
|
-
This section describes the input of the problem.
|
|
105
|
+
This optional section describes the input of the problem.
|
|
118
106
|
|
|
119
107
|
\Output
|
|
120
108
|
|
|
121
|
-
This section describes the output of the problem.
|
|
109
|
+
This optional section describes the output of the problem.
|
|
122
110
|
|
|
123
111
|
\Sample
|
|
124
112
|
|
|
125
113
|
```
|
|
126
114
|
|
|
127
|
-
The `\Sample` section will
|
|
115
|
+
The `\Sample` section will contain the sample test cases. It is possible to adjust the formatting of the sample test cases: `\SampleOneCol` places input and output test cases one below the other, while `\SampleTwoCol` places them side by side.
|
|
128
116
|
|
|
129
|
-
`RunPython` users should use `\SampleSession` to get their sample test cases properly formatted as interactive Python sessions. [CHECK]
|
|
117
|
+
`RunPython` users should use `\SampleSession` to get their sample test cases properly formatted as interactive Python sessions using `sample.dt`. [CHECK]
|
|
130
118
|
|
|
131
|
-
The title inside the `\Problem{}` macro should match the title in the metadata given in the `problem.lang.yml` file, but the title
|
|
119
|
+
The title inside the `\Problem{}` macro should match the title in the metadata given in the `problem.lang.yml` file, but the title in the LaTeX file can contain math or LaTeX macros whereas the title in the YAML file should be plain text.
|
|
132
120
|
|
|
133
121
|
### Figures
|
|
134
122
|
|
|
135
|
-
Figures can be inserted using the `\FigureL`, `\FigureC
|
|
123
|
+
Figures can be inserted using the `\FigureL`, `\FigureC`, and `\FigureR` macros, which stand for _left_, _center_, and _right_ respectively. These macros have two parameters:
|
|
136
124
|
|
|
137
|
-
1. The formatting of the figure (as in `\includegraphics[...]`).
|
|
125
|
+
1. The formatting parameters of the figure (as in `\includegraphics[...]`).
|
|
138
126
|
|
|
139
127
|
2. The filename of the figure, with no extension. The figure should exist in JPG or PNG format [CHECK]. The use of SVG format might be possible [CHECK]. The use of EPS format is deprecated.
|
|
140
128
|
|
|
@@ -142,17 +130,17 @@ For instance, `\FigureR{width=4.5cm}{image}` will place figure `image` to the ri
|
|
|
142
130
|
|
|
143
131
|
### Quotes
|
|
144
132
|
|
|
145
|
-
In order to enclose texts between quotes, please use the `\q{...}` (single quotes), `\qq{...}` (double quotes) or `\uq{...}` (no quotes, but same style) macros. [TODO: we have to honor/improve this]
|
|
133
|
+
In order to enclose texts between quotes, please use the `\q{...}` (single quotes), `\qq{...}` (double quotes), or `\uq{...}` (no quotes, but same style) macros. [CHECK & TODO: we have to honor/improve this]
|
|
146
134
|
|
|
147
135
|
### Code
|
|
148
136
|
|
|
149
|
-
The `lstlisting`
|
|
137
|
+
The `lstlisting` package may be used in order to include code. Short snippets of code can be written between `@` signs [CHECK & IMPROVE].
|
|
150
138
|
|
|
151
|
-
By default, C++ style is used. It may be changed using standard `lstlisting` definitions
|
|
139
|
+
By default, C++ style is used. It may be changed using standard `lstlisting` definitions such as `\lstset{language=C}`. The `\UseHaskell`, `\UsePython`, and `\UseClojure` macros are shortcuts to use Haskell or Python styling respectively.
|
|
152
140
|
|
|
153
141
|
### Scoring
|
|
154
142
|
|
|
155
|
-
For problems with partial scoring based on passing test cases, use the `\Scoring` macro followed by an
|
|
143
|
+
For problems with partial scoring based on passing test cases, use the `\Scoring` macro followed by an explanation of the scoring method (for example, how many points each test case is worth).
|
|
156
144
|
|
|
157
145
|
### Other sectioning macros
|
|
158
146
|
|
|
@@ -164,7 +152,6 @@ There exist a few other macros that may be used in various situations. Their eff
|
|
|
164
152
|
- `\Specification`
|
|
165
153
|
- `\Interface`
|
|
166
154
|
- `\Hint`
|
|
167
|
-
- `\Scores` [CHECK]
|
|
168
155
|
- `\Tuples`
|
|
169
156
|
- `\ObservationElastic`
|
|
170
157
|
- `\ObservationElasticII`
|
|
@@ -176,13 +163,26 @@ There exist a few other macros that may be used in various situations. Their eff
|
|
|
176
163
|
|
|
177
164
|
### Other macros
|
|
178
165
|
|
|
179
|
-
The `\
|
|
166
|
+
The `\Link{...}` macro provides a hyperlink to another problem (without specified language), e.g., `\Link{P68688}`. It currently just prints the text, but in the future it may be converted to a hyperlink in HTML output.
|
|
180
167
|
|
|
181
|
-
The
|
|
168
|
+
## The `problem.yml` file
|
|
182
169
|
|
|
183
|
-
|
|
170
|
+
Once a problem is uploaded to Jutge.org, a `problem.yml` file is automatically created in the root of the problem folder. This file contains metadata about the problem that is used by the system. **The fields of this file should not be modified by hand**. In it, you will find fields such as the problem identifier (e.g., X12345), its passcode, the time of creation, and the time of the last modification. Importantly, the presence of this file indicates that the problem has already been uploaded to Jutge.org.
|
|
184
171
|
|
|
185
|
-
|
|
172
|
+
If you are creating a problem from a copy of an existing problem, be sure to delete the `problem.yml` file before uploading it to Jutge.org to avoid interfering with the existing problem.
|
|
173
|
+
|
|
174
|
+
Here is an example of a `problem.yml` file:
|
|
175
|
+
|
|
176
|
+
```yml
|
|
177
|
+
problem_nm: X12345
|
|
178
|
+
passcode: 16PbADb1qfDj
|
|
179
|
+
created_at: 2016-01-13T11:33:16.187Z
|
|
180
|
+
updated_at: 2026-01-13T12:47:12.884Z
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## The `problem.lang.yml` files
|
|
184
|
+
|
|
185
|
+
Statement metadata is stored using YAML syntax in files named `problem.lang.yml`, where `lang` denotes the language code for which the metadata is given (`en`, `es`, `ca`, ...).
|
|
186
186
|
|
|
187
187
|
In the case that `lang` denotes the original language of the problem, `problem.lang.yml` should contain the following fields:
|
|
188
188
|
|
|
@@ -192,14 +192,14 @@ In the case that `lang` denotes the original language of the problem, `problem.l
|
|
|
192
192
|
|
|
193
193
|
If `lang` denotes a translation, `problem.lang.yml` should contain the following fields:
|
|
194
194
|
|
|
195
|
-
- `translator`: Full name of the problem translator.
|
|
196
195
|
- `title`: Title of the problem in the translated language.
|
|
196
|
+
- `translator`: Full name of the problem translator.
|
|
197
197
|
- `translator_email`: Email of the problem translator.
|
|
198
198
|
- `original_language`: Code for the original language of the problem.
|
|
199
199
|
|
|
200
|
-
A problem should have one unique original language and may have several translations. All translations should refer to the same original language. The system will find the original author through it.
|
|
200
|
+
A problem should have one unique original language and may have several translations. All translations should refer to the same original language [CHECK]. The system will find the original author through it.
|
|
201
201
|
|
|
202
|
-
All the values for the metadata fields should be given as Unicode
|
|
202
|
+
All the values for the metadata fields should be given as Unicode-based plain text. Remember to enclose them in quotes if they contain special characters such as `:` or `'`.
|
|
203
203
|
|
|
204
204
|
### Examples
|
|
205
205
|
|
|
@@ -220,121 +220,147 @@ translator_email: cmolina@somewhere.mail.com
|
|
|
220
220
|
original_language: ca
|
|
221
221
|
```
|
|
222
222
|
|
|
223
|
-
## The `
|
|
224
|
-
|
|
225
|
-
Once a problem is uploaded to [Jutge.org](https://jutge.org/), a `problem.yml` file is automatically created in the root of the problem folder. This file contains metadata about the problem that is used by the system. The fields of this file should not be modified by hand. In it, you will find fields such as the problem identifier (eg, X12345), its passcode, the time of creation, and the time of the last modification. Importantly, the presence of this file indicates that the problem has already been uploaded to [Jutge.org](https://jutge.org/).
|
|
223
|
+
## The `handler.yml` file
|
|
226
224
|
|
|
227
|
-
|
|
225
|
+
The file `handler.yml` contains the information on how to handle the problem using YAML syntax. These options will tell the toolkit how to compile and execute the problem. The handler must have two options:
|
|
228
226
|
|
|
229
|
-
|
|
227
|
+
- `handler`: `std` (default option), `graphic` (used by some Python3 problems), `quiz` (used for quiz problems), and `game` (used for game problems).
|
|
230
228
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
- `handler`: `std` (default option) and `graphic` (used by some Python3 problems).
|
|
234
|
-
- `source_modifier`: `none` (default option), `structs` (C++ problems that use structs), `no_main` (problems where only a function is requested, in that case you will need to use the optional option `func_name`).
|
|
229
|
+
- `source_modifier`: `none` (default option), `structs` (C++ problems that use structs) [CHECK], `no_main` (problems where only a function is requested; in that case you will need to use the optional option `func_name`).
|
|
235
230
|
|
|
236
231
|
There are also optional arguments that may be used:
|
|
237
232
|
|
|
238
|
-
- `checker`: Option that will tell
|
|
233
|
+
- `checker`: Option that will tell Jutge.org how to compare the user's program output with the problem solution. See [Checker](#advanced-checkers) for more information. Note: the checker option is not used by the toolkit.
|
|
239
234
|
|
|
240
|
-
- `compilers`: Compiler that
|
|
235
|
+
- `compilers`: Compiler that Jutge.org will use to correct the problem. If specified, this will be the only compiler available on the website if a user wants to send their submission. You will find a list of available compilers at https://jutge.org/documentation/compilers. Beware that, for historic reasons, `compilers` is not a list of compilers; it is just a single compiler.
|
|
241
236
|
|
|
242
|
-
- `func_name`: Name of the function requested in case the problem only asks for a function (this must be used along with `source_modifier: no_main`)
|
|
237
|
+
- `func_name`: Name of the function requested in case the problem only asks for a function (this must be used along with `source_modifier: no_main`).
|
|
243
238
|
|
|
244
|
-
- `invisible_main`: If set to `1`, the `main.cc` file will not be provided to users. This is used by problems that do not require
|
|
239
|
+
- `invisible_main`: If set to `1`, the `main.cc` file will not be provided to users. This is used by problems that do not require writing a `main` function.
|
|
245
240
|
|
|
246
|
-
- `presentation_error`: If set to `1
|
|
241
|
+
- `presentation_error`: If set to `1` (by default), the PE (Presentation Error) verdict will be enabled. Otherwise, the verdict will be WA (Wrong Answer) if the files are not identical.
|
|
247
242
|
|
|
248
|
-
- `solution`: Programming language of the solution
|
|
243
|
+
- `solution`: Programming language of the golden solution. By default, it is C++. Currently supported programming languages are C, C++, Java, Python3, Haskell, Clojure, Rust, RunPython, RunHaskell, and RunClojure.
|
|
249
244
|
|
|
250
|
-
- `pylibs`: Problems in Python can allow the usage of certain non
|
|
245
|
+
- `pylibs`: Problems in Python can allow the usage of certain non-standard Python libraries. `pylibs` is a list of libraries that may be used to solve the current problem. For instance, `pylibs: [numpy, networkx]`. By default, this list is empty. Available libraries are at https://jutge.org/documentation/pylibs.
|
|
251
246
|
|
|
252
|
-
|
|
247
|
+
Here is an example of a `handler.yml` file:
|
|
253
248
|
|
|
254
249
|
```
|
|
255
250
|
handler: std
|
|
256
|
-
|
|
251
|
+
solution: Python3
|
|
252
|
+
source_modifier: no_main
|
|
253
|
+
func_name: is_prime
|
|
254
|
+
invisible_main: 1
|
|
257
255
|
```
|
|
258
256
|
|
|
259
|
-
### Limiting
|
|
257
|
+
### Advanced: Limiting time
|
|
260
258
|
|
|
261
|
-
There are two arguments that can be used to determine the maximum time that a submission can take depending on the time the solution took to solve the problem. The submission will have a maximum time to complete the task which is calculated with the following function:
|
|
259
|
+
There are two arguments in `handler.yml` that can be used to determine the maximum time that a submission can take depending on the time the setter solution took to solve the problem. The submission will have a maximum time to complete the task which is calculated with the following function:
|
|
262
260
|
|
|
263
261
|
`Maximum submission time: solution_time * time_factor + time_constant.`
|
|
264
262
|
|
|
265
|
-
`time_factor` and `time_constant` are arguments that can be specified
|
|
263
|
+
`time_factor` and `time_constant` are arguments that can be specified in the `handler.yml` file. They are a list with a maximum of three values, one for each type of compiler in the following order:
|
|
266
264
|
|
|
267
265
|
- Fast: Ada, C, C++, D, Fortran, Go, Haskell, Pascal
|
|
268
266
|
- Medium: FreeBASIC, C#, Java, Guile
|
|
269
|
-
- Slow: Brainfuck, Erlang, JavaScript, CLISP, Lua, PHP, Perl, Python, R, Ruby and Whitespace
|
|
267
|
+
- Slow: Brainfuck, Erlang, JavaScript, CLISP, Lua, PHP, Perl, Python, R, Ruby, and Whitespace
|
|
270
268
|
|
|
271
269
|
If one or two values are missing, they will be calculated using the following formulas: `medium = fast * 5`; `slow = medium * 2`. This applies for both `time_factor` and `time_constant` arguments.
|
|
272
270
|
|
|
273
|
-
If the arguments have not been specified, the default `time_factor` and `time_constant` values for all
|
|
271
|
+
If the arguments have not been specified, the default `time_factor` and `time_constant` values for all compilers will be `2` and `0.1` respectively.
|
|
274
272
|
|
|
275
|
-
This is an example of how the arguments would look
|
|
273
|
+
This is an example of how the arguments would look in `handler.yml`:
|
|
276
274
|
|
|
277
|
-
```
|
|
275
|
+
```yml
|
|
278
276
|
time_factor: [2, 10, 2]
|
|
279
277
|
time_constant: [0.1, 0.01, 0.05]
|
|
280
278
|
```
|
|
281
279
|
|
|
280
|
+
### Advanced: Checkers
|
|
281
|
+
|
|
282
|
+
With the `checker` option you can specify how the user's program output is compared with the problem solution. This is especially useful if the order of the output does not matter, for example. There are various `checker` options:
|
|
283
|
+
|
|
284
|
+
- `std`: The default option; it will just compare the files normally.
|
|
285
|
+
|
|
286
|
+
- `loosy`: Used for loosy outputs. It is like the standard checker but it will return AC (Accepted) in case a problem gets a PE (Presentation Error) verdict.
|
|
287
|
+
|
|
288
|
+
- `epsilon`: Used for problems where the output consists of numbers and can be slightly different from the problem solution. It will check if the user solution is similar to the problem solution. This checker has the following options:
|
|
289
|
+
- `relative`: If set to `1`, the comparison method will be relative. Otherwise, it will be absolute.
|
|
290
|
+
|
|
291
|
+
- `elastic`: Used to check for outputs whose order is independent. This happens, for instance, for backtracking problems where output order is left without specification. This checker has the following options:
|
|
292
|
+
- `separator`: String that separates one case from another one.
|
|
293
|
+
|
|
294
|
+
- `elastic2`: Used to check for outputs whose order is independent and the order of these outputs are also independent. This happens, for instance, for subset backtracking problems where output order is left without specification and the order of the subset is also unordered. This checker has the following options:
|
|
295
|
+
- `separator1`: String that separates one case from another one.
|
|
296
|
+
|
|
297
|
+
- `separator2`: String that separates one case inside the case from another one.
|
|
298
|
+
|
|
299
|
+
- `starting`: String that starts one case.
|
|
300
|
+
|
|
301
|
+
- `ending`: String that ends one case.
|
|
302
|
+
|
|
303
|
+
- `external`: Used to check for outputs using an external program that reads the input and the generated output and writes to `stdout` the verdict. This checker has the following options:
|
|
304
|
+
- `external_program`: Name of the external program used. If the program does not exist, an IE (Internal Error) verdict will be returned.
|
|
305
|
+
|
|
306
|
+
- `external_timeout`: Time that the external program has to do its work. The default time is 5 seconds. An IE (Internal Error) verdict will be returned if the program runs for more than the timeout.
|
|
307
|
+
|
|
282
308
|
## Test cases
|
|
283
309
|
|
|
284
|
-
Each test case `test` is described through
|
|
310
|
+
Test cases are used to evaluate the correctness of user submissions. Each test case `test` is described through a pair of files: `test.inp` and `test.cor`.
|
|
311
|
+
|
|
312
|
+
- `test.inp` contains the input of the test case.
|
|
313
|
+
|
|
314
|
+
- `test.cor` contains the correct output of the case.
|
|
285
315
|
|
|
286
|
-
|
|
316
|
+
In addition, `test` can also make use of a `test.ops` file to describe some low-level advanced options for its correction.
|
|
287
317
|
|
|
288
|
-
Test case names should be made of letters, digits, dashes and underscores. Do not use special characters in them. Test cases whose name starts with `sample`, `public`, `hint
|
|
318
|
+
Test case names should be made of letters, digits, dashes, and underscores. Do not use special characters or blanks in them. Test cases whose name starts with `sample`, `public`, `hint`, or `distilled` have a special meaning and are considered public (might be seen by users). It is common to name test cases with names such as `sample-1`, `sample-2`, or `test-hard`.
|
|
289
319
|
|
|
290
320
|
At correction time, public test cases are corrected before the private ones. The cases are processed sequentially, ordered by their name.
|
|
291
321
|
|
|
292
|
-
As correcting each single test case causes some overhead, it is not advisable to have many different test cases.
|
|
322
|
+
As correcting each single test case causes some overhead, it is not advisable to have many different test cases. Twenty different test cases may be a reasonable limit.
|
|
293
323
|
|
|
294
324
|
Input and output test cases should follow these rules:
|
|
295
325
|
|
|
296
|
-
- They only contain common characters: digits, uppercase and lowercase letters, punctuation
|
|
326
|
+
- They only contain common characters: digits, uppercase and lowercase letters, punctuation... (specifically those with ASCII codes between 32 and 126, plus the newline). So, no accents such as `À` or `ü`, no characters such as `ç`, `Δ`, `市`, or `😊`, and no tabs. Graphic output test cases are an exception that requires a PNG file.
|
|
297
327
|
|
|
298
328
|
- All lines should end with a newline character (`\n`), including the last line.
|
|
299
329
|
|
|
300
|
-
In addition,
|
|
301
|
-
|
|
302
|
-
- There must be no spaces before a line break. In particular, there must be no lines with only one or more spaces before the line break.
|
|
330
|
+
In addition, there must be no spaces before a line break. In particular, there must be no lines with only one or more spaces before the line break.
|
|
303
331
|
|
|
304
332
|
### Sample test cases
|
|
305
333
|
|
|
306
|
-
Sample test cases start with `sample` and will be
|
|
334
|
+
Sample test cases start with `sample` and will be revealed to users in the problem statement. As such, they should make clear the format of the input and the output for the problem and should be reasonably short.
|
|
307
335
|
|
|
308
|
-
|
|
336
|
+
### Public test cases
|
|
309
337
|
|
|
310
|
-
Public test cases start with `public` and will be
|
|
338
|
+
Public test cases start with `public` and will be revealed to users, but will not be shown in the problem statement. Usage of public test cases should be rare, but can be useful in situations where long input/output samples must be delivered.
|
|
311
339
|
|
|
312
|
-
|
|
340
|
+
### Hint test cases
|
|
313
341
|
|
|
314
|
-
Hint test cases start with `hint` and will be revealed to users if the submission
|
|
342
|
+
Hint test cases start with `hint` and will be revealed to users if the submission fails on them (unless some sample test case also fails).
|
|
315
343
|
|
|
316
|
-
|
|
344
|
+
### Distilled test cases
|
|
317
345
|
|
|
318
|
-
Distilled test cases start with `distilled` and will be shown to users whose submission fails on them (unless some sample or hint test case also fails). Distilled test cases are created by the system using the [Distiller Algorithm](http://upcommons.upc.edu/handle/2117/28174) and are added automatically to the problem directory
|
|
346
|
+
Distilled test cases start with `distilled` and will be shown to users whose submission fails on them (unless some sample or hint test case also fails). Distilled test cases are created by the system using the [Distiller Algorithm](http://upcommons.upc.edu/handle/2117/28174) and are added automatically to the problem directory; they are not meant to be created or modified by hand.
|
|
319
347
|
|
|
320
|
-
File `distiller.yml` is used to specify the parameters of the distillation process. `distillation.yml` is used to get some statistics
|
|
348
|
+
File `distiller.yml` is used to specify the parameters of the distillation process. `distillation.yml` is used to get some statistics from the distillation process.
|
|
321
349
|
|
|
322
|
-
Unfortunately, the distillation process requires some hand work and is not currently fully automated.
|
|
350
|
+
Unfortunately, the distillation process requires some hand work and is not currently fully automated, so will not be explained here.
|
|
323
351
|
|
|
324
352
|
### Test options
|
|
325
353
|
|
|
326
|
-
The `test.ops` file can be used to specify some limits for the correction of the corresponding test case. The options should be written as if they were arguments of a program, with a space between each other. The following options are available:
|
|
327
|
-
|
|
328
|
-
- `--verbose`: Sets the verbose output level. It has three options: `0` (quiet), `1` (normal) and `2` (all the information).
|
|
354
|
+
The `test.ops` file can be used to specify some advanced low-level limits for the correction of the corresponding test case. The options should be written as if they were arguments of a program, with a space between each other. The following options are available:
|
|
329
355
|
|
|
330
|
-
- `--maxtime`: Sets maximum execution time. It has three values: `cputime`, `limtime
|
|
356
|
+
- `--maxtime`: Sets maximum execution time. It has three values: `cputime`, `limtime`, and `clktime`. You can specify only the `cputime`, the `cputime` and the `limtime`, or all of them.
|
|
331
357
|
- `cputime` is the maximum time that the program has to use the CPU (processing instructions).
|
|
332
358
|
|
|
333
359
|
- `limtime` is the maximum CPU time limit. If not specified, `limtime` will be `cputime+1.5`.
|
|
334
360
|
|
|
335
361
|
- `clktime` is the maximum clock time (total time) the program has to run. If not specified, `clktime` will be three times `limtime`.
|
|
336
362
|
|
|
337
|
-
- `--maxmem`:
|
|
363
|
+
- `--maxmem`: Sets max memory in MB. It has two values: `maxmem` and `maxstack`. `maxmem` is the maximum amount of memory that the program is allowed to use. `maxstack` is the maximum amount of `maxmem` that can be used for the stack. If the `maxstack` is not specified, it will be the same as `maxmem`.
|
|
338
364
|
|
|
339
365
|
- `--maxfiles`: Sets the maximum number of files that can be open simultaneously.
|
|
340
366
|
|
|
@@ -344,62 +370,26 @@ The `test.ops` file can be used to specify some limits for the correction of the
|
|
|
344
370
|
|
|
345
371
|
- `--maxcore`: Sets the maximum file size in MB of the core file (generated if the program crashes).
|
|
346
372
|
|
|
347
|
-
- `--basename`: Sets the base name of the input test set.
|
|
348
|
-
|
|
349
|
-
- `--stdout`: Set path of the output (`.out`) file. If not specified, the output name will be `basename.out`.
|
|
350
|
-
|
|
351
|
-
- `--stdin`: Set path of the input (`.inp`) file. If not specified, the output name will be `basename.inp`.
|
|
352
|
-
|
|
353
|
-
- `--stderr`: Set path of the error (`.err`) file. If not specified, the output name will be `basename.err`.
|
|
354
|
-
|
|
355
|
-
- `--logfile`: Set path of the `.log` file. If not specified, the output name will be `basename.log`.
|
|
356
|
-
|
|
357
|
-
- `--resfile`: Set path of the `.res` file. If not specified, the output name will be `basename.res`.
|
|
358
|
-
|
|
359
373
|
## Solutions
|
|
360
374
|
|
|
361
|
-
Each problem must have
|
|
375
|
+
Each problem must have one golden solution and may have several alternative solutions in different programming languages. By default, the golden solution is C++, but can be changed in the `handler.yml` file with the `solution` field (e.g., `solution: Python3`).
|
|
362
376
|
|
|
363
377
|
Independently of the available solutions, users can submit their solutions in any supported programming language. The system will match the programming language of the submission and the programming languages available for the solution and select the most appropriate one.
|
|
364
378
|
|
|
365
379
|
Solution files are named `solution.ext`, where `ext` is the standard extension that corresponds to the selected programming language. For instance, a problem may contain `solution.cc` and `solution.py` in order to provide reference solutions in C++ and Python3.
|
|
366
380
|
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
## Checker
|
|
370
|
-
|
|
371
|
-
With the `checker` option you can specify how the user's program output is compared with the problem solution. This is especially useful if the order of the output does not matter, for example. There are various `checker` options:
|
|
372
|
-
|
|
373
|
-
- `std`: The default option, it will just compare the files normally.
|
|
374
|
-
|
|
375
|
-
- `loosy`: Used for loosy outputs. It is like the standard checker but it will return AC (Accepted) in case a problem gets a PE (Presentation Error) verdict.
|
|
376
|
-
|
|
377
|
-
- `epsilon`: Used for problems where the output are numbers and can be slightly different than the problem solution. It will check if the user solution is similar to the problem solution. This checker has the following options:
|
|
378
|
-
- `relative`: If set to `1`, the comparison method will be relative. Otherwise, it will be absolute.
|
|
379
|
-
|
|
380
|
-
- `elastic`: Used to check for outputs whose order is independent. This happens, for instance, for backtracking problems where output order is left without specification. This checker has the following options:
|
|
381
|
-
- `separator`: String that separates one case from another one.
|
|
381
|
+
Python solutions should have all their executable code inside an `if __name__ == "__main__":` block.
|
|
382
382
|
|
|
383
|
-
|
|
384
|
-
- `separator1`: String that separates one case from another one.
|
|
385
|
-
|
|
386
|
-
- `separator2`: String that separates one case inside the case from another one.
|
|
387
|
-
|
|
388
|
-
- `starting`: String that starts one case.
|
|
389
|
-
|
|
390
|
-
- `ending`: String that ends one case.
|
|
391
|
-
|
|
392
|
-
- `external`: used to check for outputs using an external program that reads the input and the generated output and writes to `stdout` the verdict. This checker has the following options:
|
|
393
|
-
- `external_program`: Name of the external program used. If the program does not exist, an IE (Internal Error) verdict will be returned.
|
|
394
|
-
|
|
395
|
-
- `external_timeout`: Time that the external program has to do its work. The default time is 5 seconds. An IE (Internal Error) verdict will be returned it the program runs for more than the timeout.
|
|
383
|
+
Java solutions must have their `main` function placed in a `Main` class. See https://jutge.org/documentation/compilers/JDK for some examples.
|
|
396
384
|
|
|
397
385
|
## Scores
|
|
398
386
|
|
|
399
|
-
In order to score submissions according to the correct test cases
|
|
387
|
+
In order to score submissions according to the correct test cases they pass, the file `scores.yml` must exist. `scores.yml` describes the scoring of a problem using YAML syntax. The scores are given through a list of partial scores. Each partial score contains the following fields:
|
|
400
388
|
|
|
401
389
|
- `part`: Identifier of the partial score.
|
|
390
|
+
|
|
402
391
|
- `prefix`: Prefix of the test cases that must be passed in this partial score.
|
|
392
|
+
|
|
403
393
|
- `points`: Number of points assigned to this partial score.
|
|
404
394
|
|
|
405
395
|
The total number of points is usually 100, but other (integer) values can be used. A submission that receives the totality of points is considered accepted.
|
|
@@ -436,20 +426,28 @@ Overlapping prefixes can be used to create more complex scoring schemes.
|
|
|
436
426
|
|
|
437
427
|
## Awards
|
|
438
428
|
|
|
439
|
-
|
|
429
|
+
Jutge.org offers awards to users in specific circumstances. Problem awards are images with a caption and a short description. In the case that a problem contains an image file `award.png` and (optionally) an HTML file `award.html`, users who get the problem accepted for the first time will receive that award.
|
|
440
430
|
|
|
441
|
-
The `award.png` image file should be a square image in PNG format with a transparent or white background (preferably) of size 200x200 pixels or more. Clip art and colorful images are preferred
|
|
431
|
+
The `award.png` image file should be a square image in PNG format with a transparent or white background (preferably) of size 200x200 pixels or more. Clip art and colorful images are preferred; no offensive images should be used.
|
|
442
432
|
|
|
443
433
|
The `award.html` file should contain a description of the award using simple HTML code. If `award.html` is missing but `award.png` exists, a default description will be provided by the system.
|
|
444
434
|
|
|
435
|
+
## The `tags.yml` file
|
|
436
|
+
|
|
437
|
+
This file is deprecated and currently not used by Jutge.org.
|
|
438
|
+
|
|
445
439
|
## Quick checklist
|
|
446
440
|
|
|
447
|
-
-
|
|
441
|
+
- Ensure that your problem folder has the `.pbm` extension.
|
|
442
|
+
|
|
443
|
+
- Make sure to remove the `problem.yml` file if you are creating a new problem.
|
|
444
|
+
|
|
445
|
+
- Make sure that all file and folder names only contain letters, digits, dots, dashes, and underscores. Do not use special characters, blanks, accents, or emojis in them.
|
|
448
446
|
|
|
449
447
|
- Make sure that all lines in input and output test cases end with a newline character (`\n`), including the last line.
|
|
450
448
|
|
|
451
449
|
- Make sure that there are no spaces before a line break in output test cases. In particular, there must be no lines with only one or more spaces before the line break.
|
|
452
450
|
|
|
453
|
-
- Make sure that all files are encoded in UTF-8.
|
|
451
|
+
- Make sure that all solutions, TeX, and YAML files are encoded in UTF-8.
|
|
454
452
|
|
|
455
|
-
- Make sure that all test
|
|
453
|
+
- Make sure that all test case files are encoded in 7-bit ASCII.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jutge.org/toolkit",
|
|
3
3
|
"description": "Toolkit to prepare problems for Jutge.org",
|
|
4
|
-
"version": "4.2.
|
|
4
|
+
"version": "4.2.6",
|
|
5
5
|
"homepage": "https://jutge.org",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Jutge.org",
|
|
@@ -28,13 +28,14 @@
|
|
|
28
28
|
"type": "module",
|
|
29
29
|
"bin": {
|
|
30
30
|
"jutge-toolkit": "dist/index.js",
|
|
31
|
-
"jtk": "dist/index.js"
|
|
31
|
+
"jtk": "dist/index.js",
|
|
32
|
+
"dev": "toolkit/index.ts"
|
|
32
33
|
},
|
|
33
34
|
"scripts": {
|
|
34
35
|
"lint": "eslint .",
|
|
35
36
|
"format": "bun prettier --write .",
|
|
36
37
|
"depcheck": "bunx depcheck",
|
|
37
|
-
"dev": "bun build --target bun --
|
|
38
|
+
"dev": "bun build --target bun --outfile dist/index.js ./toolkit --watch",
|
|
38
39
|
"build": "bun build --target bun --minify --outfile dist/index.js ./toolkit ",
|
|
39
40
|
"update-jutge-client": "(cd lib ; rm -f jutge_api_client.ts ; https --download https://api.jutge.org/clients/download/typescript)"
|
|
40
41
|
},
|
|
@@ -47,21 +48,21 @@
|
|
|
47
48
|
"dependencies": {
|
|
48
49
|
"@commander-js/extra-typings": "^14.0.0",
|
|
49
50
|
"@eslint/js": "^9.39.2",
|
|
50
|
-
"@inquirer/prompts": "^8.
|
|
51
|
+
"@inquirer/prompts": "^8.2.0",
|
|
51
52
|
"archiver": "^7.0.1",
|
|
52
53
|
"boxen": "^8.0.1",
|
|
53
54
|
"bun-types": "^1.3.5",
|
|
54
55
|
"chalk": "^5.6.2",
|
|
56
|
+
"cli-highlight": "^2.1.11",
|
|
55
57
|
"commander": "^14.0.2",
|
|
56
58
|
"env-paths": "^3.0.0",
|
|
57
59
|
"eslint": "^9.39.2",
|
|
58
60
|
"execa": "^9.6.1",
|
|
61
|
+
"extract-zip": "^2.0.1",
|
|
59
62
|
"gpt-tokenizer": "^3.4.0",
|
|
60
63
|
"handlebars": "^4.7.8",
|
|
61
64
|
"image-size": "^2.0.2",
|
|
62
65
|
"inquirer-checkbox-plus-plus": "^1.1.1",
|
|
63
|
-
"marked": "^17.0.1",
|
|
64
|
-
"marked-terminal": "^7.3.0",
|
|
65
66
|
"multi-llm-ts": "^4.6.2",
|
|
66
67
|
"nanoid": "^5.1.6",
|
|
67
68
|
"openai": "^6.15.0",
|
|
@@ -75,18 +76,16 @@
|
|
|
75
76
|
"terminal-image": "^4.1.0",
|
|
76
77
|
"terminal-link": "^5.0.0",
|
|
77
78
|
"tree-node-cli": "^1.6.0",
|
|
78
|
-
"typescript-eslint": "^8.51.0",
|
|
79
79
|
"yaml": "^2.8.2",
|
|
80
80
|
"zod": "^4.3.4",
|
|
81
81
|
"zod-package-json": "^2.1.0",
|
|
82
82
|
"zod-validation-error": "^5.0.0"
|
|
83
83
|
},
|
|
84
84
|
"devDependencies": {
|
|
85
|
+
"typescript-eslint": "^8.51.0",
|
|
85
86
|
"@types/archiver": "^7.0.0",
|
|
86
87
|
"@types/image-size": "^0.8.0",
|
|
87
|
-
"@types/
|
|
88
|
-
"@types/marked-terminal": "^6.1.1",
|
|
89
|
-
"@types/node": "^25.0.3",
|
|
88
|
+
"@types/node": "^25.0.7",
|
|
90
89
|
"@types/ora": "^3.2.0",
|
|
91
90
|
"@types/semver": "^7.7.1"
|
|
92
91
|
},
|
package/toolkit/doctor.ts
CHANGED
|
@@ -14,6 +14,7 @@ export const doctorCmd = new Command('doctor')
|
|
|
14
14
|
await tui.section('Checking Java installation', doc.checkJava)
|
|
15
15
|
await tui.section('Checking Rust installation', doc.checkRust)
|
|
16
16
|
await tui.section('Checking XeLaTeX installation', doc.checkXeLaTeX)
|
|
17
|
+
await tui.section('Checking PdfLaTeX installation', doc.checkPdfLaTeX)
|
|
17
18
|
await tui.section('Checking Pandoc installation', doc.checkPandoc)
|
|
18
19
|
await tui.section('Checking AI models', doc.checkAIEnvVars)
|
|
19
20
|
await tui.section('Checking terminal', doc.checkTerminal)
|