![[ Celebrate 30 years of GNU! ]](https://static.fsf.org/nosvn/misc/GNU_30th_badge.png){kind=icon}
Help! Problems and solutions
Advanced topics
Creative questions
About the project
hyphenType
Read each of the documents in the path:
Overview > Obtaining JAR > Options Interfaces > Main Class > Documentation Formatters > Validators > Unit Testing
This path is always visible at the top of each page, as bread crumbs.
If you answer 'yes' to all of the following questions, we recommend you using hyphenType. If you answered 'no' or 'maybe', you can try using hyphenType along with other tools to solve your problem:
Yes, but not only this. If you need to read textual arguments in a stand alone
application, hyphenType can help you. But hyphenType can also be used if you
have any sort of textual interface. Even if text is typed interactively in a
graphical interface.
Obviously, that is not the case for 99.99999% of graphical applications. But
hyphenType can be of some use to parse textual interactions for the other
100% - 99.99999%.
As with any tool, there are limitations. hyphenType can only parse command line
strings that fit to its simple model. We've tried to make the model as expandable
as possible, but this effort would lead us to ultimately create a complete parsing tool.
Let's consider an complex example to understand what we mean. Suppose we
want to create a command line application that will receive any sentence in English
and answer to questions.
java ai.hall9000.PsychoTherapist What is the meaning of life?
In the example above, hyphenType cannot do anything useful, since the difficulty
relies solely on processing the text and making sense of it.
Naturally, we would need to be able to recognize verbs, nouns and other elements
in the sentence. This is clearly a huge problem, AFAIK not completely solved yet.
What hypenType can do is simply to group the elements of your command line to let
you do the rest:
java ai.hall9000.PsychoTherapist --question What is the meaning of life? --expect-answer=false
Here the situation is different since hyphenType has something to contribute. It
can give you the question ("What is...") and the flag (false) as separated structures.
Each one available through its own getter method.
Obviously, hyphenType cannot check grammar mistakes in English, but it can check if
"false" is a valid value for a boolean or not.
Think of hyphenType as just a thin presentation layer for a stand alone application.
The same way you can't expect HTML to sort a list, you can't expect hyphenType to
do complex parsing.
Yes. There are two things we can test when we talk about unit tests and parsing from the command line:
Basically, you need to create a class that extends DocumentationFormatterEngine. Please check ____.
The simple answer is simply NO. But hyphenType has a rudimentary lexer and parser that will only identify things that can be transformed into the data structure of a valid options interface. This parser will try to ignore everything unexpected. But don't worry about ignored elements, since they can all be accessed via the unparsedArguments() method.
I am very glad you asked this question. In fact, I do have an extremely good one to
recommend. I've been using ANTLR with great success for already some time:
ANTLR Parser Generator.
If you want to use ANTLR, you will need to write a grammar and use ANTLR to generate
a parser and a lexer. Parsers and lexers are software components (Java classes, in my case).
Looks like a lot of trouble to parse a simple command line? If your answer is yes,
then we recommend you to see if hyphenType can solve your problem. If you think you
need something more sophisticated, then probably ANTLR is the way to go.
The simple answer is: speed. Your source code writing speed. To make a long story
short, hyphenType is an implementation of a simple grammar to parse command line
text. If you do not want to use hyphenType, you will need to write your own parser,
which takes time.
hyphenType provides command line parsing that does not require you to write a
grammar, understand EBNF syntax, understand how to generate grammars, etc.
Besides, as hyphenType was specifically designed for parsing command line arguments,
it provides some accessory tools that aims at solving some recurring problems such as
generation of help strings, issuing error codes, and stand alone application
unit testing.
If the very simple grammar of hyphenType cannot parse something you need to parse,
we recommend you to try using another tool.
If you need a complex parser, please check this question.
There is no single grammar, but instead, a family of grammars. hyphenType is a tool that allows programmers to define their own grammars. Here we do not want to go into theoretical details on what a grammar generator looks like. Instead, we will show the grammar of a certain options interface:
interface X extends Options {
@Option
boolean a();
@OptionValue(option="a")
String aValue();
@Option
boolean b();
@SimpleArgument
String c();
}At follows is the equivalent grammar for the parser.
commandLine := optionToken* (argumentToken)1 optionToken* optionToken := HYPHEN (optionName)+ | HYPHEN OPTION_A EQUALS argumentToken optionName := OPTION_A | OPTION_B argumentToken := STRING HYPHEN := - OPTION_A := 'a' OPTION_B := 'b' STRING := // Same as Java string EQUALS := '='
* is the Kleene star, meaning zero or more. +, the Kleene plus, stands for one or more. 1 stands for zero or one. The grammar above will accept any of the following:
argument -a argument -a=aValue -ab -a argument -b -b argument -a=aValue -ab -ab
By comparing the options interface and the grammar, we believe the options interface is easier to understand by Java programmers.
No.
Why not?
Because we think this is a terrible idea. If you release your command line interface and your
project is successful, you will soon see your project become the object of discussion on forums
on the Internet. Everyone wants their project to reach such momentum.
If you translate your options to each supported language, you are basically creating noise and
confusion between users. Besides, there is no great gain on having -o to mean "open" in English
and -a to mean "open" in Japanese. Why would anyone want that?
Someone had the awful idea of translating shortcuts of a popular text editor in the Portuguese
version. The result is Control+S meaning "underline" instead of "save", among other examples.
But what if I really want this? What if I simply create resource bundles that translate
the names of options in one of the locales? Will that work?
The answer is: we do not know. The system was not designed for this purpose. If you insist on
using options like that and if you are successful, go ahead but consider your solution a hack,
not a feature.
Sorry, but I really need to do this. My customer wants it, even after I presented your
arguments to him. Can you recommend me a way out?
Well, if this is not avoidable, you can try to creating one option interface for each supported
locale and use the OptionExtractor explicitly.
public static void main(String[] arguments) {
if(/*Locale is ja_JP*/) {
OptionsExtractor<MyJapaneseOptionInterface> oe =
new OptionsExtractor<MyJapaneseOptionInterface>(MyJapaneseOptionInterface.class);
MyJapaneseOptionInterface options = oe.options(arguments);
} else if(/*Locale is ancient Egyptian*/) {
// Do the same for ancient Egyptian.
} else {
// Do the same for the default locale.
}
}
The code above is not a hack, but will take a lot of your time to provide support for several locales.
We will love to receive a message from you. Please check our mailing lists.