cli: add missing documentation to all pub functionality (#8226)

pull/8237/head
Larpon 2021-01-20 22:15:48 +01:00 committed by GitHub
parent 55efd8309a
commit c212b4d180
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 45 additions and 2 deletions

View File

@ -2,10 +2,13 @@ module cli
type FnCommandCallback = fn (cmd Command) ? type FnCommandCallback = fn (cmd Command) ?
// str returns the `string` representation of the callback.
pub fn (f FnCommandCallback) str() string { pub fn (f FnCommandCallback) str() string {
return 'FnCommandCallback=>' + ptr_str(f) return 'FnCommandCallback=>' + ptr_str(f)
} }
// Command is a structured representation of a single command
// or chain of commands.
pub struct Command { pub struct Command {
pub mut: pub mut:
name string name string
@ -27,6 +30,7 @@ pub mut:
args []string args []string
} }
// str returns the `string` representation of the `Command`.
pub fn (cmd Command) str() string { pub fn (cmd Command) str() string {
mut res := []string{} mut res := []string{}
res << 'Command{' res << 'Command{'
@ -55,10 +59,12 @@ pub fn (cmd Command) str() string {
return res.join('\n') return res.join('\n')
} }
// is_root returns `true` if this `Command` has no parents.
pub fn (cmd Command) is_root() bool { pub fn (cmd Command) is_root() bool {
return isnil(cmd.parent) return isnil(cmd.parent)
} }
// root returns the root `Command` of the command chain.
pub fn (cmd Command) root() Command { pub fn (cmd Command) root() Command {
if cmd.is_root() { if cmd.is_root() {
return cmd return cmd
@ -66,6 +72,7 @@ pub fn (cmd Command) root() Command {
return cmd.parent.root() return cmd.parent.root()
} }
// full_name returns the full `string` representation of all commands int the chain.
pub fn (cmd Command) full_name() string { pub fn (cmd Command) full_name() string {
if cmd.is_root() { if cmd.is_root() {
return cmd.name return cmd.name
@ -73,12 +80,14 @@ pub fn (cmd Command) full_name() string {
return cmd.parent.full_name() + ' $cmd.name' return cmd.parent.full_name() + ' $cmd.name'
} }
// add_commands adds the `commands` array of `Command`s as sub-commands.
pub fn (mut cmd Command) add_commands(commands []Command) { pub fn (mut cmd Command) add_commands(commands []Command) {
for command in commands { for command in commands {
cmd.add_command(command) cmd.add_command(command)
} }
} }
// add_command adds `command` as a sub-command of this `Command`.
pub fn (mut cmd Command) add_command(command Command) { pub fn (mut cmd Command) add_command(command Command) {
mut subcmd := command mut subcmd := command
if cmd.commands.contains(subcmd.name) { if cmd.commands.contains(subcmd.name) {
@ -89,6 +98,8 @@ pub fn (mut cmd Command) add_command(command Command) {
cmd.commands << subcmd cmd.commands << subcmd
} }
// setup ensures that all sub-commands of this `Command`
// is linked as a chain.
pub fn (mut cmd Command) setup() { pub fn (mut cmd Command) setup() {
for mut subcmd in cmd.commands { for mut subcmd in cmd.commands {
subcmd.parent = cmd subcmd.parent = cmd
@ -96,12 +107,14 @@ pub fn (mut cmd Command) setup() {
} }
} }
// add_flags adds the array `flags` to this `Command`.
pub fn (mut cmd Command) add_flags(flags []Flag) { pub fn (mut cmd Command) add_flags(flags []Flag) {
for flag in flags { for flag in flags {
cmd.add_flag(flag) cmd.add_flag(flag)
} }
} }
// add_flag adds `flag` to this `Command`.
pub fn (mut cmd Command) add_flag(flag Flag) { pub fn (mut cmd Command) add_flag(flag Flag) {
if cmd.flags.contains(flag.name) { if cmd.flags.contains(flag.name) {
println('Flag with the name `$flag.name` already exists') println('Flag with the name `$flag.name` already exists')
@ -110,6 +123,7 @@ pub fn (mut cmd Command) add_flag(flag Flag) {
cmd.flags << flag cmd.flags << flag
} }
// parse parses `args` into this structured `Command`.
pub fn (mut cmd Command) parse(args []string) { pub fn (mut cmd Command) parse(args []string) {
if !cmd.disable_flags { if !cmd.disable_flags {
cmd.add_default_flags() cmd.add_default_flags()
@ -128,6 +142,8 @@ pub fn (mut cmd Command) parse(args []string) {
cmd.parse_commands() cmd.parse_commands()
} }
// add_default_flags adds the commonly used `-h`/`--help` and
// `-v`/`--version` flags to the `Command`.
fn (mut cmd Command) add_default_flags() { fn (mut cmd Command) add_default_flags() {
if !cmd.disable_help && !cmd.flags.contains('help') { if !cmd.disable_help && !cmd.flags.contains('help') {
use_help_abbrev := !cmd.flags.contains('h') && cmd.flags.have_abbrev() use_help_abbrev := !cmd.flags.contains('h') && cmd.flags.have_abbrev()
@ -139,6 +155,8 @@ fn (mut cmd Command) add_default_flags() {
} }
} }
// add_default_commands adds the command functions of the
// commonly used `help` and `version` flags to the `Command`.
fn (mut cmd Command) add_default_commands() { fn (mut cmd Command) add_default_commands() {
if !cmd.disable_help && !cmd.commands.contains('help') && cmd.is_root() { if !cmd.disable_help && !cmd.commands.contains('help') && cmd.is_root() {
cmd.add_command(help_cmd()) cmd.add_command(help_cmd())
@ -257,6 +275,8 @@ fn (cmd Command) check_required_flags() {
} }
} }
// execute_help executes the callback registered
// for the `-h`/`--help` flag option.
pub fn (cmd Command) execute_help() { pub fn (cmd Command) execute_help() {
if cmd.commands.contains('help') { if cmd.commands.contains('help') {
help_cmd := cmd.commands.get('help') or { return } // ignore error and handle command normally help_cmd := cmd.commands.get('help') or { return } // ignore error and handle command normally

View File

@ -7,6 +7,9 @@ pub enum FlagType {
string string
} }
// Flag holds information for a command line flag.
// (flags are also commonly referred to as "options" or "switches")
// These are typically denoted in the shell by a short form `-f` and/or a long form `--flag`
pub struct Flag { pub struct Flag {
pub mut: pub mut:
flag FlagType flag FlagType
@ -20,10 +23,13 @@ mut:
found bool found bool
} }
// get_all_found returns an array of all `Flag`s found in the command parameters
pub fn (flags []Flag) get_all_found() []Flag { pub fn (flags []Flag) get_all_found() []Flag {
return flags.filter(it.found) return flags.filter(it.found)
} }
// get_bool returns `true` if the flag is set.
// get_bool returns an error if the `FlagType` is not boolean.
pub fn (flag Flag) get_bool() ?bool { pub fn (flag Flag) get_bool() ?bool {
if flag.flag != .bool { if flag.flag != .bool {
return error('$flag.name: Invalid flag type `$flag.flag`, expected `bool`') return error('$flag.name: Invalid flag type `$flag.flag`, expected `bool`')
@ -31,11 +37,15 @@ pub fn (flag Flag) get_bool() ?bool {
return flag.value == 'true' return flag.value == 'true'
} }
// get_bool returns `true` if the flag specified in `name` is set.
// get_bool returns an error if the `FlagType` is not boolean.
pub fn (flags []Flag) get_bool(name string) ?bool { pub fn (flags []Flag) get_bool(name string) ?bool {
flag := flags.get(name) ? flag := flags.get(name) ?
return flag.get_bool() return flag.get_bool()
} }
// get_int returns the `int` value argument of the flag.
// get_int returns an error if the `FlagType` is not integer.
pub fn (flag Flag) get_int() ?int { pub fn (flag Flag) get_int() ?int {
if flag.flag != .int { if flag.flag != .int {
return error('$flag.name: Invalid flag type `$flag.flag`, expected `int`') return error('$flag.name: Invalid flag type `$flag.flag`, expected `int`')
@ -43,11 +53,15 @@ pub fn (flag Flag) get_int() ?int {
return flag.value.int() return flag.value.int()
} }
// get_int returns the `int` value argument of the flag specified in `name`.
// get_int returns an error if the `FlagType` is not integer.
pub fn (flags []Flag) get_int(name string) ?int { pub fn (flags []Flag) get_int(name string) ?int {
flag := flags.get(name) ? flag := flags.get(name) ?
return flag.get_int() return flag.get_int()
} }
// get_float returns the `f64` value argument of the flag.
// get_float returns an error if the `FlagType` is not floating point.
pub fn (flag Flag) get_float() ?f64 { pub fn (flag Flag) get_float() ?f64 {
if flag.flag != .float { if flag.flag != .float {
return error('$flag.name: Invalid flag type `$flag.flag`, expected `float`') return error('$flag.name: Invalid flag type `$flag.flag`, expected `float`')
@ -55,11 +69,15 @@ pub fn (flag Flag) get_float() ?f64 {
return flag.value.f64() return flag.value.f64()
} }
// get_float returns the `f64` value argument of the flag specified in `name`.
// get_float returns an error if the `FlagType` is not floating point.
pub fn (flags []Flag) get_float(name string) ?f64 { pub fn (flags []Flag) get_float(name string) ?f64 {
flag := flags.get(name) ? flag := flags.get(name) ?
return flag.get_float() return flag.get_float()
} }
// get_string returns the `string` value argument of the flag.
// get_string returns an error if the `FlagType` is not string.
pub fn (flag Flag) get_string() ?string { pub fn (flag Flag) get_string() ?string {
if flag.flag != .string { if flag.flag != .string {
return error('$flag.name: Invalid flag type `$flag.flag`, expected `string`') return error('$flag.name: Invalid flag type `$flag.flag`, expected `string`')
@ -67,12 +85,15 @@ pub fn (flag Flag) get_string() ?string {
return flag.value return flag.value
} }
// get_string returns the `string` value argument of the flag specified in `name`.
// get_string returns an error if the `FlagType` is not string.
pub fn (flags []Flag) get_string(name string) ?string { pub fn (flags []Flag) get_string(name string) ?string {
flag := flags.get(name) ? flag := flags.get(name) ?
return flag.get_string() return flag.get_string()
} }
// parse flag value from arguments and return arguments with all consumed element removed // parse parses flag values from arguments and return
// an array of arguments with all consumed elements removed.
fn (mut flag Flag) parse(args []string, with_abbrev bool) ?[]string { fn (mut flag Flag) parse(args []string, with_abbrev bool) ?[]string {
if flag.matches(args, with_abbrev) { if flag.matches(args, with_abbrev) {
if flag.flag == .bool { if flag.flag == .bool {
@ -87,7 +108,7 @@ fn (mut flag Flag) parse(args []string, with_abbrev bool) ?[]string {
} }
} }
// check if first arg matches flag // matches returns `true` if first arg in `args` matches this flag.
fn (mut flag Flag) matches(args []string, with_abbrev bool) bool { fn (mut flag Flag) matches(args []string, with_abbrev bool) bool {
if with_abbrev { if with_abbrev {
return (flag.name != '' && args[0] == '--$flag.name') || return (flag.name != '' && args[0] == '--$flag.name') ||
@ -125,6 +146,8 @@ fn (mut flag Flag) parse_bool(args []string) ?[]string {
return args[1..] return args[1..]
} }
// get returns the `Flag` matching `name` or an error
// if it can't be found.
fn (flags []Flag) get(name string) ?Flag { fn (flags []Flag) get(name string) ?Flag {
for flag in flags { for flag in flags {
if flag.name == name { if flag.name == name {