View source

From Reanmachine Wiki

You do not have permission to do that, for the following reasons:
This page has been locked to prevent editing.
The action you have requested is limited to users in the group moderator.
You can view and copy the source of this page:
{{Reanmachine SoftwareHeader/Product
|BaseArticle=Software:Reanmachine.CommandLine
|HasDownloads=true
|HasChangeLog=true
|API=http://www.reanmachine.com/api/Reanmachine.CommandLine/1.0.0.0/
}}
[[Category:Software Libraries|CommandLine]]
{{Infobox Software
|ProductName=Reanmachine.CommandLine
|CurrentVersion=1.0.0.0
|License={{GPLv3}}
|Language=<nowiki>C#.NET</nowiki>
|Platform={{DotNetPlatformList|Windows=2.0, 3.0, 3.5}}
|Dependancies=''None''
}}

[[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.

__TOC__

{{Software}}
{{dot net}}


[[Reanmachine.CommandLine]] was written to aid with parsing of command line arguments in .NET applications. The inspiration for this project was to tackle the problem of string values passed in the command line.

For Example:
<source lang="text">
myprogram.exe -title="My Program"
</source>
 

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

{|width="300px" class="basic-bordered"
!args[0]
|<nowiki>-</nowiki>title="My
|-
!args[1]
|Program"
|}

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

{|width="300px" class="basic-bordered"
!type
|VALUE
|-
!tag
|title
|-
!value
|My Program
|}

==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.

<source lang="text">
gactutil -i c:\path\to\library\bin\Reanmachine.CommandLine\Release\Reanmachine.CommandLine.dll
</source>

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''
<source lang="csharp">
using Reanmachine.CommandLine;
</source>

===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''
<source lang="csharp">
[STAThread]
static void main(string [] args)
{
    CommandLineList Arguments = CommandLineParser.ParseArguments(args);

    ...
}
</source>

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''
<source lang="csharp">
foreach(CommandLineArgument Arg in Arguments)
{
  /* Do some kind of analysis on Arg (the current argument) */
}
</source>

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

''Example''
<source lang="csharp">
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. */
}
</source>

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''
<source lang="csharp">
[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");
}
</source>

''Command Line''
<source lang="text">
myprogram.exe -debugMode
</source>

''Output''
<source lang="text">
Debug Mode: ON
</source>

===Using the Parsed Arguments===

To fully understand the structure of ''CommandLineArgument'' it is suggested you review the [http://www.reanmachine.com/api/Reanmachine.CommandLine/1.0.0.0/html/e1423f6d-bf35-b675-67d7-67f366ac5354.htm CommandLineArgument API Documenation].

====Fields====
:{|class="basic-bordered" width="100%"
!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====
:{|class="basic-bordered" width="100%"
!Type<nowiki>:</nowiki>
!Example<nowiki>:</nowiki>
!Argument<nowiki>:</nowiki>
!Description<nowiki>:</nowiki>
|-
!UNKNOWN
|prog.exe -f"
|<nowiki>-</nowiki>f"
|Used for arguments that fail the parsing process, so far only unclosed quotes will trigger this type.
|-
!rowspan="2"|ITEM
|prog.exe something.txt
|something.txt
|rowspan="2"|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.
|-
!rowspan="2"|VALUE
|prog.exe -width=800
|Arg.Tag = "width"; Arg.Value = "800";
|rowspan="2"|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<nowiki>:</nowiki> Allows you to enforce parameter format using basic language defenition.
*More to come...
Templates used on this page:
Return to Software:Reanmachine.CommandLine.
Retrieved from "http://reanmachine.com/wiki/Software:Reanmachine.CommandLine"
View source

From Reanmachine Wiki

Views

Personal tools

Navigation

Search

Toolbox
