字段选项

字段选项会把命令属性变成 CLI 选项。func 会解析当前命令作用域，将选项值赋给命令实例，然后运行选中的处理器。

标志

@Flag 创建布尔选项。用户没有传入该标志时，会使用属性默认值。

import { CommandMajor, Flag, Handler } from 'func'

@CommandMajor()
export class Major {
  @Flag({ alias: 'v', description: 'Print more logs' })
  verbose = false

  @Handler()
  run() {
    console.log(this.verbose)
  }
}

my-cli --verbose 和 my-cli -v 都会把 this.verbose 设置为 true。

值

@Value 创建标量值选项。它可以从 TypeScript metadata 推断 String、Number 和 Boolean。推断不足时可以使用 type。

import { Command, Handler, Value } from 'func'

@Command({ name: 'serve' })
export class ServeCommand {
  @Value()
  host: string = 'localhost'

  @Value()
  port: number = 3000

  @Value({ name: 'dry-run', type: Boolean })
  dryRun = false

  @Handler()
  run() {
    console.log(this.host, this.port, this.dryRun)
  }
}

对于 my-cli serve --host 0.0.0.0 --port 4000，实例会收到 host = '0.0.0.0' 和 port = 4000。

重复值

@ArrayValue 创建重复字符串选项。适用于用户可以多次传入同一选项的场景。

import { ArrayValue, Command, Handler } from 'func'

@Command({ name: 'build' })
export class BuildCommand {
  @ArrayValue({ name: 'include', alias: 'i' })
  includes: string[] = []

  @Handler()
  run() {
    console.log(this.includes)
  }
}

my-cli build -i src -i tests 会把 ['src', 'tests'] 赋给 this.includes。

校验

字段校验器会在选项值赋值后运行。校验错误属于 runtime-print 错误，因此可以由局部或全局错误处理器格式化。

import {
  Command,
  DependsOn,
  Enum,
  Exclusive,
  Flag,
  Handler,
  Required,
  Value,
  ValueValidate,
} from 'func'

@Command({ name: 'publish' })
export class PublishCommand {
  @Required()
  @Enum(['dev', 'prod'])
  @Value()
  target?: string

  @DependsOn(['token'])
  @Value()
  registry?: string

  @Value()
  token?: string

  @Exclusive(['json'])
  @Flag()
  table = false

  @Flag()
  json = false

  @Value()
  @ValueValidate(value => Number(value) > 0 || 'retry must be positive')
  retry: number = 1

  @Handler()
  run() {}
}

@Required 要求值已定义。
@Enum 将值限制在允许列表中。
@DependsOn 要求显式传入此选项时，同时传入相关选项。
@Exclusive 拒绝互相冲突的显式选项组合。
@ValueValidate 运行自定义校验逻辑。

子选项

@SubOptions 为命令作用域声明仅用于解析的选项。对于大多数类型化命令值，优先使用字段选项。只有当你确实想从 @Args() 读取归一化选项数据时，才使用子选项。