pkl.Command0.31.0

Overview
Properties
Methods
Classes

open module pkl.Command

Defines inputs and outputs for CLI commands implemented in Pkl.

Module URI:: pkl:Command
Pkl version:: 0.31.0 or higher
Known subtypes in package:
Known usages in package:
All versions:

Modules extending pkl:Command may configure ModuleOutput.text, ModuleOutput.bytes, and/or ModuleOutput.files of output to influence the effect of the command.

Command modules should override options and provide their own class declaring options:

extends "pkl:Command"

options: Options

class Options {
  // ...
}

Properties(show inherited)

link

hidden

output: ModuleOutput (pkl.base)Source

The output of this module.

Defaults to all module properties rendered as either Pcf or the format specified on the command line.
link

hidden

command: CommandInfo

Command configuration.

link

hidden

options: Typed

Command line options.

This property is set by the runtime during command execution. It must not be amended or overridden by modules or classes extending Command.

Command modules should override this property and provide their own options type. The properties of the specified type declare the command line flags and arguments accepted by the command.

Example:

extends "pkl:Command"

options: Options

class Options {
  /// Maximum number of tries to attempt operation before giving up.
  `max-tries`: UInt = 3

  /// Duration after which operation will be timed out.
  @Flag { convert = module.convertDuration; metavar = "duration" }
  `connection-timeout`: Duration = 30.s

  /// Whether to use cache data locally.
  @BooleanFlag
  cache: Boolean = true

  /// Log verbosity.
  @CountedFlag { shortName = "v" }
  verbose: Int

  /// File paths to operate on.
  @Argument { completionCandidates = "paths" }
  path: Listing<String>
}

link

hidden

parent: Command?

The value of the parent command with parsed options.

This property is set by the runtime during command execution. It must not be amended or overridden by modules or classes extending Command.

The parent command is null for root commands.
link

hidden

root: Command?

The value of the root command with parsed options.

This property is set by the runtime during command execution.

The root command is null for root commands.
link

hidden

convertDuration: (String) -> Duration

A convert function for Duration values.

For use with Flag.convert and Argument.convert.
link

hidden

convertDataSize: (String) -> DataSize

A convert function for DataSize values.

For use with Flag.convert and Argument.convert.

Methods(show inherited)

link

function

getClass(): Class (pkl.base)Source

Returns the class of this.
link

function

toString(): String (pkl.base)Source

Returns a string representation of this.

This method is used to convert the values of string interpolation expressions to strings.
link

function

ifNonNull<Result>(transform: (NonNull) -> Result): Result? (pkl.base)Source

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.
link

function

hasProperty(name: String): Boolean (pkl.base)Source

Tells if this object has a property with the given name.
link

function

getProperty(name: String): unknown (pkl.base)Source

Returns the value of the property with the given name.

Throws if a property with this name does not exist.
link

function

getPropertyOrNull(name: String): unknown? (pkl.base)Source

Returns the value of the property with the given name.

Returns null if a property with this name does not exist.
link

function

toDynamic(): Dynamic (pkl.base)Source

Converts this object to a Dynamic object.
link

function

toMap(): Map<String, unknown> (pkl.base)Source

Converts this object to a Map.
link

function
relativePathTo(other: Module): List<String> (pkl.base)Source

Returns the relative, descendent directory path between this module and other.
Throws if no such path exists.

For example, if module mod1 has path /dir1/mod1.pkl, and module mod2 has path /dir1/dir2/dir3/mod2.pkl, then mod1.relativePathTo(mod2) will return List("dir2", "dir3").

A common use case is to compute the directory path between a template located at the root of a hierarchy (say rootModule.pkl) and the currently evaluated module (accessible via the module keyword):
```
import "rootModule.pkl" // self-import
path = rootModule.relativePathTo(module)
```

Classes

link

class

CommandInfo

Command configuration.
link

abstract class

BaseFlag extends Annotation

Annotates options properties to configure them as named CLI flags.
link

class

Flag extends BaseFlag

Annotates an options property to configure it as a named CLI flag that accepts a value.
link

class

BooleanFlag extends BaseFlag

Annotates Boolean options properties to configure them as named CLI flags that may be specified zero or one times.
link

class

CountedFlag extends BaseFlag

Annotates Integer options properties to configure them as named CLI flags that may be specified zero or more times.
link

class

Argument extends Annotation

Annotates an options property to configure it as a positional CLI argument.
link

class

Import

A value used in Flag.convert and Argument.convert to declare an option as a dynamic import.