The general topic of the course labs (and all the assignments) is a library for parsing command-line arguments.
Definitions
- Short option
- A command-line argument that starts with a single dash,
followed by a single character (e.g. “
-v
”) - Long option
- A command-line argument that starts with two dashes,
followed by one or more characters (e.g. “
--version
”) - Option
- Short option or Long option
- Option parameter
- A command-line argument that follows an option (if the option is defined to accept parameters by the user of your library)
- Plain argument
- A command-line argument that is neither an option nor an option paramter.
- Delimiter
- A command-line argument consisting of two dashes only, i.e.
--
. Any subsequent argument is considered to be a plain argument
For example, in the following command
cmd -v --version -s OLD --length=20 -- -my-file your-file
there are short options v
and s
, long options version
and
length
, the OLD
and 20
represent parameters to -s
and --length
respectively. The -my-file
and your-file
arguments after the --
delimiter
plain arguments.
Functional requirements
Your library must allow the user to perform the following operations in a convenient way:
- To specify what options the client program accepts, which of them are optional and which of them are mandatory, verify the actual arguments passed to the client program conform to this specification.
- To define synonyms (at the very least 1:1 between short and long options, but ideally in a more general way).
- To specify, whether an option may/may not/must accept parameters, verify that the actual arguments passed to the client program conform to this specification.
- To specify types of parameters, verify that the actual arguments passed to the client program conform to this specification. At the very least the library has to distinguish between string parameters, integral parameters (with either or both: lower and upper bound), boolean parameters, and string parameters with fixed domain (enumeration).
- To determine what options were passed to the client program together with their parameters.
- To extract values of all plain arguments. The delimiter may be
omitted unless a plain argument starts with
-
. - To document the options and to present the documentation to the user in form of a help text.
It is not necessary to support all the above functions explicitly. For example, the validation of a type of a parameter may be performed implicitly upon retrieval of the value by the user. An exception may be thrown if the corresponding argument has incorrect type.
The requirements are intentionally not exhaustive. Use your imagination and be creative :-).
What To Submit
You will be given access to Git repository hosted on the faculty GitLab instance. You are expected to commit your solution there.
In this task, you are supposed to design the API only. Therefore, you
are expected to write source code with empty implementations of
individual methods (except for return null
and similar as required by
the compiler). The API you submit must, however, fulfill the
requirements written above.
Apart from the bare API, also must also submit an example program that uses
the API to parse the following arguments (obviously, it will fail, because
the library has no implementation yet) that are used by time
command.
time [options] command [arguments...]
GNU Options
-f FORMAT, --format=FORMAT
Specify output format, possibly overriding the format specified
in the environment variable TIME.
-p, --portability
Use the portable output format.
-o FILE, --output=FILE
Do not send the results to stderr, but overwrite the specified file.
-a, --append
(Used together with -o.) Do not overwrite but append.
-v, --verbose
Give very verbose output about all the program knows about.
GNU Standard Options
--help Print a usage message on standard output and exit successfully.
-V, --version
Print version information on standard output, then exit successfully.
-- Terminate option list.
Do NOT implement the actual command, only show how your API would be used to set-up option parsing for this command.
The source code may be in any of these programming languages: Java, C#, C or C++.
Feel free to commit also files of your build system. But bear in mind that we might ask you to change it later on to ensure smooth integration with the CI environment (however, cmake, make, Ant and Maven are okay). However, do not commit compiled files (`.class`, `.o` etc.).
Helpful questions
- What classes will the library contain? What purpose will they have?
- In what way will the user declare individual options, their parameters and synonyms? What data structures could capture these.
- In what way will the user react to options? How will the options be accessed? Callbacks? List of all options? On-demand access to particular options?
- In what way will the library validate the arguments? Explicitly/implicitly? Exceptions/Error codes? Will the library produce warnings displayed to the user directly?
Hints
- Take a look at existing libraries out there.
- Try to remedy their drawbacks and whatever annoyances you fancy.
- Modify some of your previous projects to use your API to parse its command-line options. This may help you discover design issues early in the process.