Nuclex.Support/Source/Parsing/CommandLine.cs
2009-04-23 20:23:23 +00:00

251 lines
9.5 KiB
C#

#region CPL License
/*
Nuclex Framework
Copyright (C) 2002-2009 Nuclex Development Labs
This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
IBM Common Public License for more details.
You should have received a copy of the IBM Common Public
License along with this library
*/
#endregion
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Nuclex.Support.Collections;
namespace Nuclex.Support.Parsing {
/// <summary>Parses and stores an application's command line parameters</summary>
/// <remarks>
/// <para>
/// At the time of the creation of this component, there are already several command
/// line parsing libraries out there. Most of them, however, do way too much at once
/// or at the very least rely on huge, untested clutters of classes and methods to
/// arrive at their results.
/// </para>
/// <para>
/// This command line parser does nothing more than represent the command line to
/// the application through a convenient interface. It parses a command line and
/// extracts the arguments, but doesn't interpret them and or check them for validity.
/// </para>
/// <para>
/// This design promotes simplicity and makes is an ideal building block to create
/// actual command line interpreters that connect the parameters to program
/// instructions and or fill structures in code.
/// </para>
/// <para>
/// Terminology
/// <list type="table">
/// <item>
/// <term>Command line</term>
/// <description>
/// The entire command line either as a string or as
/// an already parsed data structure
/// </description>
/// </item>
/// <item>
/// <term>Argument</term>
/// <description>
/// Either an option or a loose value (see below) being specified on
/// the command line
/// </description>
/// </item>
/// <item>
/// <term>Option</term>
/// <description>
/// Can be specified on the command line and typically alters the behavior
/// of the application or changes a setting. For example, '--normalize' or
/// '/safemode'.
/// </description>
/// </item>
/// <item>
/// <term>Value</term>
/// <description>
/// Can either sit loosely in the command line (eg. 'update' or 'textfile.txt')
/// or as assignment to an option (eg. '--width=1280' or '/overwrite:always')
/// </description>
/// </item>
/// </list>
/// </para>
/// </remarks>
public partial class CommandLine {
/// <summary>Initializes a new command line</summary>
public CommandLine() : this(new List<Argument>()) { }
/// <summary>Initializes a new command line</summary>
/// <param name="argumentList">List containing the parsed arguments</param>
private CommandLine(List<Argument> argumentList) {
this.arguments = argumentList;
}
/// <summary>Parses the command line arguments from the provided string</summary>
/// <param name="commandLineString">String containing the command line arguments</param>
/// <returns>The parsed command line</returns>
/// <remarks>
/// You should always pass Environment.CommandLine to this methods to avoid
/// some problems with the build-in command line tokenizer in .NET
/// (which splits '--test"hello world"/v' into '--testhello world/v')
/// </remarks>
public static CommandLine Parse(string commandLineString) {
bool windowsMode = (Path.DirectorySeparatorChar != '/');
return Parse(commandLineString, windowsMode);
}
/// <summary>Parses the command line arguments from the provided string</summary>
/// <param name="commandLineString">String containing the command line arguments</param>
/// <param name="windowsMode">Whether the / character initiates an argument</param>
/// <returns>The parsed command line</returns>
/// <remarks>
/// You should always pass Environment.CommandLine to this methods to avoid
/// some problems with the build-in command line tokenizer in .NET
/// (which splits '--test"hello world"/v' into '--testhello world/v')
/// </remarks>
public static CommandLine Parse(string commandLineString, bool windowsMode) {
return new CommandLine(
Parser.Parse(commandLineString, windowsMode)
);
}
/// <summary>Returns whether an argument with the specified name exists</summary>
/// <param name="name">Name of the argument whose existence will be checked</param>
/// <returns>True if an argument with the specified name exists</returns>
public bool HasArgument(string name) {
return (indexOfArgument(name) != -1);
}
/// <summary>Adds a value to the command line</summary>
/// <param name="value">Value that will be added</param>
public void AddValue(string value) {
bool valueContainsSpaces = (value.IndexOfAny(new char[] { ' ', '\t' }) != -1);
if(valueContainsSpaces) {
StringBuilder builder = new StringBuilder(value.Length + 2);
builder.Append('"');
builder.Append(value);
builder.Append('"');
this.arguments.Add(
Argument.ValueOnly(
new StringSegment(builder.ToString(), 0, value.Length + 2),
1,
value.Length
)
);
} else {
this.arguments.Add(
Argument.ValueOnly(new StringSegment(value), 0, value.Length)
);
}
}
/// <summary>Adds an option to the command line</summary>
/// <param name="name">Name of the option that will be added</param>
public void AddOption(string name) {
AddOption("-", name);
}
/// <summary>Adds an option to the command line</summary>
/// <param name="initiator">Initiator that will be used to start the option</param>
/// <param name="name">Name of the option that will be added</param>
public void AddOption(string initiator, string name) {
StringBuilder builder = new StringBuilder(
initiator.Length + name.Length
);
builder.Append(initiator);
builder.Append(name);
this.arguments.Add(
Argument.OptionOnly(
new StringSegment(builder.ToString()),
initiator.Length,
name.Length
)
);
}
/// <summary>Adds an option with an assignment to the command line</summary>
/// <param name="name">Name of the option that will be added</param>
/// <param name="value">Value that will be assigned to the option</param>
public void AddAssignment(string name, string value) {
AddAssignment("-", name, value);
}
/// <summary>Adds an option with an assignment to the command line</summary>
/// <param name="initiator">Initiator that will be used to start the option</param>
/// <param name="name">Name of the option that will be added</param>
/// <param name="value">Value that will be assigned to the option</param>
public void AddAssignment(string initiator, string name, string value) {
bool valueContainsSpaces = (value.IndexOfAny(new char[] { ' ', '\t' }) != -1);
StringBuilder builder = new StringBuilder(
initiator.Length + name.Length + 1 + value.Length +
(valueContainsSpaces ? 2 : 0)
);
builder.Append(initiator);
builder.Append(name);
builder.Append('=');
if(valueContainsSpaces) {
builder.Append('"');
builder.Append(value);
builder.Append('"');
} else {
builder.Append(value);
}
this.arguments.Add(
new Argument(
new StringSegment(builder.ToString()),
initiator.Length,
name.Length,
initiator.Length + name.Length + 1 +
(valueContainsSpaces ? 1 : 0),
value.Length
)
);
}
/// <summary>Returns a string that contains the entire command line</summary>
/// <returns>The entire command line as a single string</returns>
public override string ToString() {
return Formatter.FormatCommandLine(this);
}
/// <summary>Retrieves the index of the argument with the specified name</summary>
/// <param name="name">Name of the argument whose index will be returned</param>
/// <returns>
/// The index of the indicated argument of -1 if no argument with that name exists
/// </returns>
private int indexOfArgument(string name) {
for(int index = 0; index < this.arguments.Count; ++index) {
if(this.arguments[index].Name == name) {
return index;
}
}
return -1;
}
/// <summary>Options that were specified on the command line</summary>
public IList<Argument> Arguments {
get { return this.arguments; }
}
/// <summary>Options that were specified on the command line</summary>
private List<Argument> arguments;
}
} // namespace Nuclex.Support.Parsing