projen/lib/task.d.ts

CDK for software projects

import type { TaskCommonOptions, TaskSpec, TaskStep, TaskStepOptions } from "./task-model";
import type { TaskShell } from "./task-shell";
export interface TaskOptions extends TaskCommonOptions {
    /**
     * Shell command to execute as the first command of the task.
     *
     * A single shell string, so only pass trusted input: an interpolated value is
     * interpreted by the shell too. Use `execArgs` for arguments you did not write
     * literally.
     *
     * Mutually exclusive with `execArgs`.
     *
     * @default - add steps using `task.exec(command)` or `task.spawn(subtask)`
     */
    readonly exec?: string;
    /**
     * Shell command to execute as the first command of the task, provided as a
     * list of the program followed by its arguments (an "argv").
     *
     * A convenient alternative to `exec`: arguments with spaces or special
     * characters are passed through as-is, with no quoting needed. The elements
     * are not run through a shell, so environment variables (`$FOO`) are not
     * expanded and other shell features are unavailable.
     * @see TaskStep.execArgs
     *
     * Mutually exclusive with `exec`.
     *
     * @default - add steps using `task.execArgs(args)`, `task.exec(command)` or `task.spawn(subtask)`
     */
    readonly execArgs?: string[];
    /**
     * List of task steps to run.
     */
    readonly steps?: TaskStep[];
    /**
     * Should the provided `exec` shell command receive args passed to the task.
     * @see {@link TaskStepOptions.receiveArgs}
     *
     * @default false
     */
    readonly receiveArgs?: boolean;
    /**
     * Should the provided `exec` shell command receive fixed args.
     * @see {@link TaskStepOptions.args}
     *
     * @default - no arguments are passed to the step
     */
    readonly args?: string[];
}
/**
 * A task that can be performed on the project. Modeled as a series of shell
 * commands and subtasks.
 */
export declare class Task {
    /**
     * Task name.
     */
    readonly name: string;
    private readonly _conditions;
    private readonly _steps;
    private readonly _env;
    private _cwd?;
    private _shell?;
    private readonly requiredEnv?;
    private _locked;
    private _description?;
    constructor(name: string, props?: TaskOptions);
    /**
     * Forbid additional changes to this task.
     */
    lock(): void;
    /**
     * Returns the working directory for this task.
     */
    get cwd(): string | undefined;
    /**
     * Sets the working directory for this task.
     */
    set cwd(cwd: string | undefined);
    /**
     * The shell used to run this task's commands, or `undefined` when inheriting
     * the built-in default shell.
     * @see {@link TaskCommonOptions.shell}
     */
    get shell(): TaskShell | undefined;
    /**
     * Sets the shell used to run this task's commands.
     */
    set shell(shell: TaskShell | undefined);
    /**
     * Returns the description of this task.
     */
    get description(): string | undefined;
    /**
     * Sets the description of this task.
     */
    set description(desc: string | undefined);
    /**
     * A command to execute which determines if the task should be skipped. If it
     * returns a zero exit code, the task will not be executed.
     */
    get condition(): string | undefined;
    /**
     * Add a command to execute which determines if the task should be skipped.
     *
     * If a condition already exists, the new condition will be appended with ` && ` delimiter.
     * @param condition The command to execute.
     * @see {@link Task.condition}
     */
    addCondition(...condition: string[]): void;
    /**
     * Reset the task so it no longer has any commands.
     * @param command the first command to add to the task after it was cleared.
     */
    reset(command?: string, options?: TaskStepOptions): void;
    /**
     * Adds steps to this task. This is a generic method that accepts any
     * task step (exec, spawn, say, builtin).
     *
     * @param steps The steps to add.
     */
    addSteps(...steps: TaskStep[]): void;
    /**
     * Executes a shell command
     * @param command Shell command
     * @param options Options
     */
    exec(command: string, options?: TaskStepOptions): void;
    /**
     * Executes a command provided as a list of the program followed by its
     * arguments (an "argv").
     *
     * A convenient alternative to `Task.exec`: arguments with spaces or
     * special characters are passed through as-is, with no quoting needed. The
     * elements are not run through a shell, so environment variables (`$FOO`) are
     * not expanded and other shell features are unavailable.
     *
     * @example task.execArgs(["echo", "hello world"]);
     *
     * @param command The program followed by its arguments.
     * @param options Options
     */
    execArgs(command: string[], options?: TaskStepOptions): void;
    /**
     * Execute a builtin task.
     *
     * Builtin tasks are programs bundled as part of projen itself and used as
     * helpers for various components.
     *
     * In the future we should support built-in tasks from external modules.
     *
     * @param name The name of the builtin task to execute (e.g.
     * `release/resolve-version`).
     */
    builtin(name: string): void;
    /**
     * Say something.
     * @param message Your message
     * @param options Options
     */
    say(message: string, options?: TaskStepOptions): void;
    /**
     * Spawns a sub-task.
     * @param subtask The subtask to execute.
     */
    spawn(subtask: Task, options?: TaskStepOptions): void;
    /**
     * Adds steps at the beginning of this task.
     *
     * @param steps The steps to add.
     */
    prependSteps(...steps: TaskStep[]): void;
    /**
     * Adds a command at the beginning of the task.
     * @param command The command to add.
     */
    prependExec(command: string, options?: TaskStepOptions): void;
    /**
     * Adds a spawn instruction at the beginning of the task.
     * @param subtask The subtask to execute.
     */
    prependSpawn(subtask: Task, options?: TaskStepOptions): void;
    /**
     * Says something at the beginning of the task.
     * @param message Your message
     */
    prependSay(message: string, options?: TaskStepOptions): void;
    /**
     * Renders step options (with a {@link TaskShell}) to the manifest
     * {@link TaskStep} form, where `shell` is its `string | string[]` rendering.
     */
    private renderStep;
    private _pushSteps;
    private _unshiftSteps;
    /**
     * Adds an environment variable to this task.
     * @param name The name of the variable
     * @param value The value. If the value is surrounded by `$()`, we will
     * evaluate it within a subshell and use the result as the value of the
     * environment variable.
     */
    env(name: string, value: string): void;
    /**
     * Returns all environment variables in the task level
     */
    get envVars(): Readonly<{
        [name: string]: string;
    }>;
    /**
     * Returns an immutable copy of all the step specifications of the task.
     */
    get steps(): TaskStep[];
    /**
     * Insert one or more steps at a given index
     *
     * @param index Steps will be inserted before this index. May be negative to
     * count backwards from the end, or may be `== steps().length` to insert at the end.
     * @param steps The steps to insert
     */
    insertStep(index: number, ...steps: TaskStep[]): void;
    /**
     *
     * @param index The index of the step to edit
     * @param step The new step to replace the old one entirely, it is not merged with the old step
     */
    updateStep(index: number, step: TaskStep): void;
    /**
     *
     * @param index The index of the step to remove
     */
    removeStep(index: number): void;
    /**
     * Renders a task spec into the manifest.
     *
     * @internal
     */
    _renderSpec(): TaskSpec;
    private assertUnlocked;
    private warnForLazyValue;
    /**
     * Ensure that environment variables are persisted as strings
     * to prevent type errors when parsing from tasks.json in future
     */
    private getEnvString;
}