Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foxcapades/lib-kt-cli-builder

Kotlin-based CLI call generator.
https://github.com/foxcapades/lib-kt-cli-builder

Last synced: 9 days ago
JSON representation

Kotlin-based CLI call generator.

Awesome Lists containing this project

README 

        
= CLI Call Builder

:version-actual: 0.8.5

:version-feature: 0.8.0

:source-highlighter: highlightjs



Provides delegates, annotations, and tools to generate CLI calls from

classes, making it easier to define type-safe, validating wrappers around

external CLI tools.



image:https://img.shields.io/github/license/foxcapades/lib-kt-cli-builder[GitHub License]

image:https://img.shields.io/badge/docs-dokka-%230e86d4[API Documentation, link="https://foxcapades.github.io/lib-kt-cli-builder/{version-feature}"]

image:https://img.shields.io/badge/kotlin-2.0.20-%237F52FF[Kotlin Version]

image:https://img.shields.io/badge/jvm-21-%23f90[Target JVM Version]

image:https://img.shields.io/maven-central/v/io.foxcapades.kt/cli-builder[Version, link="https://central.sonatype.com/artifact/io.foxcapades.kt/cli-builder/{actual-version}"]



== Usage



.build.gradle.kts

[source, kotlin, subs="attributes"]

----

  implementation("io.foxcapades.kt:cli-builder:{version-actual}")

----



=== Examples



==== Delegates



Flags and arguments may be defined on a type by use of the `Flag` or `Argument`

delegate types.



[source, kotlin]

----

@CliCommand("my-command")

class MyCommandConfig {

  // creates a required `-i` flag with

  val input by stringFlag('i') { required = true }



  // creates an optional `-o` flag with a default value of "-"

  val output by stringFlag('o') { default = "-" }



  // creates an optional `--threads/-t` flag with a default value of "1"

  val threads by intFlag("threads", 't') { default = 1 }

}

----



==== Annotations



Flags and arguments may be defined on a type by use of the `@CliFlag` or

`@CliArgument` annotations.



[source, kotlin]

----

@CliCommand("my-command")

data class MyCommandConfig(

  // creates a required `-i` flag

  @CliFlag(shortForm='i', required=true)

  val input: String,



  // creates an optional `-o` flag

  @CliFlag(shortForm='o')

  val output: String,



  // creates an optional `--threads/-t` flag

  @CliFlag("threads", 't')

  val threads: Int,

)

----



==== Headless



[source, kotlin]

----

class MyCommandConfig : Command {

  // Combine an annotation with a delegate

  @CliFlag("input", 'i')

  var input by pathFlag()



  override fun getCliCallComponents(config: CliSerializationConfig) =

    "my-command" to listOf(::input)

}



val foo = MyCommandConfig()

foo.input = Path("path/to/some/file")



require(Cli.toCliString(foo) == "my-command --input='path/to/some/file'")

----



=== Building A CLI Command



A CLI command is expected to be a value that is annotated with `@CliCommand`

and/or implements the `Command` interface.



A command may contain flags and/or arguments defined as delegated properties, as

annotated values, or as raw `Flag` or `Argument` instances directly used as

values from properties or getters.



For classes that implement the `Command` interface, the output of the

`getCliCallComponents` method will be used as the source for what components may

be considered for inclusion in a generated CLI call.



[source, kotlin]

----

class MyCommandConfig : Command {

  // Will not be considered when generated CLI calls as the getCliCallComponents

  // method does not include this property.

  var input by pathFlag()



  override fun getCliCallComponents(config: CliSerializationConfig) =

    "my-command" to emptyList()

}

----



For classes that instead use the `@CliCommand` annotation, the class will be

inspected to determine what components may be considered for inclusion in a

generated CLI call.



[source, kotlin]

----

@CliCommand("my-command")

class MyCommandConfig {

  // Will be considered when generating CLI calls due to the @CliFlag annotation

  @CliFlag("input", 'i')

  var input: Path?



  // Will be considered when generating CLI calls as it is a Flag delegate

  var output by pathFlag()



  // Will be considered when generating CLI calls as it is an Argument value

  val value: Argument



  // Will NOT be considered when generating CLI calls as it is a plain value

  val toggle: Boolean

}

----



==== Delegation vs Annotation vs Value



TODO



annotation can be combined with either delegate or value, but value and delegate

cannot be used together.



When an annotation is used in combination with either a delegate or a component

value, the settings from the annotation take priority over the settings from

the component itself.



TODO



when using the `@CliCommand` annotation on an implementation of `Command`, the

command name returned by the `getCliCallComponents` method is ignored.

Additionally, any positional args included in the annotation will precede the

components returned by the `getCliCallComponents` method.



==== Component Filtering



When and if individual components are included in a generated CLI call is based

on configurable predicates that are applied to components when they are to be

serialized.



The default configuration for whether a flag should be included in a CLI call

falls through to the flag's argument predicate.



The default configuration for whether an argument should be included simply

tests whether the argument has been explicitly set.