.\" Copyright (c) 2018-2023, OARC, Inc.
.\" All rights reserved.
.\"
.\" This file is part of dnsjit.
.\"
.\" dnsjit is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" dnsjit is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with dnsjit.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsjit.lib.getopt 3 "1.3.0" "dnsjit"
.SH NAME
dnsjit.lib.getopt \- Parse and handle arguments
.SH SYNOPSIS
  local getopt = require("dnsjit.lib.getopt").new({
      { "v", "verbose", 0, "Enable verbosity", "?+" },
      { nil, "host", "localhost", "Set host", "?" },
      { "p", nil, 53, "Set port", "?" },
  })

  local left = getopt:parse()

  print("host", getopt:val("host"))
  print("port", getopt:val("p"))
.SH DESCRIPTION
A "getopt long" implementation to easily handle command line arguments
and display usage.
An option is the short name (one character), long name,
default value (which also defines the type), help text and extensions.
Options are by default required, see extensions to change this.
.LP
The Lua types allowed are
.BR boolean ,
.BR string ,
.BR number .
.LP
The extensions available are:
.TP
.B ?
Make the option optional.
.TP
.B *
For string and number options this make it possible to specified it
multiple times and all values will be returned in a table.
.TP
.B +
For number options this will act as an counter increaser, the value will
be the default value + 1 for each time the option is given.
.LP
Option
.I -h
and
.I --help
are automatically added if the option
.I --help
is not already defined.
.SS Attributes
.TP
left
A table that contains the arguments left after parsing, same as returned by
.IR parse() .
.TP
usage_desc
A string that describes the usage of the program, if not set then the
default will be "
.I "program [options...]"
".
.SS Functions
.TP
.BR Getopt.new "(args)"
Create a new Getopt object.
.I args
is a table with tables that specifies the options available.
Each entry is unpacked and sent to
.BR Getopt:add() .
.TP
.BR Getopt:log "()"
Return the Log object to control logging of this instance or module.
.TP
.BR Getopt:add "(short, long, default, help, extensions)"
Add an option.
.TP
.BR Getopt:usage "()"
Print the usage.
.TP
.BR Getopt:parse "(args, startn)"
Parse the options.
If
.I args
is not specified or nil then the global
.B arg
is used.
If
.I startn
is given, it will start parsing arguments in the table from that position.
The default position to start at is 2 for
.IR dnsjit ,
see
.BR dnsjit.core (3).
.TP
.BR Getopt:val "(name)"
Return the value of an option.
.SH SEE ALSO
.BR dnsjit.core (3)
.SH AUTHORS and CONTRIBUTORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC),
Petr Špaček (ISC)
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fIhttps://github.com/DNS-OARC/dnsjit/issues\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fIadmin@dns-oarc.net\fP
.RE
.LP