Currently, we have a simple command line interface that splits the command line inputs on whitespace and examines them. It works great for present purposes. But as one last Spring-quarter gesture towards making this application Unix-tastic, we would like to use Daniel Buenzli's cmdliner library. Moving to cmdliner will get us the following things:
the order of the command line switches won't matter
the switches will be typeable in short (e.g. -d, -r), verbose (e.g. --delete, --recursive), and grouped-together form (e.g. -dr)
it'll automatically generate USAGE messages
it'll automatically generate a man page
it has a notion of a subcommand, and can automatically generate error messages and man pages for those
Given that our goal for the initial Email Archives: Building Capacity and Community grant period is to have a working command line application in the UNIX style, this seems like a good step in the direction of our destination app architecture.
The Interface Itself
Our initial discussions seem to have landed on creating three modes that Attachment Converter can be run in:
MBOX Mode
Single-Email Mode
Report Mode
Attachment Converter will default to the first of these three when run without any switches. All three of these modes will work in filter style, reading from standard in by default when no command line arguments are supplied, and read from an input filepath when a filepath is supplied.
MBOX Mode
In MBOX mode, Attachment Converter will assume the input is in the form of an MBOX, and it will perform all the conversions the configration file said to perform. Its behavior should be as follows:
by default, read from standard in and print to standard out
if it is passed a single filepath, read data in from that file and print to standard out
reject more than one filepath with an error message
reject a filepath pointing at a directory with an error message
Single-Email Mode
In Single-Email mode, Attachment Converter will assume it is being given a plaintext email rather than a mailbox as an input. It will convert all attachments in the single email as per what is indicated in the configuration. This mode will activate when Attachment Converter is given the following command line switch:
--single-email
Its behavior is as follows:
by default, read from standard in and print to standard out
if it is given a single filepath, read the data from that instead and print to standard out
if passed more than one filepath, it does nothing and prints an error message
if passed a directory filepath, it does nothing and prints an error message
Report Mode
Report Mode provides a list of all the attachment types in a given mailbox. See issue #15 for details on how that feature turned out. There are two ways of running report mode: a normal version and a verbose version. The command line switch for for normal reporting is:
--report
This prints a list of all the MIME types that occur in the input, alphabetically sorted and deduped.
The command line switch for verbose reporting is:
--report-params
Thsi prints a list of all the MIME types that occur in the input MBOX, along with all the header field parameters that go along with it. (The MIME type in an email is indicated in the Content-Type header, and that header, like all headers, is allowed to have an arbitrary number of header field parameters.) The typical example of a header field parameter we've come across in this context gives the character encoding.
Regardless of whether or not the app is run in report mode verbosely or non-verbosely, it reads from standard in and writes to standard out, the same way as it does in MBOX and Single-Email modes.
Where to put the code
The code for this interface can most likely go into main.ml in the root of the project. I'll leave it to the developer's discretion about whether to break it out into a separate file.
Move to
cmdlinerfor command line interfaceCurrently, we have a simple command line interface that splits the command line inputs on whitespace and examines them. It works great for present purposes. But as one last Spring-quarter gesture towards making this application Unix-tastic, we would like to use Daniel Buenzli's
cmdlinerlibrary. Moving tocmdlinerwill get us the following things:-d,-r), verbose (e.g.--delete,--recursive), and grouped-together form (e.g.-dr)Given that our goal for the initial Email Archives: Building Capacity and Community grant period is to have a working command line application in the UNIX style, this seems like a good step in the direction of our destination app architecture.
The Interface Itself
Our initial discussions seem to have landed on creating three modes that Attachment Converter can be run in:
Attachment Converter will default to the first of these three when run without any switches. All three of these modes will work in filter style, reading from standard in by default when no command line arguments are supplied, and read from an input filepath when a filepath is supplied.
MBOX Mode
In MBOX mode, Attachment Converter will assume the input is in the form of an MBOX, and it will perform all the conversions the configration file said to perform. Its behavior should be as follows:
Single-Email Mode
In Single-Email mode, Attachment Converter will assume it is being given a plaintext email rather than a mailbox as an input. It will convert all attachments in the single email as per what is indicated in the configuration. This mode will activate when Attachment Converter is given the following command line switch:
Its behavior is as follows:
Report Mode
Report Mode provides a list of all the attachment types in a given mailbox. See issue #15 for details on how that feature turned out. There are two ways of running report mode: a normal version and a verbose version. The command line switch for for normal reporting is:
This prints a list of all the MIME types that occur in the input, alphabetically sorted and deduped.
The command line switch for verbose reporting is:
Thsi prints a list of all the MIME types that occur in the input MBOX, along with all the header field parameters that go along with it. (The MIME type in an email is indicated in the
Content-Typeheader, and that header, like all headers, is allowed to have an arbitrary number of header field parameters.) The typical example of a header field parameter we've come across in this context gives the character encoding.Regardless of whether or not the app is run in report mode verbosely or non-verbosely, it reads from standard in and writes to standard out, the same way as it does in MBOX and Single-Email modes.
Where to put the code
The code for this interface can most likely go into
main.mlin the root of the project. I'll leave it to the developer's discretion about whether to break it out into a separate file.