Click here to close now.

Welcome!

Java Authors: Carmen Gonzalez, Plutora Blog, Pat Romanski, Harry Trott, Elizabeth White

Related Topics: Java

Java: Article

Parsing Command Line Arguments with Java

Parsing Command Line Arguments with Java

One of Java's great appeals is that the language provides out-of-the-box GUI development capabilities. Still, a lot of us use Java to write command line tools. Such tools are great to automate batch and offline processes. This article presents a framework that jump-starts the development of such tools.

Command line tools are usually invoked from a shell (e.g., DOS prompt, sh, ksh, etc.) and perform a certain task. The task can be customized based on the command line arguments. For instance:

telnet foo.bar.com

attempts to open a telnet connection to host foo.bar.com. It uses the default telnet port. The next example:

telnet -p 3434 foo.bar.com

attempts a similar connection using port 3434.

Command line tools can be as simple or as complicated as the developer desires. An example of a simple command line tool is the echo command found in most shells. On the other hand, the Java compiler and the Java Virtual Machine (JVM) are complex command line tools.

Java presents the command line arguments in an array of strings. This is already a huge improvement over C and C++, in which the arguments are presented as an array of C strings, i.e., an array of pointers to arrays of characters. Yet it comes short of the developer's desire to get the arguments parsed and ready to use.

Since I published my 1997 C++ command line parsing framework (see Reference), many readers have e-mailed me with requests and suggestions. The top two requests have been for a Java implementation and an improvement to handle arrays of arguments. In this article I present a total rewrite of the framework with improvements for Java programmers.

Using the Framework
Before moving to the implementation I'll demonstrate how to use the framework to write a command line utility. Let's say you want to write a utility called "mycat" - like the UNIX cat - which takes a number of files and concatenates them together into a larger file. A -v option turns verbose output on and off. A -l option allows the insertion of extra empty lines between the files. The command would look like:

&127;mycat [-l ] [-v] file1 file2 ... .

In your Main class you need to add a Token object for each argument. In this example we have three Tokens: the number of lines, the verbosity mode and the input files. In addition, you need to add an ApplicationSettings object. This object is used to contain all the arguments.

The source code for these settings is shown in Listing 1. I first declare the sm_main variable and then the three Token variables: sm_verbose, sm_files, sm_lines. The arguments in the constructor of each token object fully describe the expected usage of the Token:

  • Is it a switch or an argument?
  • What is the switch's name (e.g., -v)?
  • What is its type (integer, string, etc.)?
  • Can it appear multiple times (e.g., -l, 1, -l, 2)?
  • Is it a required argument?
  • If not, when the argument is missing:
    1. Is there an environment variable to provide the value?
    2. Is there a default value?

    A static initializer adds the Token variables to the ApplicationSettings variable. By the time the main() function of your application is reached, the ApplicationSettings object knows everything about the syntax of your command line utility.

    Listing 2 shows the main program of my example. The first line after the try statement calls the parseArgs() method of the ApplicationSettings object. The actual command line arguments are passed as an argument to the object. When the syntax is incorrect, a usage message is printed and an exception is thrown. Otherwise, the Token objects are set to contain appropriate values. For instance, when the -v option is present, the sm_verbose object will be set. Later, when its getValue() method is called, it will return true.

    In a similar fashion, if two files are passed as arguments, let's say foo.cc and bar.cc, the sm_files Token will be set appropriately. Its getValue(0) method will return foo.cc, its getValue(1) method will return bar.cc.

    Now compile the example with your favorite development environment and run the resulting code without passing any arguments. You should get the usage message in Listing 3. But wait a minute: you never wrote code to print usage messages; what's going on here? It's very simple. The framework uses the same code that defines the expected Tokens to generate usage statements. Kiss the ugly, always-out-of-date, static String statements that describe the usage of the utility goodbye.

    Now let's run the program again with some decent arguments. Let's say we run it with arguments "-v foo.cc bar.cc". The program prints the arguments correctly. Though we didn't pass any value for the -l switch, the Token returns 0. This is the expected behavior because the default value of the sm_lines Token is indeed 0.

    Why Use the Framework?
    By now some of the advantages of the framework should be obvious to you. The error-prone while and switch statements that usually parse the arguments have been replaced by a few very readable statements.

    These statements:

  • Document the usage of the command line utility
  • Encapsulate the settings so they can be used by the rest of the program
  • Automatically generate usage messages when the user enters incorrect syntax:
    1. Missing arguments
    2. Unexpected arguments
    3. Wrong types of arguments

    The stated advantages speed up the original development of any command line utility. They allow the developer to jump to the real code as soon as possible. At the same time, they provide immediate access to the command line settings and usage messages.

    Where the framework really shines is in the area where most of a developer's time is spent: software maintenance. If a command line utility is successful, users will ask for changes and improvements. Many of them will translate to more command line options or change the syntax of existing ones. The framework makes adding and modifying options trivial and safe. Compile-time messages will save the developer from runtime embarrassment.

    Finally, the framework is extensible. One can define new types of switches that accommodate new data types or anything else a developer desires.

    At this point you can go ahead, download the code and start using it in your own applications. The next few sections discuss the design of the framework.

    The StringArrayIterator Class
    The StringArrayIterator class is a utility class (see Listing 4). It encapsulates an array of strings and a position inside the array. The get() method returns the String at the current position. The moveNext() operation on the array allows the programmer to advance the current position to the next string. The EOF() operation determines when the end of the array has been reached.

    The ApplicationSettings object contains a StringArrayIterator object. It gets initialized from the command line arguments.

    The Token Class
    The Token class, shown in Listing 5, is an abstract class. Each Token object contains a description of an argument or a switch. After a successful parsing it also contains the value or values that were provided for the argument in the command line.

    During the parsing phase, the most important methods of the Token class are the parseSwitch() and parseArgument() methods. Both of them take the StringArrayIterator object with the command line arguments as input. If the current command line argument is recognized, three things occur: it's parsed, the pointer of the StringArrayIterator object is moved and a value of true is returned. If it's not recognized, a value of false is returned.

    The values that correspond to this switch or argument are stored in a Vector of objects. Subclasses determine their class. For instance, the StringToken subclass will have String objects, and the IntegerToken subclass will contain Integer objects.

    While the program is running, the values are accessible using the getValue(int) and getValue() operations.

    Token Subclasses
    A Token subclass encapsulates arguments of a specific type. For example, there's a StringToken, an IntegerToken, etc. Since most of its methods have a generic implementation, each Token subclass has very few methods to implement.

    Listing 6 presents the implementation for the class StringToken. A few more subclasses are provided in the downloaded code. You can extend the framework by implementing more subclasses.

    The ApplicationSettings Object
    The ApplicationSettings object puts everything I've discussed so far together (see Listing 7). It contains all the Token objects and initiates the parsing algorithm. The user triggers the parsing by calling the parseArgs() method.

    The command line arguments are assigned to the StringArrayIterator member of the class. Then, for every command line argument, each Token object is called and asked to parse it as either an option or an argument.

    If no Token object can parse the argument, a usage message is printed by iterating through the Tokens and calling their printUsage() and printUsageExtended() methods. Both methods take an OutputStream as an argument. They print their output to this stream.

    Pure Java and Impurities
    Almost all the code is pure Java. Since pure Java doesn't provide support for environment variables and assertions, I had to use the functions provided in my environment, the Win32 Virtual Machine.

    These few lines of code are carefully isolated in the util.java file shown in Listing 8. In a pure Java environment you can comment out three lines of code from this file. You don't get assertions and support for initialization of arguments from environment variables. Otherwise, everything else works as advertised.

    Limitations
    The framework doesn't provide support for complex scenarios. For instance, there's no support for switches that depend on each other. You can't dictate that the -t option can appear if and only if the -p option appears. You'd have to implement such checks yourself after the arguments were parsed.

    Conclusion
    In this article I presented an extensible Java framework. The framework simplifies the development and maintenance of code that parses the arguments of command line utilities and tools.

    The framework doesn't provide support for complex scenarios. Still, my experience is that the framework covers most common cases. I expect that it will be as useful for Java development as it has been for C++.

    Reference
    P. Kougiouris (1997). "Yet Another Command-Line Parser." C/C++ Users Journal, Vol. 15, No. 4, April.

  • More Stories By Panos Kougiouris

    Panos Kougiouris has ten years' experience in software development for high-tech companies. For the past three years he has been at Healtheon, a Silicon Valley startup, and he has held technical positions with Oracle and Sun Microsystems. Panos holds computer science degrees from the University of Illinois at Urbana-Champaign and the University of Patra, Greece.

    Comments (1) View Comments

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    Most Recent Comments
    AST 12/04/04 10:52:06 AM EST

    Hi. Just wanted to point out another package for solving this problem. It supports popt-style autohelp as well as POSIX options, joined options (-Wall -Dfoo=bar), repeated options and of course GNU-style (--some-long-option) options.

    Where the library really differs is that it leverages the GoF Command Pattern to make the options "active" in a similar manner to the Swing Action objects. Another feature is the ability to specify which sets of options must be present or cannot be present without requiring coding this logic yourself. The parser does the work for you.

    An article discussing how this can be done at http://te-code.sourceforge.net/article-20041121-cli.html .

    Ok, and yes, I'm a bit biased because I wrote the library... ;)

    Hope this helps,

    ast

    @ThingsExpo Stories
    Dale Kim is the Director of Industry Solutions at MapR. His background includes a variety of technical and management roles at information technology companies. While his experience includes work with relational databases, much of his career pertains to non-relational data in the areas of search, content management, and NoSQL, and includes senior roles in technical marketing, sales engineering, and support engineering. Dale holds an MBA from Santa Clara University, and a BA in Computer Science from the University of California, Berkeley.
    The cloud is now a fact of life but generating recurring revenues that are driven by solutions and services on a consumption model have been hard to implement, until now. In their session at 16th Cloud Expo, Ermanno Bonifazi, CEO & Founder of Solgenia, and Ian Khan, Global Strategic Positioning & Brand Manager at Solgenia, will discuss how a top European telco has leveraged the innovative recurring revenue generating capability of the consumption cloud to enable a unique cloud monetization model to drive results.
    As organizations shift toward IT-as-a-service models, the need for managing and protecting data residing across physical, virtual, and now cloud environments grows with it. CommVault can ensure protection &E-Discovery of your data – whether in a private cloud, a Service Provider delivered public cloud, or a hybrid cloud environment – across the heterogeneous enterprise. In his session at 16th Cloud Expo, Randy De Meno, Chief Technologist - Windows Products and Microsoft Partnerships, will discuss how to cut costs, scale easily, and unleash insight with CommVault Simpana software, the only si...
    Analytics is the foundation of smart data and now, with the ability to run Hadoop directly on smart storage systems like Cloudian HyperStore, enterprises will gain huge business advantages in terms of scalability, efficiency and cost savings as they move closer to realizing the potential of the Internet of Things. In his session at 16th Cloud Expo, Paul Turner, technology evangelist and CMO at Cloudian, Inc., will discuss the revolutionary notion that the storage world is transitioning from mere Big Data to smart data. He will argue that today’s hybrid cloud storage solutions, with commodity...
    Every innovation or invention was originally a daydream. You like to imagine a “what-if” scenario. And with all the attention being paid to the so-called Internet of Things (IoT) you don’t have to stretch the imagination too much to see how this may impact commercial and homeowners insurance. We’re beyond the point of accepting this as a leap of faith. The groundwork is laid. Now it’s just a matter of time. We can thank the inventors of smart thermostats for developing a practical business application that everyone can relate to. Gone are the salad days of smart home apps, the early chalkb...
    Cloud data governance was previously an avoided function when cloud deployments were relatively small. With the rapid adoption in public cloud – both rogue and sanctioned, it’s not uncommon to find regulated data dumped into public cloud and unprotected. This is why enterprises and cloud providers alike need to embrace a cloud data governance function and map policies, processes and technology controls accordingly. In her session at 15th Cloud Expo, Evelyn de Souza, Data Privacy and Compliance Strategy Leader at Cisco Systems, will focus on how to set up a cloud data governance program and s...
    Roberto Medrano, Executive Vice President at SOA Software, had reached 30,000 page views on his home page - http://RobertoMedrano.SYS-CON.com/ - on the SYS-CON family of online magazines, which includes Cloud Computing Journal, Internet of Things Journal, Big Data Journal, and SOA World Magazine. He is a recognized executive in the information technology fields of SOA, internet security, governance, and compliance. He has extensive experience with both start-ups and large companies, having been involved at the beginning of four IT industries: EDA, Open Systems, Computer Security and now SOA.
    The industrial software market has treated data with the mentality of “collect everything now, worry about how to use it later.” We now find ourselves buried in data, with the pervasive connectivity of the (Industrial) Internet of Things only piling on more numbers. There’s too much data and not enough information. In his session at @ThingsExpo, Bob Gates, Global Marketing Director, GE’s Intelligent Platforms business, to discuss how realizing the power of IoT, software developers are now focused on understanding how industrial data can create intelligence for industrial operations. Imagine ...
    We certainly live in interesting technological times. And no more interesting than the current competing IoT standards for connectivity. Various standards bodies, approaches, and ecosystems are vying for mindshare and positioning for a competitive edge. It is clear that when the dust settles, we will have new protocols, evolved protocols, that will change the way we interact with devices and infrastructure. We will also have evolved web protocols, like HTTP/2, that will be changing the very core of our infrastructures. At the same time, we have old approaches made new again like micro-services...
    Operational Hadoop and the Lambda Architecture for Streaming Data Apache Hadoop is emerging as a distributed platform for handling large and fast incoming streams of data. Predictive maintenance, supply chain optimization, and Internet-of-Things analysis are examples where Hadoop provides the scalable storage, processing, and analytics platform to gain meaningful insights from granular data that is typically only valuable from a large-scale, aggregate view. One architecture useful for capturing and analyzing streaming data is the Lambda Architecture, representing a model of how to analyze rea...
    SYS-CON Events announced today that Vitria Technology, Inc. will exhibit at SYS-CON’s @ThingsExpo, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Vitria will showcase the company’s new IoT Analytics Platform through live demonstrations at booth #330. Vitria’s IoT Analytics Platform, fully integrated and powered by an operational intelligence engine, enables customers to rapidly build and operationalize advanced analytics to deliver timely business outcomes for use cases across the industrial, enterprise, and consumer segments.
    Today’s enterprise is being driven by disruptive competitive and human capital requirements to provide enterprise application access through not only desktops, but also mobile devices. To retrofit existing programs across all these devices using traditional programming methods is very costly and time consuming – often prohibitively so. In his session at @ThingsExpo, Jesse Shiah, CEO, President, and Co-Founder of AgilePoint Inc., discussed how you can create applications that run on all mobile devices as well as laptops and desktops using a visual drag-and-drop application – and eForms-buildi...
    Containers and microservices have become topics of intense interest throughout the cloud developer and enterprise IT communities. Accordingly, attendees at the upcoming 16th Cloud Expo at the Javits Center in New York June 9-11 will find fresh new content in a new track called PaaS | Containers & Microservices Containers are not being considered for the first time by the cloud community, but a current era of re-consideration has pushed them to the top of the cloud agenda. With the launch of Docker's initial release in March of 2013, interest was revved up several notches. Then late last...
    SYS-CON Events announced today that Dyn, the worldwide leader in Internet Performance, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Dyn is a cloud-based Internet Performance company. Dyn helps companies monitor, control, and optimize online infrastructure for an exceptional end-user experience. Through a world-class network and unrivaled, objective intelligence into Internet conditions, Dyn ensures traffic gets delivered faster, safer, and more reliably than ever.
    CommVault has announced that top industry technology visionaries have joined its leadership team. The addition of leaders from companies such as Oracle, SAP, Microsoft, Cisco, PwC and EMC signals the continuation of CommVault Next, the company's business transformation for sales, go-to-market strategies, pricing and packaging and technology innovation. The company also announced that it had realigned its structure to create business units to more directly match how customers evaluate, deploy, operate, and purchase technology.
    In their session at @ThingsExpo, Shyam Varan Nath, Principal Architect at GE, and Ibrahim Gokcen, who leads GE's advanced IoT analytics, focused on the Internet of Things / Industrial Internet and how to make it operational for business end-users. Learn about the challenges posed by machine and sensor data and how to marry it with enterprise data. They also discussed the tips and tricks to provide the Industrial Internet as an end-user consumable service using Big Data Analytics and Industrial Cloud.
    The explosion of connected devices / sensors is creating an ever-expanding set of new and valuable data. In parallel the emerging capability of Big Data technologies to store, access, analyze, and react to this data is producing changes in business models under the umbrella of the Internet of Things (IoT). In particular within the Insurance industry, IoT appears positioned to enable deep changes by altering relationships between insurers, distributors, and the insured. In his session at @ThingsExpo, Michael Sick, a Senior Manager and Big Data Architect within Ernst and Young's Financial Servi...
    Performance is the intersection of power, agility, control, and choice. If you value performance, and more specifically consistent performance, you need to look beyond simple virtualized compute. Many factors need to be considered to create a truly performant environment. In his General Session at 15th Cloud Expo, Harold Hannon, Sr. Software Architect at SoftLayer, discussed how to take advantage of a multitude of compute options and platform features to make cloud the cornerstone of your online presence.
    Almost everyone sees the potential of Internet of Things but how can businesses truly unlock that potential. The key will be in the ability to discover business insight in the midst of an ocean of Big Data generated from billions of embedded devices via Systems of Discover. Businesses will also need to ensure that they can sustain that insight by leveraging the cloud for global reach, scale and elasticity.
    IoT is still a vague buzzword for many people. In his session at @ThingsExpo, Mike Kavis, Vice President & Principal Cloud Architect at Cloud Technology Partners, discussed the business value of IoT that goes far beyond the general public's perception that IoT is all about wearables and home consumer services. He also discussed how IoT is perceived by investors and how venture capitalist access this space. Other topics discussed were barriers to success, what is new, what is old, and what the future may hold. Mike Kavis is Vice President & Principal Cloud Architect at Cloud Technology Pa...