Lamp

Background

Click to expand

Building commands has always been a core concept in many applications, and, lots of times, a really boring and cumbersome one to pull off: Having to think of all the possible input from the user, all the mistakes they will make, validating input and then finally executing the actual command logic.

We aren't supposed to mess our hands up with so much of this. We really shouldn't get ourselves dirty with the highly error-prone string manipulation, nor are we supposed to repeat 3 lines of code a thousand times. We also should not be forced to think of all the edge cases and possible output of the user side. Developers should focus on what's important, not what isn't.

Then after all that, we really should make sure our code is clean, maintainable, extendable and flexible.

Building upon this belief, Lamp was born.

Lamp has taken responsibility upon itself to take all the crap of the command creation process: parsing input, validating arguments, auto completions, tokenizing and redirection, and leaves you only to the important part of your job here: the actual command logic.

Through annotations, parameter resolvers, command conditions, permissions, argument validators, cooldowns, dependency injection, auto-completers, Lamp not only makes the command creation process much easier, it also becomes more fun, intuitive and less error prone.

There are many commands frameworks out there, why should I use Lamp?

Glad you asked!

Lamp is small: The overall size of Lamp will not exceed 150 KB. Built to be lightweight, Lamp is convenient to package and ship.
Lamp is extendable: Lamp has been built thoroughly with this in mind. You can create custom annotations for commands, parameters, permissions and resolvers, with their very own functionality. This gives so much space for your own extendability, and also helps make sure the code you write is minimal.
Lamp is portable: Created with a high-level command API and an extendable codebase, Lamp has been produced to provide first-class support to as many platforms as possible. As of now, Lamp supports the following platforms:
With the help of the built-in APIs for dispatching commands and auto-completions, it is possible to support almost any platform out-of-the-box.
Lamp is easy: Despite all the powerful features and extendability, getting started with Lamp couldn't be easier. Simply create a command handler for your appropriate platform, then proceed with creating your command with the main @Command and @Subcommand annotations, and finally registering it with CommandHandler#register().
Lamp is powerful: Lamp allows you to leverage some of the command features which would be otherwise too burdensome to build:
- @Switch parameters
- @Flag (named) parameters
- Simple dependency injection
- Built-in localization API
- A quote-aware argument parser
- Context resolver factories and value resolver factories
- Simple and powerful auto completions API
- Built-in command cooldown handler

Getting Started

Now, for the good part.

First, you'll need to add the JitPack repository, and then you're going to select which part of Lamp you're going to use.

If you for some reason want to use the whole project as dependency, you can use "com.github.Revxrsal" as the groupId (or group on Gradle), and only the name "Lamp" as the artifactId (or name on Gradle). But if you chose to use only one module or two, you have to use "com.github.Revxrsal.Lamp" as the groupId and "[the module that you want]" as the artifactId. Bellow, there are examples about Maven and Gradle that will help you get started.

Maven

pom.xml

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- For the common module -->
    <dependency>
        <groupId>com.github.Revxrsal.Lamp</groupId>
        <artifactId>common</artifactId> 
        <version>[version]</version>
    </dependency>

    <!-- For the bukkit module -->
    <dependency>
        <groupId>com.github.Revxrsal.Lamp</groupId>
        <artifactId>bukkit</artifactId>
        <version>[version]</version>
    </dependency>  
</dependencies>

Gradle

build.gradle (Groovy)

repositories {
    maven { url = 'https://jitpack.io' }
}

dependencies {
    // For the common module
    implementation 'com.github.Revxrsal.Lamp:common:[version]'

    // For the bukkit module
    implementation 'com.github.Revxrsal.Lamp:bukkit:[verison]'
}

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

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

build.gradle.kts (Kotlin DSL)

repositories {
    maven(url = "https://jitpack.io")
}

dependencies {
    // For the common project
    implementation("com.github.Revxrsal.Lamp:common:[version]")

    // For the bukkit module
    implementation("com.github.Revxrsal.Lamp:bukkit:[verison]")
}

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

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

Documentation

Overview: Lamp/wiki
Examples: wiki/examples
Javadocs: https://revxrsal.github.io/Lamp/

SkytAsul / Lamp