private static ConsoleString GetOptionsUsage(IEnumerable <CommandLineArgument> opts, bool ignoreActionProperties, ArgUsageOptions options)
{
if (opts.Count() == 0)
{
return(new ConsoleString("There are no options\n"));
}
var usageInfos = opts.Select(o => new ArgumentUsageInfo(o));
var hasPositionalArgs = usageInfos.Where(i => i.Position >= 0).Count() > 0;
List <ConsoleString> columnHeaders = new List <ConsoleString>()
{
new ConsoleString("OPTION", ConsoleColor.Yellow),
new ConsoleString("DESCRIPTION", ConsoleColor.Yellow),
};
bool hasTypeCol = false, hasPosCol = false;
int insertPosition = 1;
if (options.ShowType)
{
columnHeaders.Insert(insertPosition++, new ConsoleString("TYPE", ConsoleColor.Yellow));
hasTypeCol = true;
}
if (hasPositionalArgs && options.ShowPosition)
{
columnHeaders.Insert(insertPosition, new ConsoleString("POSITION", ConsoleColor.Yellow));
hasPosCol = true;
}
List <List <ConsoleString> > rows = new List <List <ConsoleString> >();
foreach (ArgumentUsageInfo usageInfo in usageInfos.OrderBy(i => i.Position >= 0 ? i.Position : 1000))
{
var hooks = new List <UsageHook>();
if (usageInfo.Property != null && ArgUsage.ExplicitPropertyHooks.ContainsKey(usageInfo.Property))
{
hooks.AddRange(ArgUsage.ExplicitPropertyHooks[usageInfo.Property]);
}
hooks.AddRange(ArgUsage.GlobalUsageHooks);
hooks.AddRange(usageInfo.Argument.UsageHooks);
foreach (var hook in hooks)
{
hook.BeforeGenerateUsage(usageInfo);
}
if (usageInfo.Ignore)
{
continue;
}
if (usageInfo.IsAction && ignoreActionProperties)
{
continue;
}
var positionString = new ConsoleString(usageInfo.Position >= 0 ? usageInfo.Position + "" : "NA");
var requiredString = new ConsoleString(usageInfo.IsRequired ? "*" : "", ConsoleColor.Red);
var descriptionString = new ConsoleString(usageInfo.Description);
if (options.AppendDefaultValueToDescription && usageInfo.DefaultValue != null)
{
descriptionString += new ConsoleString(" [default=" + usageInfo.DefaultValue.ToString() + "]", ConsoleColor.DarkGreen);
}
var typeString = new ConsoleString(usageInfo.Type);
var aliases = usageInfo.Aliases.OrderBy(a => a.Length).ToList();
var maxInlineAliasLength = 8;
string inlineAliasInfo = "";
int aliasIndex;
for (aliasIndex = 0; aliasIndex < aliases.Count; aliasIndex++)
{
var proposedInlineAliases = inlineAliasInfo == string.Empty ? aliases[aliasIndex] : inlineAliasInfo + ", " + aliases[aliasIndex];
if (proposedInlineAliases.Length <= maxInlineAliasLength)
{
inlineAliasInfo = proposedInlineAliases;
}
else
{
break;
}
}
if (inlineAliasInfo != string.Empty)
{
inlineAliasInfo = " (" + inlineAliasInfo + ")";
}
rows.Add(new List <ConsoleString>()
{
new ConsoleString("") + (usageInfo.Name + inlineAliasInfo),
descriptionString,
});
insertPosition = 1;
if (options.ShowType)
{
rows.Last().Insert(insertPosition++, typeString + requiredString);
}
if (hasPositionalArgs && options.ShowPosition)
{
rows.Last().Insert(insertPosition, positionString);
}
for (int i = aliasIndex; i < aliases.Count; i++)
{
rows.Add(new List <ConsoleString>()
{
new ConsoleString(" " + aliases[i]),
ConsoleString.Empty,
});
if (hasTypeCol)
{
rows.Last().Add(ConsoleString.Empty);
}
if (hasPosCol)
{
rows.Last().Add(ConsoleString.Empty);
}
}
if (options.ShowPossibleValues)
{
foreach (var possibleValue in usageInfo.PossibleValues)
{
rows.Add(new List <ConsoleString>()
{
ConsoleString.Empty,
new ConsoleString(" " + possibleValue),
});
if (hasTypeCol)
{
rows.Last().Insert(rows.Last().Count - 1, ConsoleString.Empty);
}
if (hasPosCol)
{
rows.Last().Insert(rows.Last().Count - 1, ConsoleString.Empty);
}
}
}
}
return(FormatAsTable(columnHeaders, rows, " "));
}
public static ConsoleString GetStyledUsage(Type t, string exeName = null, ArgUsageOptions options = null)
{
return(GetStyledUsage(new CommandLineArgumentsDefinition(t), exeName, options));
}
public static ConsoleString GetStyledUsage(CommandLineArgumentsDefinition definition, string exeName = null, ArgUsageOptions options = null)
{
if (ArgHook.HookContext.Current != null && ArgHook.HookContext.Current.Definition == definition)
{
ArgHook.HookContext.Current.RunBeforePrepareUsage();
}
options = options ?? new ArgUsageOptions();
if (exeName == null)
{
var assembly = Assembly.GetEntryAssembly();
if (assembly == null)
{
throw new InvalidOperationException("PowerArgs could not determine the name of your executable automatically. This may happen if you run GetUsage<T>() from within unit tests. Use GetUsageT>(string exeName) in unit tests to avoid this exception.");
}
exeName = Path.GetFileNameWithoutExtension(Assembly.GetEntryAssembly().Location);
}
ConsoleString ret = new ConsoleString();
ret += new ConsoleString("Usage: " + exeName, ConsoleColor.Cyan);
if (definition.Actions.Count > 0)
{
string actionText = options.SpecifiedActionOverride == null ? "<action>" : options.SpecifiedActionOverride.DefaultAlias;
ret = ret.AppendUsingCurrentFormat(" " + actionText + " options\n");
foreach (var example in definition.Examples)
{
ret += new ConsoleString("\nEXAMPLE: " + example.Example + "\n" + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
if (definition.Arguments.Count > 0)
{
var global = GetOptionsUsage(definition.Arguments, true, options);
if (string.IsNullOrEmpty(global.ToString()) == false)
{
ret += new ConsoleString("\nGlobal options:\n\n", ConsoleColor.Cyan) + global + "\n";
}
}
var specifiedAction = definition.SpecifiedAction;
if (options.SpecifiedActionOverride != null)
{
specifiedAction = options.SpecifiedActionOverride;
if (definition.Actions.Contains(specifiedAction) == false)
{
throw new InvalidArgDefinitionException("There is no action that matches '" + options.SpecifiedActionOverride + "'");
}
}
if (specifiedAction == null)
{
ret += new ConsoleString("Actions:", ConsoleColor.Cyan);
}
foreach (var action in definition.Actions)
{
if (specifiedAction != null && action.Equals(specifiedAction) == false)
{
// The user specified an action so only show the usage for that action
continue;
}
if (string.IsNullOrWhiteSpace(action.Description) == false)
{
ret += "\n" + action.DefaultAlias + " - " + action.Description + "\n\n";
}
else
{
ret += "\n" + action.DefaultAlias + "\n\n";
}
foreach (var example in action.Examples)
{
ret += new ConsoleString() + " EXAMPLE: " + new ConsoleString(example.Example + "\n", ConsoleColor.Green) +
new ConsoleString(" " + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
ret += GetOptionsUsage(action.Arguments, false, options);
}
}
else
{
ret = ret.AppendUsingCurrentFormat(" options\n\n");
ret += GetOptionsUsage(definition.Arguments, false, options);
ret += "\n";
foreach (var example in definition.Examples)
{
ret += new ConsoleString() + " EXAMPLE: " + new ConsoleString(example.Example + "\n", ConsoleColor.Green) +
new ConsoleString(" " + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
}
return(ret);
}
public static ConsoleString GetStyledUsage <T>(string exeName = null, ArgUsageOptions options = null)
{
return(GetStyledUsage(typeof(T), exeName, options));
}
public static string GetUsage(CommandLineArgumentsDefinition definition, string exeName = null, ArgUsageOptions options = null)
{
return(GetStyledUsage(definition, exeName, options).ToString());
}
public static string GetUsage <T>(string exeName = null, ArgUsageOptions options = null)
{
return(GetStyledUsage <T>(exeName, options).ToString());
}
private static ConsoleString GetOptionsUsage(IEnumerable <PropertyInfo> opts, bool ignoreActionProperties, ArgUsageOptions options)
{
var usageInfos = opts.Select(o => new ArgumentUsageInfo(o));
var hasPositionalArgs = usageInfos.Where(i => i.Position >= 0).Count() > 0;
List <ConsoleString> columnHeaders = new List <ConsoleString>()
{
new ConsoleString("OPTION", ConsoleColor.Yellow),
new ConsoleString("DESCRIPTION", ConsoleColor.Yellow),
};
int insertPosition = 1;
if (options.ShowType)
{
columnHeaders.Insert(insertPosition++, new ConsoleString("TYPE", ConsoleColor.Yellow));
}
if (hasPositionalArgs && options.ShowPosition)
{
columnHeaders.Insert(insertPosition, new ConsoleString("POSITION", ConsoleColor.Yellow));
}
List <List <ConsoleString> > rows = new List <List <ConsoleString> >();
foreach (ArgumentUsageInfo usageInfo in usageInfos.OrderBy(i => i.Position >= 0 ? i.Position : 1000))
{
foreach (var hook in usageInfo.Property.GetUsageHooks())
{
hook.BeforeGenerateUsage(usageInfo);
}
if (usageInfo.Ignore)
{
continue;
}
if (usageInfo.IsAction && ignoreActionProperties)
{
continue;
}
if (usageInfo.IsActionArgs && ignoreActionProperties)
{
continue;
}
var positionString = new ConsoleString(usageInfo.Position >= 0 ? usageInfo.Position + "" : "NA");
var requiredString = new ConsoleString(usageInfo.IsRequired ? "*" : "", ConsoleColor.Red);
var descriptionString = new ConsoleString(usageInfo.Description);
var typeString = new ConsoleString(usageInfo.Type);
var indicator = "-";
rows.Add(new List <ConsoleString>()
{
new ConsoleString(indicator) + (usageInfo.Name + (usageInfo.Aliases.Count > 0 ? " (" + usageInfo.Aliases[0] + ")" : "")),
descriptionString,
});
insertPosition = 1;
if (options.ShowType)
{
rows.Last().Insert(insertPosition++, typeString + requiredString);
}
if (hasPositionalArgs && options.ShowPosition)
{
rows.Last().Insert(insertPosition, positionString);
}
for (int i = 1; i < usageInfo.Aliases.Count; i++)
{
rows.Add(new List <ConsoleString>()
{
new ConsoleString(" " + usageInfo.Aliases[i]),
ConsoleString.Empty,
ConsoleString.Empty,
});
if (hasPositionalArgs)
{
rows.Last().Insert(2, positionString);
}
}
}
return(FormatAsTable(columnHeaders, rows, " "));
}
/// <summary>
/// Generates color styled usage documentation for the given argument scaffold type.
/// </summary>
/// <typeparam name="T">Your custom argument scaffold type</typeparam>
/// <param name="exeName">The name of your program or null if you want PowerArgs to automatically detect it.</param>
/// <param name="options">Specify custom usage options</param>
/// <returns></returns>
public static ConsoleString GetStyledUsage <T>(string exeName = null, ArgUsageOptions options = null)
{
options = options ?? new ArgUsageOptions();
if (exeName == null)
{
var assembly = Assembly.GetEntryAssembly();
if (assembly == null)
{
throw new ArgException("PowerArgs could not determine the name of your executable automatically. This may happen if you run GetUsage<T>() from within unit tests. Use GetUsageT>(string exeName) in unit tests to avoid this exception.");
}
exeName = Path.GetFileNameWithoutExtension(Assembly.GetEntryAssembly().Location);
}
ConsoleString ret = new ConsoleString();
ret += new ConsoleString("Usage: " + exeName, ConsoleColor.Cyan);
var actionProperty = ArgAction.GetActionProperty <T>();
if (actionProperty != null)
{
ret.AppendUsingCurrentFormat(" <action> options\n\n");
foreach (var example in typeof(T).Attrs <ArgExample>())
{
ret += new ConsoleString("EXAMPLE: " + example.Example + "\n" + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
var global = GetOptionsUsage(typeof(T).GetProperties(BindingFlags.Instance | BindingFlags.Public), true, options);
if (string.IsNullOrEmpty(global.ToString()) == false)
{
ret += new ConsoleString("Global options:\n\n", ConsoleColor.Cyan) + global + "\n";
}
ret += "Actions:";
foreach (PropertyInfo prop in typeof(T).GetProperties(BindingFlags.Instance | BindingFlags.Public))
{
if (prop.IsActionArgProperty() == false)
{
continue;
}
var actionDescription = prop.HasAttr <ArgDescription>() ? " - " + prop.Attr <ArgDescription>().Description : "";
ret += "\n\n" + prop.GetArgumentName().Substring(0, prop.GetArgumentName().Length - Constants.ActionArgConventionSuffix.Length) + actionDescription + "\n\n";
foreach (var example in prop.Attrs <ArgExample>())
{
ret += new ConsoleString() + " EXAMPLE: " + new ConsoleString(example.Example + "\n", ConsoleColor.Green) +
new ConsoleString(" " + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
ret += GetOptionsUsage(prop.PropertyType.GetProperties(BindingFlags.Instance | BindingFlags.Public), false, options);
}
}
else
{
ret.AppendUsingCurrentFormat(" options\n\n");
ret += GetOptionsUsage(typeof(T).GetProperties(BindingFlags.Instance | BindingFlags.Public), false, options);
ret += "\n";
foreach (var example in typeof(T).Attrs <ArgExample>())
{
ret += new ConsoleString() + " EXAMPLE: " + new ConsoleString(example.Example + "\n", ConsoleColor.Green) +
new ConsoleString(" " + example.Description + "\n\n", ConsoleColor.DarkGreen);
}
}
return(ret);
}
