NAME
Getopt::Kingpin - command line options parser (like golang kingpin)
SYNOPSIS
use
Getopt::Kingpin;
my
$kingpin
= Getopt::Kingpin->new;
$kingpin
->flags->get(
"help"
)->short(
'h'
);
my
$verbose
=
$kingpin
->flag(
'verbose'
,
'Verbose mode.'
)->short(
'v'
)->bool;
my
$name
=
$kingpin
->arg(
'name'
,
'Name of user.'
)->required->string;
$kingpin
->parse;
# perl sample.pl hello
printf
"name : %s\n"
,
$name
;
Automatically generate --help option.
usage: script.pl [<flags>] <name>
Flags:
-h, --help Show context-sensitive help.
-v, --verbose Verbose mode.
Args:
<name> Name of user.
Support sub-command.
use
Getopt::Kingpin;
my
$kingpin
= Getopt::Kingpin->new;
my
$register
=
$kingpin
->command(
'register'
,
'Register a new user.'
);
my
$register_nick
=
$register
->arg(
'nick'
,
'Nickname for user.'
)->required->string;
my
$register_name
=
$register
->arg(
'name'
,
'Name for user.'
)->required->string;
my
$post
=
$kingpin
->command(
'post'
,
'Post a message to a channel.'
);
my
$post_image
=
$post
->flag(
'image'
,
'Image to post.'
)->file;
my
$post_channel
=
$post
->arg(
'channel'
,
'Channel to post to.'
)->required->string;
my
$post_text
=
$post
->arg(
'text'
,
'Text to post.'
)->string_list;
my
$cmd
=
$kingpin
->parse;
if
(
$cmd
eq
'register'
) {
printf
"register %s %s\n"
,
$register_nick
,
$register_name
;
}
elsif
(
$cmd
eq
'post'
) {
printf
"post %s %s %s\n"
,
$post_image
,
$post_channel
, @{
$post_text
->value};
}
else
{
$kingpin
->help;
}
Help is below.
usage: script.pl [<flags>] <command> [<args> ...]
Flags:
--help Show context-sensitive help.
Commands:
help [<command>...]
Show help.
register [<nick>] [<name>]
Register a new user.
post [<flags>] [<channel>] [<text>]
Post a message to a channel.
DESCRIPTION
Getopt::Kingpin is a command line parser. It supports flags and positional arguments.
Simple to use
Automatically generate help flag (--help).
This module is inspired by Kingpin written in golang. https://github.com/alecthomas/kingpin
METHOD
new()
Create a parser object. Default script-name is basename($0).
my
$kingpin
= Getopt::Kingpin->new;
my
$kingpin
= Getopt::Kingpin->new(
"script-name.pl"
,
"description of script"
);
my
$kingpin
= Getopt::Kingpin->new(
name
=>
"script-name.pl"
,
description
=>
"description of script"
,
);
# Use hash ref to set description only.
my
$kingpin
= Getopt::Kingpin->new({
description
=>
"description of script"
,
});
flag($name, $description)
Add and return Getopt::Kingpin::Flag object.
# Define --debug option
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
);
# Set $debug to boolean value
$debug
->bool;
# shorthand
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->bool;
Getopt::Kingpin::Flag object has methods below.
value()
Get flag value.
my
$name
=
$kingpin
->flag(
"name"
,
"Set name."
)->string;
# perl script.pl --name 'kingpin'
printf
"%s\n"
,
$name
->value;
# -> kingpin
# simple way
printf
"%s\n"
,
$name
;
# -> kingpin
short()
Set short flag.
# Define --debug and -d
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->short(
'-d'
)->bool;
default()
The default value can be overridden with the default($value).
# Set default value to true (1)
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->
default
(1)->bool;
The default can be set to a coderef or object overloading &{}.
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->
default
(
sub
{
my
$config
= read_config_files();
return
$config
->{DEBUG};
})->bool;
override_default_from_envar()
The default value can be overridden with the override_default_from_envar($envar).
# Set default value to environment value of __DEBUG__
# export $__DEBUG__=1 to enable debug mode
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->override_default_from_envar(
"__DEBUG__"
)->bool;
required()
Set required.
my
$debug
=
$kingpin
->flag(
"debug"
,
"Enable debug mode."
)->required->bool;
placeholder()
Set placeholder value for flag in the help. Here are some examples of flags with various permutations.
--name=NAME
# flag("name")->string
--name=
"Harry"
# flag("name")->default("Harry")->string
--name=FULL-NAME
# flag("name")->placeholder("FULL-NAME")->string
hidden()
If set hidden(), flag does not appear in the help.
types
bool()
Boolean value. (0 or 1) Boolean flag has a negative complement: --<name> and --no-<name>.
# --debug or --no-debug
my
$debug
=
$kingpin
->flag(
"debug"
)->bool;
existing_dir()
Path::Tiny object.
existing_file()
Path::Tiny object.
existing_file_or_dir()
Path::Tiny object.
file()
Path::Tiny object.
int()
Integer value.
num()
Numeric value.
string()
String value. It is default type to flag.
string_list(), int_list(), file_list(), etc
Allows repeated uses of a flag.
--input=customers.csv --input=customers2.csv
string_hash(), int_hash(), file_hash(), etc
Allows repeated use of a flag as key-value pairs.
--define os=linux --define arch=x86_64
arg($name, $description)
Add and return Getopt::Kingpin::Arg object.
my
$name
=
$kingpin
->arg(
"name"
,
"Set name"
)->string;
Getopt::Kingpin::Arg object has methods below. Below are same as Flag's.
value()
Get value.
default()
Set default value.
override_default_from_envar()
Set default value by environment variable.
required()
Set required.
command()
Add sub-command.
my
$post
=
$kingpin
->command(
"post"
,
"post image"
);
parse()
Parse @arguments. If @arguments is empty, parse @ARGV.
# parse @ARGV
$kingpin
->parse;
# parse @arguments
$kingpin
->parse(
@arguments
);
If define sub-command, parse() return Getopt::Kingpin::Command object;
my
$kingpin
= Getopt::Kingpin->new();
my
$post
=
$kingpin
->command(
"post"
,
"post image"
);
my
$server
=
$post
->arg(
"server"
,
""
)->string();
my
$image
=
$post
->arg(
"image"
,
""
)->file();
my
$cmd
=
$kingpin
->parse;
printf
"cmd : %s\n"
,
$cmd
;
printf
"cmd : %s\n"
,
$cmd
->name;
You may also pass an arrayref to parse():
$kingpin
->parse( \
@arguments
);
An empty arrayref will not cause Kingpin to parse @ARGV like an empty array would.
_parse()
Parse @_. Internal use only.
version($version)
Set application version to $version.
help_short()
Internal use only.
help()
Print help.
SEE ALSO
LICENSE
Copyright (C) sago35.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
sago35 <sago35@gmail.com>