Command line

This page describes how to integrate Lamp with the command line, as well as what to expect out of it.

Setting up

Prerequisites

• Java 17 or newer

Adding Lamp dependency

To add Lamp to your project, add the following (depending on your project structure):

pom.xml

<dependencies>
  <!-- Required for all platforms -->
  <dependency>
      <groupId>io.github.revxrsal</groupId>
      <artifactId>lamp.common</artifactId> 
      <version>[VERSION]</version>
  </dependency>

  <!-- CLI module -->
  <dependency>
      <groupId>io.github.revxrsal</groupId>
      <artifactId>lamp.cli</artifactId>
      <version>[VERSION]</version>
  </dependency>  
</dependencies>

build.gradle

dependencies {
   // Required for all platforms
   implementation 'io.github.revxrsal:lamp.common:[VERSION]'
   
   // CLI module
   implementation 'io.github.revxrsal:lamp.cli:[VERSION]'
}

build.gradle.kts

dependencies {
    // Required for all platforms
    implementation("io.github.revxrsal:lamp.common:[VERSION]")
    
    // CLI module
    implementation("io.github.revxrsal:lamp.cli:[VERSION]")
}

Latest version:

Optional: Preserve parameter names

Lamp identifies parameters by their names and uses them to generate relevant command metadata. By default, Java does not preserve parameter names reflectively. You need to add the following to your project:

pom.xml

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.8.0</version>
    <configuration>
      <compilerArgs>
        <!-- Preserves parameter names -->
        <arg>-parameters</arg>
      </compilerArgs>
    </configuration>
  </plugin>
</plugins>

build.gradle

compileJava { 
    // Preserve parameter names in the bytecode
    options.compilerArgs += ["-parameters"]
}

// optional: if you're using Kotlin
compileKotlin {
    kotlinOptions.javaParameters = true
}

build.gradle.kts

tasks.withType<JavaCompile> {
    // Preserve parameter names in the bytecode
    options.compilerArgs.add("-parameters")
}

// optional: if you're using Kotlin
tasks.withType<KotlinJvmCompile> {
    compilerOptions {
        javaParameters = true
    }
}

Supported CLI types

• java.util.Scanner in place of CommandActor

• java.io.PrintStream in place of CommandActor

Example

Execute and exit

Java

public final class CLIApp {

    public static void main(String[] args) {
        var lamp = CLILamp.builder()
                .build();
        lamp.register(new PingCommand());
        /* register all other commands here */

        ConsoleActor actor = ActorFactory.defaultFactory().createForStdIo(lamp);
        lamp.dispatch(actor, String.join(" ", args));
    }

    static class PingCommand {

        @Command("ping")
        public void ping(ConsoleActor actor) {
            actor.reply("Pong!");
        }
    }
}

Kotlin

fun main(args: Array<String>) {
    val lamp = CLILamp.builder().build()
    lamp.register(PingCommand())
    /* register all other commands here */

    val actor = ActorFactory.defaultFactory().createForStdIo(lamp)
    lamp.dispatch(actor, args.joinToString(" "))
}

class PingCommand {

    @Command("ping")
    fun ping(actor: ConsoleActor) {
        actor.reply("Pong!")
    }
}

Poll console indefinitely

Java

public final class CLIApp {

    public static void main(String[] args) {
        var lamp = CLILamp.builder()
                .build();
        lamp.register(new PingCommand());
        /* register all other commands here */

        // Call this to continuously read input from the console
        //
        // pollStdin() is CLIVisitors.pollStdin().
        // we use static imports here for brevity.
        lamp.accept(pollStdin());
    }

    static class PingCommand {

        @Command("ping")
        public void ping(ConsoleActor actor) {
            actor.reply("Pong!");
        }
    }
}

Kotlin

fun main(args: Array<String>) {
    val lamp = CLILamp.builder().build()
    lamp.register(PingCommand())
    /* register all other commands here */

    // Call this to continuously read input from the console
    //
    // pollStdin() is CLIVisitors.pollStdin().
    // we use static imports here for brevity.
    lamp.accept(pollStdin())
}

class PingCommand {

    @Command("ping")
    fun ping(actor: ConsoleActor) {
        actor.reply("Pong!")
    }
}