recodex-wiki/Tasks.md

# Tasks detailed

Basic information about tasks is on [Assignments overview](https://github.com/ReCodEx/GlobalWiki/wiki/Assignments-overview#task) page. This text is more detailed explaination of all implemented internal tasks and used judges.

## Internal tasks

**Archivate task** can be used for pack and compress a directory. Calling command is `archivate`. Requires two arguments:

- path and name of the directory to be archived
- path and name of the target archive. Only `.zip` format is supported.

**Extract task** is opposite to archivate task. It can extract different types of archives. Supported formats are the same as supports `libarchive` library (see [libarchive wiki](https://github.com/libarchive/libarchive/wiki)), mainly `zip`, `tar`, `tar.gz`, `tar.bz2` and `7zip`. Please note, that system administrator may not install all packages needed, so some formats may not work. Please, consult your system administrator for more information. Archives could contain only regular files or directories (ie. no symlinks, block and character devices sockets or pipes allowed). Calling command is `extract` and requires two arguments:

- path and name of the archive to extract
- directory, where the archive will be extracted

**Fetch task** will give you a file. It can be downloaded from remote file server or just copied from local cache if available. Calling comand is `fetch` with two arguments:

- name of the requested file without path
- path and name on the destination. Providing a different destination name can be used for easy rename.

**Copy task** can copy files and directories. Detailed info can be found on reference page of [boost::filesystem::copy](http://www.boost.org/doc/libs/1_60_0/libs/filesystem/doc/reference.html#copy). Calling command is `cp` and require two arguments:

- path and name of source target
- path and name of destination targer

**Make directory task** can create arbitrary number of directories. Calling command is `mkdir` and requires at least one argument. For each provided one will be called [boost::filesystem::create_directories](http://www.boost.org/doc/libs/1_60_0/libs/filesystem/doc/reference.html#create_directories) command.

**Rename task** will rename files and directories. Detailed bahavior can be found on reference page of [boost::filesystem::rename](http://www.boost.org/doc/libs/1_60_0/libs/filesystem/doc/reference.html#rename). Calling command is `rename` and require two arguments:

- path and name of source target
- path and name of destination target

**Remove task** is for deleting files and directories. Calling command is `rm` and require at least one argument. For each provided one will be called [boost::filesystem::remove_all](http://www.boost.org/doc/libs/1_60_0/libs/filesystem/doc/reference.html#remove_all) command.


## Judges

Judges are treated as normal external command, so there is no special task for them. They should be used for comparision of outputted files from execution tasks and sample outputs. Results of this comparision should be at least information if files are same or not. Extension for this is percentual results based on similarity of given files.

All packed judges are adopted from old Codex with only very small modifications. ReCodEx judges base directory is in `${JUDGES_DIR}` variable, which can be used in job config file.

### Judges interface

For future extensibility is **critical** that judges have some shared **interface** of calling and return values.
- Parameters: There are two mandatory positional parameters which has to be files for comparision
- Results:
  - _everything OK_
    - exitcode: 0
    - stdout: there is one line with double value which should be percentage of similarity of two given files
  - _error during execution_
    - exitcode: 1
    - stderr: there should be description of error

### ReCodEx judges

Below is list of judges which is packed with ReCodEx project and comply above requirements.

**recodex-judge-normal** is base judge used by most of exercises. This judge compares two text files. It compares only text tokens regardless amount of whitespace between them.
```
Usage: recodex-judge-normal [-r | -n | -rn] <file1> <file2>
```
- file1 and file2 are paths to files that will be compared
- switch options `-r` and `-n` can be specified as a 1st optional argument.
    - `-n` judge will treat newlines as ordinary whitespace (it will ignore line breaking)
    - `-r` judge will treat tokens as real numbers and compares them accordingly (with some amount of error)

**recodex-judge-filter** can be used for preprocess output files before real judging. This judge filters C-like comments from a text file. The comment starts with double slash sequence (`//`) and finishes with newline. If the comment takes whole line, then whole line is filtered.
```
Usage: recodex-judge-filter [inputFile [outputFile]]
```
- if `outputFile` is ommited, std. output is used instead.
- if both files are ommited, application uses std. input and output.

**recodex-judge-shuffle** is for judging shuffled files. This judge compares two text files and returns 0 if they matches (and 1 otherwise). Two files are compared with no regards for whitespace (whitespace acts just like token delimiter).
```
Usage: recodex-judge-shuffle [-[n][i][r]] <file1> <file2>
```
- `-n` ignore newlines (newline is considered only a whitespace)
- `-i` ignore items order on the row (tokens on each row may be permutated)
- `-r` ignore order of rows (rows may be permutated); this option has no effect when `-n` is used