3. Параметры командной строки

← Основы языка · Оглавление · Далее: управляющие конструкции и функции →

Блок params описывает параметры сценария. Он должен находиться в начале скрипта; перед ним допускается только документирующий комментарий ##.

Простой пример

## Скачивает архив.
params {
    ## URL архива.
    $url String

    ## Имя выходного файла.
    $output String = "archive.tar"

    ## Количество повторов.
    $retries Integer = 3
}

println "url=" + $url
println "output=" + $output
println "retries=" + $retries

Запуск:

java -jar jobs.jar download.jobs --url https://example.test/file.tar --retries=5

Параметры передаются как --name value или --name=value.

Обязательные и необязательные параметры

Если у параметра нет значения по умолчанию, он обязателен:

params {
    $input Path
    $verbose Boolean = false
}

Если обязательный параметр не передан, неизвестен или не приводится к нужному типу, интерпретатор печатает help и завершает выполнение с кодом 255.

Поддерживаемые типы

В params обычно используются встроенные типы:

params {
    $name String
    $file Path
    $count Integer = 1
    $ratio Decimal = 0.5
    $enabled Boolean = true
}

Пользовательские конвертеры

Вместо имени типа можно указать функцию-конвертер. Она принимает строку из командной строки и возвращает готовое значение.

params {
    $name Normalize-Name
}

Normalize-Name($value) {
    return "[" + $value.Trim().To-Upper() + "]"
}

println $name

Функции-конвертеры можно объявлять ниже блока params: top-level use и объявления функций подготавливаются до обработки параметров.

Ошибки валидации параметров

Для пользовательских ошибок используйте ParamsException. Внутри обработки параметров она приводит к выводу сообщения, help и коду 255.

params {
    $name Validate-Name
}

Validate-Name($value) {
    if $value.Trim().Is-Empty() {
        throw new ParamsException("Name cannot be empty.")
    }
    return $value.Trim()
}

Любое другое исключение из конвертера считается обычной runtime-ошибкой и выводится со stack trace.

Автоматический help

Документирующие комментарии ## перед params и перед отдельными параметрами попадают в help:

## Создаёт текстовый отчёт.
params {
    ## Исходный CSV-файл.
    $input Path

    ## Папка для результата.
    $out-dir Path = p"build"
}

Вызов help:

java -jar jobs.jar report.jobs --help
java -jar jobs.jar report.jobs -h

← Основы языка · Оглавление · Далее: управляющие конструкции и функции →