SigCommand

Custom command module

명령어를 추상화 하는 모듈입니다. Foundation SimpleCommand의 대체를 목적으로 합니다.

Reason

• Fo의 SimpleCommand는 유닛 테스트를 방해합니다.

• SimpleCommand의 args는 명령어 실행 당시가 아닌 현재 값을 나타내므로 비동기 실행에 적합하지 않습니다.

• CommandAPI 등의 대안 라이브러리에는 사용 상의 부족한 점이 존재합니다.

Usage

1. SigCommand 를 extends 합니다.

2. 생성자에 super("명령어 이름") 을 작성합니다.

3. onCommand() 메서드에 필요한 로직을 작성합니다.

4. 컨트롤러 등에서 SigCommand#register(JavaPlugin) 로 명령어를 등록합니다. (혹은 SigCommandController#register(SigCommand) 사용 가능

Implementation

@Slf4j
public class TestSigCommand extends SigCommand {

  public TestSigCommand() {
    super("testcmd");

    setPermission("siglib.testcmd");
    addCommand(new TestSubCommandShow(),
      new TestSubCommandAdd(),
      new TestSubCommandDelete(),
      new TestSubCommandPerm(),
      new TestSubCommandRecursive());
  }

  @Override
  public void onCommand(@NotNull SigCommandInput input) {
    log.info("test main command");
  }

  @Override
  protected List<String> tabComplete(@NotNull SigCommandInput input) {
    return completeSubCommands();
  }

}

Register

SigCommandController.getInstance().register(new TestSigCommand());

new TestSigCommand().register(SimplePlugin.getInstance());

JavaPlugin과 함께 명령어를 등록하는 것을 권장합니다. 자세한 내용은 밑의 register 문단을 참고하세요.

Feature

Namespace

네임스페이스는 명령어 실행 시 중복을 방지하기 위해 namespace:command_name 의 포맷으로 명령어를 실행할 때 사용되는 값입니다.

또한 이 값은 명령어 펄미션의 기본 값과 쿨다운 id의 기본 값에 사용됩니다.

네임스페이스의 기본 값은 sigcommand 입니다.

명령어가 다른 SigCommand에 등록된 경우 최상위 SigCommand의 네임스페이스를 사용합니다.

Execute command

  @Override
  public void onCommand(@NotNull SigCommandInput input) {
    int amount = Optional.ofNullable(input.getNextArg())
        .filter(ParseUtil::isInteger)
        .map(Integer::parseInt)
        .orElse(0);
    
    TestSigCommandController.getInstance().addTestFlag(amount);
  }

• 입력 값은 SigCommandInput를 통해 받아서 실행할 수 있습니다. 자세한 사항은 해당 목록을 참고해주세요.

Aliases

public TestSigCommand() {
    super("testcmd");

    setAliases("tcmd", "test");
  }

• addAlias(String): 이 명령어에 사용될 별칭을 추가합니다.

• setAliases(String...): 이 명령어에 사용될 별칭을 설정합니다. 이는 다른 명령어에 등록된 상태여도 작동합니다.

• setMatcher(Predicate): Predicate를 통한 별칭 기능을 제공합니다.

setMatcher(Predicate) 기능은 최상위 명령어인 경우 작동하지 않습니다. 또한, 여러 개의 matcher가 일치할 수 있는 경우 상위 명령어에 등록된 순서대로 작동합니다.

Description

  @Override
  public String getDesc() {
    return "%s command: %s".formatted(getName(), getUsage());
  }

  @Override
  public String getUsage() {
    return "/%s".formatted(SigCommandUtil.getNamesWithSpace(this));
  }

버킷에 전달되는 description과 usage는 해당 메서드를 재정의 함으로서 구현 가능합니다.

Sub command

  public TestSigCommand() {
    super("testcmd", "siglibtest");

    setPermission("siglib.testcmd");
    addSubCommand(
                new TestSubCommandShow(),
                new TestSubCommandAdd(),
                new TestSubCommandDelete();
    addSubCommand("direct", input -> send(input, "direct sub command"));
  }

• addSubCommand(SigCommand): 하위 명령어를 추가합니다.

• addSubCommand(String, Consumer<SigCommandInput>): 빠르게 하위 명령어를 추가합니다.

이미 다른 명령어에 하위 명령어로 등록된 명령어나, 명령어 자기 자신, getName()이 겹치는 명령어는 하위 명령어로 등록될 수 없습니다.

Tab complete

  @Override
  protected List<String> tabComplete(@NotNull SigCommandInput input) {
    return completeWords(input, "<number>");
  }
  
  @Override
  protected List<String> onUnknownTabComplete(@NotNull SigCommandInput input) {
    return completeEmpty();
  }

• completeWords(input, String...): 입력된 단어들을 반환합니다.

• completeSubCommands(input): 밑에 등록된 명령어의 getName() 들을 반환합니다.

• completeSubCommands(input, CommandSender): 위와 동일하나 펄미션이 있는 명령어 만을 반환합니다.

• completePlayerNames(input): 현재 온라인인 플레이어의 이름들을 반환합니다.

• completeEmpty() 또는 NO_COMPLETE: Tab complete를 수행하지 않습니다.

completeWords 메서드를 사용해야 자동 완성 탐색 등의 기능이 작동합니다. List를 반환할 경우 SigCommandInput이 필요한 자동 완성 기능들을 사용할 수 없습니다.

• args.length에 따라 탭 자동 완성을 하는 명령어의 경우 아래와 같이 구현할 수 있습니다.

  @Override
  protected List<String> tabComplete(@NotNull SigCommandInput input) {
    return switch (input.getTabLength()) { // getTabLength() 임에 주의
      case 1 -> completeWords(input, controller.getStatisticItems()
           .stream()
           .toList());
      case 2 -> completeWords(input, controller.getDurations()
           .stream()
           .map(TimeUtil::durationString)
           .toList());
      default -> completeEmpty();
    };
  }

Register

SigCommandController#register를 이용하는 방법과 SigCommand 메서드를 이용하는 방식이 있습니다. SigCommand 등록 메서드는 아래와 같습니다.

• register(): namespace를 sigcommand 로 하여 명령어를 등록합니다.

• register(String): 입력된 값에 따라 namespace를 설정하여 명령어를 등록합니다.

• register(JavaPlugin): 플러그인의 getName().toLowerCase()를 namespace로 명령어를 등록합니다. 또한 JavaPlugin을 command에 등록합니다.

name 과 namespace 가 동일한 명령어가 이미 등록되어 있는 경우 등록에 실패할 수 있습니다.

JavaPlugin 없이 SigCommand를 등록한 경우 플러그인 비활성화/리로드 시 명령어 실행 방지 기능이 작동하지 않을 수 있습니다.

Miscellaneous

• checkPlayer(SigCommandInput): 실행자가 플레이어인 경우 경고를 표시합니다.

• checkConsole(SigCommandInput): 실행자가 콘솔인 경우 경고를 표시합니다.

SigCommandConstraint

명령어의 실행 제약 조건을 다룹니다.

Permission

  public TestSigCommand() {
    super("testcmd");

    setPermission("siglib.testcmd");
  }
  
  @Override
  protected void onNoPermission(@NotNull SigCommandInput input) {
    // do on no permission
  }

명령어에 대한 펄미션을 설정합니다.

• 펄미션이 설정되지 않았을 경우 기본 펄미션은 (namespace).command.(command_names) 입니다. 예) siglib.command.testcmd, siglib.command.testcmd.add

• removePermission(): 펄미션을 삭제합니다. 아무 유저나 실행할 수 있게 됩니다.

• setPermissionMessage(String): 펄미션이 없을 시 표시될 메시지를 지정합니다. onNoPermission()에 의해 덮어 쓰여질 수 있습니다.

register()를 호출하기 전의 코드 상 기본 펄미션 값은 sigcommand.default 입니다.

상위 명령어에 대한 펄미션이 없더라도 해당 명령어 자체의 펄미션만 있으면 실행이 가능합니다.

Cooldown

  public TestSubCommandCooldown() {
    super("cooldown");
    
    setCooldown(Duration.ofSeconds(5));
  }
  
  @Override
  protected boolean onCooldown(@NotNull SigCommandInput input) {
    // do on command cooldown
  }

명령어에 대한 쿨다운을 설정합니다. 기본적으로는 쿨다운은 존재하지 않습니다.

• 쿨다운 id가 설정되지 않았을 경우 기본 id는 (namespace)_(command_names) 입니다. 예) siglib_testcmd, siglib_testcmd_add

• setCooldownId(String): 적용될 쿨다운 ID를 설정합니다.

• setCooldown(Duration): 이 명령어를 실행할 때 적용될 쿨다운의 시간을 설정합니다.

• addCooldown(): 설정된 Duration에 따른 쿨다운을 즉시 적용합니다.

• addCooldown(Duration): 해당 Duration 만큼의 쿨다운을 즉시 적용합니다.

• setCooldownMessage(String): 쿨다운 중 일시 표시될 메시지를 지정합니다. onCooldown()에 의해 덮어 쓰여질 수 있습니다.

register()를 호출하기 전 코드 상 기본 쿨다운 id 값은 sigcommand_default 입니다.

상위 명령어에 대한 쿨다운이 돌아가고 있더라도 해당 명령어의 쿨다운은 별개로 다루어집니다.

SigCommandInput

실행 중인 명령어의 입력 정보를 포함하는 데이터 입니다.

• getSender(): 명령어를 보낸 CommandSender 를 반환합니다. 콘솔일 수도 있습니다.

• getNamespace(): 입력 시 사용된 네임스페이스를 반환합니다. null 일 수 있습니다.

• getLabel(): 입력 시 사용된 명령어의 이름을 나타냅니다. Aliases로 입력했을 경우 이를 나타냅니다.

• getDepth(): 현재 명령어의 실행 깊이를 나타냅니다. 예를 들어 최상위 명령어인 경우 값은 0 입니다.

• getArgs(): 입력 시 사용된 명령어의 전체 인자들을 나타냅니다. getArgs().get(0)은 Label을 제외하고 첫 번째로 입력된 값을 나타냅니다.

• getArg(Integer): 입력된 순서의 인자를 나타냅니다. args[index]와 같습니다. 존재하지 않을 경우 null을 반환 합니다.

• getLength(): 인자의 갯수를 나타냅니다. args.length 와 같습니다.

• getTabLength(): 탭 자동 완성에 사용되는 인자의 갯수를 나타냅니다. isLastBlank() == true인 경우 1을 더합니다.

• getNowArg(): 현재 명령어를 실행하는 순서의 인자를 나타냅니다. Label은 제외됩니다. 이 값은 하위 명령어인 경우 SigCommand#getName()과 같습니다.

• getNextArg(): 다음 위치에 있는 인자를 나타냅니다. 없을 경우 null을 반환합니다.

• getNextArg(Integer): 값만큼 다음 위치에 있는 인자를 나타냅니다. 없을 경우 null을 반환합니다.

• getPrevArg(): 이전 위치에 있는 인자를 나타냅니다. 없을 경우 null을 반환합니다.

• getPrevArg(Integer): 값만큼 이전 위치에 있는 인자를 나타냅니다. 없을 경우 null을 반환합니다.

• getInput(): 입력된 명령 줄을 /를 제외하고 재구성해 반환합니다.

• getSlashInput(): 입력된 명령 줄을 /를 포함하여 재구성해 반환합니다.

• isLastBlank(): 마지막 입력 문자가 공백인지 확인합니다.

getNowArg()는 최상위 명령어인 경우 null을 반환합니다. (Label은 Argument에 포함되지 않습니다.)

기존 명령어 시스템과 달리, 유효한 글자가 입력 되어야 하나의 Argument로 취급합니다. 즉, ""와 같은 빈 문자열은 제외 됩니다.

SigCommandBuilder

SigCommand 를 만들 수 있는 빌더 입니다.

SigCommandBuilder.builder()
  .name("testcmd")
  .aliases("tcmd", "testcommand")
  .onCommand(input -> MessageUtil.send(input, "test command executed"))
  .subCommand("sub", input -> MessageUtil.send(input, "sub command executed"))
  .register();

SigCommandException

오류 발생 시 반환 되는 Exception 입니다. 오류 메시지와 입력 시 사용된 SigCommandInput을 포함하고 있습니다.

Caution

• SigCommand#init을 외부에서 호출하지 마세요. 호출할 필요가 없으며 버그를 유발할 수 있습니다.