Software:Reanmachine.CommandLine

From Reanmachine Wiki

Reanmachine.CommandLine is a .NET Library supporting versions 2.0, 3.0, and 3.5 which assists with the handling of command line arguments. Reanmachine.CommandLine is written in C# and is licenced under the GPLv3 for use by anyone.

For Example:

myprogram.exe -title="My Program"

In this case, the arguments would be passed into the application as:

What Reanmachine.CommandLine does is parses this array and produces a meta-rich argument object (CommandLineArgument) which is used to identify the relevant information:

Installation

Reanmachine.CommandLine can be used in two ways under windows, Installed into the GAC, or used by reference. If you wish to use by reference you only need to install the self-installing package, unzip the binaries package or compile the source package. You can then add the .dll as a reference to your project from it's current location.

If you wish to register the library with the GAC you will need the .NET SDK Tools. Please note, you must use the .dll contained in the binaries or self-installer packages as they are signed with a strong name.

gactutil -i c:\path\to\library\bin\Reanmachine.CommandLine\Release\Reanmachine.CommandLine.dll

By doing this you should be able to locate the library in the .NET Tab of the Reference Importer window in Visual Studio.

Usage

To use Reanmachine.CommandLine in your project you must import it as a reference to your project. This will give your project access to the binary and will make sure the library ends up in your \Debug\ and \Release\ folders for your project on compile-time.

Inclusion

Every file which will use the library must have the following line at the top of the file:

C#.NET

using Reanmachine.CommandLine;

Parsing the Command Line Arguments

To parse the command line arguments passed in to your program, you must pass the variable 'args' from your main function to the CommandLineParser class and store the returned CommandLineList.

C#.NET

[STAThread]
static void main(string [] args)
{
    CommandLineList Arguments = CommandLineParser.ParseArguments(args);
 
    ...
}

This will parse the arguments and return a list of formatted and categorized arguments.

Analyzing the returned Arguments

The class CommandLineList extends List<CommandLineArgument> and will expose all functions of List<> as well as two custom functions which were added to speed up analysis.

Example

foreach(CommandLineArgument Arg in Arguments)
{
  /* Do some kind of analysis on Arg (the current argument) */
}

Additionally you can retrieve a Queue<CommandLineArgument> so that you can pop elements off the Queue without disrupting the original list.

Example

Queue<CommandLineArgument> QArguments = Arguments.GetQueue();
 
CommandLineArgument Arg = null;
while( (Arg = QArguments.Dequeue()) != null )
{
   /* Do some kind of analysis on Arg (the current argument) */
 
   ...
 
   /* At this point QArguments does not contain Arg, so QArguments.Count will be 1 less. */
}

Finally, the last way to use the CommandLineList object, is to extract quick 'Flags'. This is usefull for determining true/false flags, like Debug Mode.

Code

[STAThread]
static void main(string [] args)
{
    CommandLineList Arguments = CommandLineParser.ParseArguments(args);
 
    if (Arguments.GetTag("debugMode") != null)
      Console.WrtieLine("Debug Mode: ON");
    else
      Console.WriteLine("Debug Mode: OFF");
}

Command Line

myprogram.exe -debugMode

Output

Debug Mode: ON

Using the Parsed Arguments

To fully understand the structure of CommandLineArgument it is suggested you review the CommandLineArgument API Documenation.

Fields

CommandLineArgument.Type	CommandLineArgumentType	The type of argument, see Argument Types below.
CommandLineArgument.Raw	String	The raw argument passed from the initial parse phase.
CommandLineArgument.Tag	String	A string value representing the 'tag' of the argument. Only used in FLAG and VALUE arguments.
CommandLineArgument.Value	String	A string value representing the 'value' of the argument. Only used in ITEM and VALUE arguments.

Argument Types

Type:	Example:	Argument:	Description:
UNKNOWN	prog.exe -f"	-f"	Used for arguments that fail the parsing process, so far only unclosed quotes will trigger this type.
ITEM	prog.exe something.txt	something.txt	Used for arguments that are a single item in themselves. Not the same as values, since values have names associated with them. (Default Argument Class)
	prog.exe "something with spaces.txt"	something with spaces.txt
FLAG	prog.exe -debugMode	debugMode	Used for arguments that are a toggle flag, a true/false value.
VALUE	prog.exe -width=800	Arg.Tag = "width"; Arg.Value = "800";	Used for arguments that have specific values assigned to variable names, or 'tags'.
	prog.exe -title="My Program"	Arg.Tag = "title"; Arg.Value = "My Program";

For further details on usage, please refer to the Reanmachine.CommandLine.Tests namespace in the project for unit tests.

Features Planned for v1.1.0.0

• Pattern matching: Allows you to enforce parameter format using basic language defenition.
• More to come...