Click here to Skip to main content
15,867,686 members
Articles / Programming Languages / C#
Article

Full-featured Automatic Argument Parser

Rate me:
Please Sign up or sign in to vote.
4.84/5 (43 votes)
5 Nov 2003MIT4 min read 115.2K   1.6K   71   28
Argument parser utility class which makes good use of custom attributes.

Contents

Introduction

What? Yet another argument parsing class?! What for? Well, actually for a couple of reasons:

  • Supports many argument types:
    • Switches (eg. /foo, /foo=1, /foo=true [localized])
    • Named/unnamed flags (eg. -raFl, -aABCDEF). Flags are "type-safe" in the sense that you specify which values are accepted. For example, if the user writes -raFlW and 'W' is not an accepted flag, then an ArgumentFormatException is raised.
    • Named/unnamed values (eg. /foo=bar, "foo")
    • Any prefix(es) you specify (eg. -foo, /foo, \foo, ...)
    • Any assignment symbol(s) (eg. /foo=bar, /foo:bar, ...)
    • Any additional or overriding pattern you provide
  • Automatically sets field/property values according to arguments provided using custom attributes.
    • All value types are supported, including enumerations.
    • You can specify a single member, a class, a type (for static members) or an assembly.
    • One argument can set many members at once, even if located in different types.
  • Supports globalization through custom attributes (ie you provide a ResourceManager, a CultureInfo and a resource ID and the argument name/alias will be automatically updated according to resource file). This works for switches, named values and flags.
  • Keeps track of handled and unhandled arguments.
  • All that in less than 400 lines of code. :)

I want to thank Ray Hayes for his idea of automatically setting field/property by judiciously using custom attributes. This is a great example of that proverbial 1% of inspiration. :) Take a look at his article here.

Quick Example

This is an example quickly showing how you might use the class, more or less taken from the included demo, which by the way is a utility I posted some time ago on this site. You can read the article here.

C#
using Common;
using Common.IO;
using System;
using System.Collections;
using System.Collections.Specialized;
using System.IO;

namespace xmove
{
    class XMove
    {
        private static System.Resources.ResourceManager m_resMan;

        // this argument can either be named "batch", "file", "batchFile"
        // or even "smurf" if you fancy it
        [AutoSetMember("batch", "file", "batchFile", "smurf")]
        private static String m_batchFile;

        [AutoSetMember("yc", SwitchMeansFalse=true)]
        private static bool m_confirmMove = true;

        [AutoSetMember("yc", SwitchMeansFalse=true)]
        private static bool m_confirmOverwrite = true;
        
        [AutoSetMember("r")]
        private static bool m_recursive = false;
        
        private static FindFile.SearchAttributes m_searchAttributes;
        
        [STAThread]
        static void Main(string[] args)
        {
            // a FlagCollection contains all accepted flags
            FlagCollection flags = new FlagCollection();
            
            // here we add the flag named "a" with accepted values
            // a,c,d,h,...
            // the argument must then looks like "-a<VALUES>" on the command
            // line
            flags.Add("a", "acdehnorstFA");
            
            // create a new parser that accept all argument formats,
            // is case sensitive and accept provided flags
            ArgumentParser parser = new ArgumentParser(ArgumentFormats.All,
                false, flags);
            
            // parse the arguments with the result stored in a
            // StringDictionary
            StringDictionary theArgs = parser.Parse(args);

            // automatically set all static members of the class XMove
            parser.AutoSetMembers(typeof(XMove));
            
            // now, the values of m_batchFile, m_confirmMove,
            // m_confirmOverwrite and m_recursive are all set !
            
            // the corresponding arguments have been moved to
            // parser.HandledArguments
            // the remaining arguments are in parser.UnhandledArguments
            
            // one argument remains which can't be set automatically
            if (theArgs.ContainsKey("a"))
            {
                String attribs = theArgs[m_resMan.GetString("app0019")];
                
                if (attribs.IndexOf("A") > -1)
                    m_searchAttributes |= FindFile.SearchAttributes.All;

                if (attribs.IndexOf("F") > -1)
                    m_searchAttributes |= FindFile.SearchAttributes.AnyFile;
                
                .........
            }
            
            
            // here we load the resources for the application
            LoadResources();
            
            // we then set the resource manager of the
            // AutoSetMemberAttribute accordingly
            // why this property is static is explained in the
            // "How it Works" section of this article
            AutoSetMemberAttribute.Resources = m_resMan;

            // create a new instance of Dummy class
            Dummy dummy = new Dummy();
            
            // then set members of this class, no matter if they are
            // static, instance, public, private, protected, internal
            
            // type conversion is done automatically !
            parser.AutoSetMembers(dummy);
        }
        
        private void LoadResources()
        {
            ....
        }
    }
    
    class Dummy
    {
        public enum MyEnum
        {
            a,
            b,
            c,
            d
        }
        
        [AutoSetMember("foo")]
        private static int field1;
        
        // here we indicate that the argument name is to be retrieved using
        // the ResourceManager at runtime
        [AutoSetMember(ResID="0001")]
        private Double field2;
        
        // same here
        [AutoSetMember(ResID="0002")]
        protected String Property1
        {
            get {...}
            set {...}
        }
        
        [AutoSetMember("buzz")]
        public MyEnum Property2
        {
            get {...}
            set {...}
        }
    }
}

Using the code

Two main classes do all the work: ArgumentParser and AutoSetMemberAttribute. As usual, contructors let you directly set one or more properties, so I will skip them.

ArgumentParser class

Properties

public char[] AllowedPrefixes [get, set]
The accepted prefix(es).

public ArgumentFormats ArgumentFormats [get, set]<BR>The accepted argument format(s).

public char[] AssignSymbols [get, set]
The accepted assignation symbol(s).

public string CustomPattern [get, set]
An additional or overriding pattern. In the pattern, use capture name constants made public by this class (ArgumentNameCaptureName, ArgumentValueCaptureName, FlagNameCaptureName, FlagsCaptureName and PrefixCaptureName).

public StringDictionary HandledArguments [get]
The argument(s) that have been automatically set by AutoSetMembers method.

public StringDictionary UnhandledArguments [get]
The argument(s) that have not been automatically set by AutoSetMembers method.

public bool UseOnlyCustomPattern [get, set]
Indicates if the custom pattern provided is overriding the internal pattern automatically generated.

Methods

public StringDictionary Parse(string[] args)
Parses the array of arguments and returns the dictionary of parsed arguments
UnhandledArgument property is also updated accordingly.

public void AutoSetMembers(Assembly assembly)
public void AutoSetMembers(Type type)
public void AutoSetMembers(object instance)
public void AutoSetMembers(object classToProcess, MemberInfo member)
Automatically sets member(s) of the provided assembly, type, class instance. Also works for a single field/property.

public void Clear()
Clears all saved arguments (both handled and unhandled).

private void BuildPattern()
Builds the pattern to be used when parsing each argument.

private void SetMemberValue(object instance, MemberInfo memberInfo, object value)<BR>Set the static or instance member to the specified value.

AutoSetMemberAttribute

Properties

public static CultureInfo Culture [get, set]
The culture to be used for retrieving culture aware aliases.

public static ResourceManager Resources [get, set]
The resource manager to be used for retrieving culture aware aliases.

public ArrayList Aliases [get]
Command line argument's name or aliases if many names are possible.

public string Description [get, set]
The description of the command line argument.

public object ID [get, set]
An ID (can be anything you want).

public string ResID [get, set]
The resource ID to be used when retrieving culture aware aliases.

public bool SwitchMeansFalse [get, set]
Indicates if the meaning of a switch is false instead of true as usual.

How it Works

Parsing of the command line

Here is a quick explanation of the regex that is constructed by ArgumentParser.BuildPattern() private method. Variables are indicated by capitalized names and are to be replaced at runtime.

// The whole parsing string (with all possible argument formats) :
// ---------------------------------------------------------------
// (CUSTOM_PATTERN)
// |(^(?<PREFIX>[PREFIXES])(?<FLAGNAME>)FLAG_NAMES)(?<FLAGS>[FlagsCaptureName]+)$)
// |(^(?<PREFIX>[PREFIXES])(?<NAME>[^EQUAL_SYMBOLS]+)([EQUAL_SYMBOLS](?<VALUE>.+))?$)
// |(LITERAL_STRING_SYMBOL?(?<VALUE>.*))
//
// Again, but commented :
// ----------------------
// (CUSTOM_PATTERN)|        # custom pattern, if any (it has priority over
//                          # standard pattern)
//
// foreach flag in FlagCollection :
//
// (^
// (?<PREFIX>[PREFIXES])            # mandatory prefix
// (?<FLAGNAME>)FLAG_NAMES)       # flag name
// (?<FLAGS>[FlagsCaptureName]+)  # flag value
// $)|
//
// (^
// (?<PREFIX>[PREFIXES])            # mandatory prefix
// (?<NAME>[^EQUAL_SYMBOLS]+)     # argument name (which includes flag
//                                # name/values)
// ([EQUAL_SYMBOLS](?<VALUE>.+))? # argument value, if any
// $)
//
// |(
// LITERAL_STRING_SYMBOL?   # optional @ caracter indicating literal string
// (?<VALUE>.*)             # standalone value (will be given an index when
//                          # parsed in Parse() method)
// )

Automatically setting member values

At design time, AutoSetMemberAttribute custom attribute is used to specify which argument will be used to set the affected member. Other informations include description, resource ID and an ID that you might use at your convenience.

At runtime, you can set the AutoSetMemberAtttribute static properties Resource and Culture. It's necessary to make those properties static because attributes are serialized at compile time, so they can only have constant values as instance properties.

When you execute ArgumentParser.SetAutoMembers(...), the following occurs :

  1. AutoSetMember attributes will be located using reflection.
  2. If a resource ID is specified and a resource manager and a culture are provided, the localized argument name will be added as an alias.
  3. The argument associated to the member (if any) will be converted to the member's type
  4. The member's value will be updated using ArgumentParser.SetMemberValue(...).
  5. The argument will be removed from ArgumentParser.UnhandledArguments and added to ArgumentParser.HandledArguments.
C#
/// <SUMMARY>
/// Automatically sets members for the provided
/// <SEE cref="System.Reflection.Assembly" />.
/// </SUMMARY>
/// <PARAM name="assembly">The <SEE cref="System.Reflection.Assembly" /> to process.</PARAM>
public void AutoSetMembers(Assembly assembly)
{
    Type[] types = assembly.GetTypes();

    foreach (Type type in types)
        AutoSetMembers(type);
}

/// <SUMMARY>
/// Automatically sets members for the provided <SEE cref="System.Type" />.
/// </SUMMARY>
/// <PARAM name="type">The <SEE cref="System.Type" /> to process.</PARAM>
/// <REMARKS>Only static members will be processed.</REMARKS>
public void AutoSetMembers(Type type)
{
    MemberInfo[] members = type.FindMembers(
        AutoSetMemberAttribute.SupportedMemberTypes,
        AutoSetMemberAttribute.SupportedBindingFlags, Type.FilterName, "*");

    foreach (MemberInfo member in members)
        AutoSetMembers(type, member);
}

/// <SUMMARY>
/// Automatically sets members for the provided class instance.
/// </SUMMARY>
/// <PARAM name="instance">The class instance to process. Must not be null.</PARAM>
/// <REMARKS>Both static and instance members will be processed.</REMARKS>
public void AutoSetMembers(object instance)
{
    MemberInfo[] members = instance.GetType().FindMembers(
        AutoSetMemberAttribute.SupportedMemberTypes,
        AutoSetMemberAttribute.SupportedBindingFlags, Type.FilterName, "*");

    foreach (MemberInfo member in members)
        AutoSetMembers(instance, member);
}

/// <SUMMARY>
/// Automatically sets member of the provided class instance or
/// <SEE cref="System.Type" />.
/// </SUMMARY>
/// <PARAM name="classToProcess">The class instance or <SEE cref="System.Type" /> to process.</PARAM>
/// <PARAM name="member">The member which will be set. Must be a field or a property.</PARAM>
/// <REMARKS>Both static and instance members are accepted.</REMARKS>
public void AutoSetMembers(object classToProcess, MemberInfo member)
{
    AutoSetMemberAttribute attrib = Attribute.GetCustomAttribute(member,
        typeof(AutoSetMemberAttribute)) as AutoSetMemberAttribute;

    if (attrib != null)
    {
        if (attrib.ResID != null && AutoSetMemberAttribute.Resources != null)
            attrib.Aliases.Add(AutoSetMemberAttribute.Resources.GetString(
                attrib.ResID, AutoSetMemberAttribute.Culture));

        String argValue = null;
        bool found = false;

        foreach (String alias in attrib.Aliases)
        {
            if (m_unhandled.ContainsKey(alias))
            {
                argValue = (String)m_unhandled[alias];

                m_handled.Add(alias, argValue);
                m_unhandled.Remove(alias);

                found = true;
                break;
            }
            else if (m_handled.ContainsKey(alias))
            {
                argValue = (String)m_handled[alias];

                found = true;
                break;
            }
        }

        if (found)
        {
            Type memberType = null;

            switch (member.MemberType)
            {
                case MemberTypes.Property:
                    memberType = ((PropertyInfo)member).PropertyType;
                    break;

                case MemberTypes.Field:
                    memberType = ((FieldInfo)member).FieldType;
                    break;
            }

            if (memberType == typeof(bool))
            {
                if (argValue == "")
                    SetMemberValue(classToProcess, member,
                        !attrib.SwitchMeansFalse);
                else if (argValue == Boolean.FalseString ||
                    argValue == Boolean.TrueString)
                    SetMemberValue(classToProcess, member,
                        Boolean.Parse(argValue));
                else
                    // last chance ... if can't parse it as integer, an
                    // exception will be raised
                    SetMemberValue(classToProcess, member,
                        Int32.Parse(argValue) != 0);
            }
            else if (memberType == typeof(String))
                SetMemberValue(classToProcess, member, argValue);
            else if (memberType.IsEnum)
            {
                object value = Enum.Parse(memberType, argValue,
                    m_ignoreCase);
                SetMemberValue(classToProcess, member, value);
            }
            else if (memberType.IsValueType)
                SetMemberValue(classToProcess, member,
                    Convert.ChangeType(argValue, memberType));
        }
    }
}

/// <SUMMARY>
/// Sets the static or instance member (property or field) to the specified
/// value.
/// </SUMMARY>
/// <PARAM name="instance">The class instance or <SEE cref="System.Type" /> to be used.</PARAM>
/// <PARAM name="memberInfo">The member to be set.</PARAM>
/// <PARAM name="value">The new value of the member.</PARAM>
private void SetMemberValue(object instance, MemberInfo memberInfo,
    object value)
{
    if (memberInfo is PropertyInfo)
    {
        PropertyInfo pi = (PropertyInfo) memberInfo;

        if (pi.CanWrite)
        {
            MethodInfo methodInfo = pi.GetSetMethod(true);

            BindingFlags bindingFlags = BindingFlags.SetProperty;

            if (methodInfo.IsStatic)
                bindingFlags |= BindingFlags.Static;

            pi.SetValue(instance, value, bindingFlags, null, null, null);
        }
    }
    else if (memberInfo is FieldInfo)
    {
        FieldInfo fi = (FieldInfo) memberInfo;

        BindingFlags bindingFlags = BindingFlags.SetField;

        if (fi.IsStatic)
            bindingFlags |= BindingFlags.Static;

        fi.SetValue(instance, value, bindingFlags, null, null);
    }
}

License

This article, along with any associated source code and files, is licensed under The MIT License


Written By
Architect
Canada Canada
Sébastien Lorion is software architect as day job.

He is also a musician, actually singing outside the shower Smile | :)

He needs constant mental and emotional stimulation, so all of this might change someday ...

Comments and Discussions

 
Generalhiiiiiiiiii Pin
glory44415-Apr-11 8:58
glory44415-Apr-11 8:58 
QuestionHow get a regular parameter rather than an option? Pin
DaveKolb2-Apr-09 20:00
DaveKolb2-Apr-09 20:00 
AnswerRe: How get a regular parameter rather than an option? Pin
Sebastien Lorion3-Apr-09 5:27
Sebastien Lorion3-Apr-09 5:27 
GeneralRe: How get a regular parameter rather than an option? Pin
DaveKolb3-Apr-09 8:31
DaveKolb3-Apr-09 8:31 
AnswerRe: How get a regular parameter rather than an option? Pin
Sebastien Lorion3-Apr-09 9:06
Sebastien Lorion3-Apr-09 9:06 
GeneralRe: How get a regular parameter rather than an option? Pin
DaveKolb3-Apr-09 9:15
DaveKolb3-Apr-09 9:15 
AnswerRe: How get a regular parameter rather than an option? Pin
Sebastien Lorion3-Apr-09 9:35
Sebastien Lorion3-Apr-09 9:35 
AnswerRe: How get a regular parameter rather than an option? Pin
Sebastien Lorion4-Apr-09 17:59
Sebastien Lorion4-Apr-09 17:59 
GeneralRe: How get a regular parameter rather than an option? Pin
DaveKolb4-Apr-09 19:58
DaveKolb4-Apr-09 19:58 
QuestionSuggestion Pin
exbuddha16-Oct-06 10:14
exbuddha16-Oct-06 10:14 
Hi... Nice work for sure! I like how simple it is to grab your code and use it with just a few lines of code. I was wondering if you can update the regex to accept this type of inputs "/i 2" instead of "/i:25" or "/i=25". I was not able to use your code for that type of user input.

Thanks.
AnswerRe: Suggestion Pin
Sebastien Lorion16-Oct-06 10:21
Sebastien Lorion16-Oct-06 10:21 
GeneralRe: Suggestion Pin
exbuddha16-Oct-06 12:32
exbuddha16-Oct-06 12:32 
QuestionUse the same switch twice Pin
Armus15-Sep-06 1:57
Armus15-Sep-06 1:57 
AnswerRe: Use the same switch twice Pin
Sebastien Lorion15-Sep-06 3:58
Sebastien Lorion15-Sep-06 3:58 
QuestionDoes the code check for invalid options? Pin
Josef Meile15-Feb-05 9:30
Josef Meile15-Feb-05 9:30 
AnswerRe: Does the code check for invalid options? Pin
Sebastien Lorion17-Feb-05 2:50
Sebastien Lorion17-Feb-05 2:50 
GeneralAutoSetMember for VB.NET? Pin
mike2orb23-Jan-04 18:04
mike2orb23-Jan-04 18:04 
GeneralRe: AutoSetMember for VB.NET? Pin
Guy LaRochelle29-Nov-04 2:27
Guy LaRochelle29-Nov-04 2:27 
QuestionWhy GPL? Pin
godefroi5-Nov-03 11:39
godefroi5-Nov-03 11:39 
AnswerRe: Why GPL? Pin
Sebastien Lorion5-Nov-03 19:17
Sebastien Lorion5-Nov-03 19:17 
GeneralLooks Great Pin
William Bartholomew7-Sep-03 11:48
William Bartholomew7-Sep-03 11:48 
GeneralRe: Looks Great Pin
Sebastien Lorion7-Sep-03 15:36
Sebastien Lorion7-Sep-03 15:36 
GeneralBest argument parser yet Pin
scadaguy5-Sep-03 3:10
scadaguy5-Sep-03 3:10 
GeneralRe: Best argument parser yet Pin
Sebastien Lorion5-Sep-03 12:10
Sebastien Lorion5-Sep-03 12:10 
GeneralGreat Utility - One Suggestion Pin
Heath Stewart5-Sep-03 2:30
protectorHeath Stewart5-Sep-03 2:30 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.