HelpText.cs

Go to the documentation of this file.

// Copyright 2005-2015 Giacomo Stelluti Scala & Contributors. All rights reserved. See License.md in the project root for license information.
 
using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Text;
 
using CommandLine.Core;
using CommandLine.Infrastructure;
 
using CSharpx;
 
namespace CommandLine.Text
{
    public struct ComparableOption
    {
        public bool Required;
        public bool IsOption;
        public bool IsValue;
        public string LongName;
        public string ShortName;
        public int Index;
    }
 
    public class HelpText
    {
        private const int BuilderCapacity = 128;
        private const int DefaultMaximumLength = 80; // default console width
 
        private const int OptionToHelpTextSeparatorWidth = 4;
 
        private const int OptionPrefixWidth = 2;
 
        private const int TotalOptionPadding = OptionToHelpTextSeparatorWidth + OptionPrefixWidth;
 
        private readonly StringBuilder postOptionsHelp;
        private readonly StringBuilder preOptionsHelp;
        private string copyright;
        private string heading;
        private StringBuilder optionsHelp;
 
        public HelpText()
            : this(SentenceBuilder.Create(), string.Empty, string.Empty) { }
 
        public HelpText(SentenceBuilder sentenceBuilder)
            : this(sentenceBuilder, string.Empty, string.Empty) { }
 
        public HelpText(string heading)
            : this(SentenceBuilder.Create(), heading, string.Empty) { }
 
        public HelpText(SentenceBuilder sentenceBuilder, string heading)
            : this(sentenceBuilder, heading, string.Empty) { }
 
        public HelpText(string heading, string copyright)
            : this(SentenceBuilder.Create(), heading, copyright) { }
 
        public HelpText(SentenceBuilder sentenceBuilder, string heading, string copyright)
        {
            if (sentenceBuilder == null)
            {
                throw new ArgumentNullException("sentenceBuilder");
            }
 
            if (heading == null)
            {
                throw new ArgumentNullException("heading");
            }
 
            if (copyright == null)
            {
                throw new ArgumentNullException("copyright");
            }
 
            preOptionsHelp = new StringBuilder(BuilderCapacity);
            postOptionsHelp = new StringBuilder(BuilderCapacity);
 
            try
            {
                MaximumDisplayWidth = Console.WindowWidth;
 
                if (MaximumDisplayWidth < 1)
                {
                    MaximumDisplayWidth = DefaultMaximumLength;
                }
            }
            catch (IOException)
            {
                MaximumDisplayWidth = DefaultMaximumLength;
            }
 
            SentenceBuilder = sentenceBuilder;
            this.heading = heading;
            this.copyright = copyright;
            AutoHelp = true;
            AutoVersion = true;
        }
 
        public string Heading
        {
            get => heading;
            set
            {
                if (value == null)
                {
                    throw new ArgumentNullException("value");
                }
 
                heading = value;
            }
        }
 
        public string Copyright
        {
            get => copyright;
            set
            {
                if (value == null)
                {
                    throw new ArgumentNullException("value");
                }
 
                copyright = value;
            }
        }
 
        public int MaximumDisplayWidth { get; set; }
 
        public bool AddDashesToOption { get; set; }
 
        public bool AdditionalNewLineAfterOption { get; set; }
 
        public bool AddNewLineBetweenHelpSections { get; set; }
 
        public bool AddEnumValuesToHelpText { get; set; }
 
        public bool AutoHelp { get; set; }
 
        public bool AutoVersion { get; set; }
 
        public SentenceBuilder SentenceBuilder { get; }
 
        public static HelpText AutoBuild<T>(ParserResult<T> parserResult,
                                            Func<HelpText, HelpText> onError,
                                            Func<Example, Example> onExample,
                                            bool verbsIndex = false,
                                            int maxDisplayWidth = DefaultMaximumLength)
        {
            HelpText auto = new HelpText
            {
                Heading = HeadingInfo.Empty,
                Copyright = CopyrightInfo.Empty,
                AdditionalNewLineAfterOption = true,
                AddDashesToOption = !verbsIndex,
                MaximumDisplayWidth = maxDisplayWidth,
            };
 
            try
            {
                auto.Heading = HeadingInfo.Default;
                auto.Copyright = CopyrightInfo.Default;
            }
            catch (Exception)
            {
                auto = onError(auto);
            }
 
            IEnumerable<Error> errors = Enumerable.Empty<Error>();
 
            if (onError != null && parserResult.Tag == ParserResultType.NotParsed)
            {
                errors = ((NotParsed<T>)parserResult).Errors;
 
                if (errors.IsHelp() ||
                    errors.OnlyMeaningfulOnes()
                          .Any())
                {
                    auto = onError(auto);
                }
            }
 
            ReflectionHelper.GetAttribute<AssemblyLicenseAttribute>()
                            .Do(license => license.AddToHelpText(auto, true));
 
            Maybe<AssemblyUsageAttribute> usageAttr = ReflectionHelper.GetAttribute<AssemblyUsageAttribute>();
 
            Maybe<IEnumerable<string>> usageLines = RenderUsageTextAsLines(parserResult, onExample)
                .ToMaybe();
 
            if (usageAttr.IsJust() || usageLines.IsJust())
            {
                string heading = auto.SentenceBuilder.UsageHeadingText();
 
                if (heading.Length > 0)
                {
                    if (auto.AddNewLineBetweenHelpSections)
                    {
                        heading = Environment.NewLine + heading;
                    }
 
                    auto.AddPreOptionsLine(heading);
                }
            }
 
            usageAttr.Do(usage => usage.AddToHelpText(auto, true));
 
            usageLines.Do(lines => auto.AddPreOptionsLines(lines));
 
            if ((verbsIndex && parserResult.TypeInfo.Choices.Any()) ||
                errors.Any(e => e.Tag == ErrorType.NoVerbSelectedError))
            {
                auto.AddDashesToOption = false;
                auto.AddVerbs(parserResult.TypeInfo.Choices.ToArray());
            }
            else
            {
                auto.AddOptions(parserResult);
            }
 
            return auto;
        }
 
        public static HelpText AutoBuild<T>(ParserResult<T> parserResult, int maxDisplayWidth = DefaultMaximumLength)
        {
            return AutoBuild(parserResult, h => h, maxDisplayWidth);
        }
 
        public static HelpText AutoBuild<T>(ParserResult<T> parserResult,
                                            Func<HelpText, HelpText> onError,
                                            int maxDisplayWidth = DefaultMaximumLength)
        {
            if (parserResult.Tag != ParserResultType.NotParsed)
            {
                throw new ArgumentException("Excepting NotParsed<T> type.", "parserResult");
            }
 
            IEnumerable<Error> errors = ((NotParsed<T>)parserResult).Errors;
 
            if (errors.Any(e => e.Tag == ErrorType.VersionRequestedError))
            {
                return new HelpText($"{HeadingInfo.Default}{Environment.NewLine}")
                {
                    MaximumDisplayWidth = maxDisplayWidth,
                }.AddPreOptionsLine(Environment.NewLine);
            }
 
            if (!errors.Any(e => e.Tag == ErrorType.HelpVerbRequestedError))
            {
                return AutoBuild(parserResult,
                                 current =>
                                 {
                                     onError?.Invoke(current);
 
                                     return DefaultParsingErrorsHandler(parserResult, current);
                                 },
                                 e => e,
                                 maxDisplayWidth: maxDisplayWidth
                                );
            }
 
            HelpVerbRequestedError err = errors.OfType<HelpVerbRequestedError>()
                                               .Single();
 
            NotParsed<object> pr = new NotParsed<object>(TypeInfo.Create(err.Type),
                                                         new Error[] { err }
                                                        );
 
            return err.Matched
                       ? AutoBuild(pr,
                                   current =>
                                   {
                                       onError?.Invoke(current);
 
                                       return DefaultParsingErrorsHandler(pr, current);
                                   },
                                   e => e,
                                   maxDisplayWidth: maxDisplayWidth
                                  )
                       : AutoBuild(parserResult,
                                   current =>
                                   {
                                       onError?.Invoke(current);
 
                                       return DefaultParsingErrorsHandler(parserResult, current);
                                   },
                                   e => e,
                                   true,
                                   maxDisplayWidth
                                  );
        }
 
        public static HelpText DefaultParsingErrorsHandler<T>(ParserResult<T> parserResult, HelpText current)
        {
            if (parserResult == null)
            {
                throw new ArgumentNullException("parserResult");
            }
 
            if (current == null)
            {
                throw new ArgumentNullException("current");
            }
 
            if (((NotParsed<T>)parserResult).Errors.OnlyMeaningfulOnes()
                                            .Empty())
            {
                return current;
            }
 
            IEnumerable<string> errors = RenderParsingErrorsTextAsLines(parserResult,
                                                                        current.SentenceBuilder.FormatError,
                                                                        current.SentenceBuilder
                                                                               .FormatMutuallyExclusiveSetErrors,
                                                                        2
                                                                       ); // indent with two spaces
 
            if (errors.Empty())
            {
                return current;
            }
 
            return current
                   .AddPreOptionsLine(string.Concat(Environment.NewLine, current.SentenceBuilder.ErrorsHeadingText()))
                   .AddPreOptionsLines(errors);
        }
 
        public static implicit operator string(HelpText info)
        {
            return info.ToString();
        }
 
        public HelpText AddPreOptionsLine(string value)
        {
            return AddPreOptionsLine(value, MaximumDisplayWidth);
        }
 
        public HelpText AddPostOptionsLine(string value)
        {
            return AddLine(postOptionsHelp, value);
        }
 
        public HelpText AddPreOptionsLines(IEnumerable<string> lines)
        {
            lines.ForEach(line => AddPreOptionsLine(line));
 
            return this;
        }
 
        public HelpText AddPostOptionsLines(IEnumerable<string> lines)
        {
            lines.ForEach(line => AddPostOptionsLine(line));
 
            return this;
        }
 
        public HelpText AddPreOptionsText(string text)
        {
            string[] lines = text.Split(new[] { Environment.NewLine },
                                        StringSplitOptions.None
                                       );
            lines.ForEach(line => AddPreOptionsLine(line));
 
            return this;
        }
 
        public HelpText AddPostOptionsText(string text)
        {
            string[] lines = text.Split(new[] { Environment.NewLine },
                                        StringSplitOptions.None
                                       );
            lines.ForEach(line => AddPostOptionsLine(line));
 
            return this;
        }
 
        public HelpText AddOptions<T>(ParserResult<T> result)
        {
            if (result == null)
            {
                throw new ArgumentNullException("result");
            }
 
            return AddOptionsImpl(GetSpecificationsFromType(result.TypeInfo.Current),
                                  SentenceBuilder.RequiredWord(),
                                  SentenceBuilder.OptionGroupWord(),
                                  MaximumDisplayWidth
                                 );
        }
 
        public HelpText AddVerbs(params Type[] types)
        {
            if (types == null)
            {
                throw new ArgumentNullException("types");
            }
 
            if (types.Length == 0)
            {
                throw new ArgumentOutOfRangeException("types");
            }
 
            return AddOptionsImpl(AdaptVerbsToSpecifications(types),
                                  SentenceBuilder.RequiredWord(),
                                  SentenceBuilder.OptionGroupWord(),
                                  MaximumDisplayWidth
                                 );
        }
 
        public HelpText AddOptions<T>(int maximumLength, ParserResult<T> result)
        {
            if (result == null)
            {
                throw new ArgumentNullException("result");
            }
 
            return AddOptionsImpl(GetSpecificationsFromType(result.TypeInfo.Current),
                                  SentenceBuilder.RequiredWord(),
                                  SentenceBuilder.OptionGroupWord(),
                                  maximumLength
                                 );
        }
 
        public HelpText AddVerbs(int maximumLength, params Type[] types)
        {
            if (types == null)
            {
                throw new ArgumentNullException("types");
            }
 
            if (types.Length == 0)
            {
                throw new ArgumentOutOfRangeException("types");
            }
 
            return AddOptionsImpl(AdaptVerbsToSpecifications(types),
                                  SentenceBuilder.RequiredWord(),
                                  SentenceBuilder.OptionGroupWord(),
                                  maximumLength
                                 );
        }
 
        public static string RenderParsingErrorsText<T>(ParserResult<T> parserResult,
                                                        Func<Error, string> formatError,
                                                        Func<IEnumerable<MutuallyExclusiveSetError>, string>
                                                            formatMutuallyExclusiveSetErrors,
                                                        int indent)
        {
            return string.Join(Environment.NewLine,
                               RenderParsingErrorsTextAsLines(parserResult,
                                                              formatError,
                                                              formatMutuallyExclusiveSetErrors,
                                                              indent
                                                             )
                              );
        }
 
        public static IEnumerable<string> RenderParsingErrorsTextAsLines<T>(ParserResult<T> parserResult,
                                                                            Func<Error, string> formatError,
                                                                            Func<IEnumerable<MutuallyExclusiveSetError>,
                                                                                    string>
                                                                                formatMutuallyExclusiveSetErrors,
                                                                            int indent)
        {
            if (parserResult == null)
            {
                throw new ArgumentNullException("parserResult");
            }
 
            IEnumerable<Error> meaningfulErrors =
                ((NotParsed<T>)parserResult).Errors.OnlyMeaningfulOnes();
 
            if (meaningfulErrors.Empty())
            {
                yield break;
            }
 
            foreach (Error error in meaningfulErrors
                         .Where(e => e.Tag != ErrorType.MutuallyExclusiveSetError))
            {
                StringBuilder line = new StringBuilder(indent.Spaces())
                    .Append(formatError(error));
 
                yield return line.ToString();
            }
 
            string mutuallyErrs =
                formatMutuallyExclusiveSetErrors(meaningfulErrors.OfType<MutuallyExclusiveSetError>());
 
            if (mutuallyErrs.Length > 0)
            {
                string[] lines = mutuallyErrs
                    .Split(new[] { Environment.NewLine },
                           StringSplitOptions.None
                          );
 
                foreach (string line in lines)
                {
                    yield return line;
                }
            }
        }
 
        public static string RenderUsageText<T>(ParserResult<T> parserResult)
        {
            return RenderUsageText(parserResult, example => example);
        }
 
        public static string RenderUsageText<T>(ParserResult<T> parserResult, Func<Example, Example> mapperFunc)
        {
            return string.Join(Environment.NewLine, RenderUsageTextAsLines(parserResult, mapperFunc));
        }
 
        public static IEnumerable<string> RenderUsageTextAsLines<T>(ParserResult<T> parserResult,
                                                                    Func<Example, Example> mapperFunc)
        {
            if (parserResult == null)
            {
                throw new ArgumentNullException("parserResult");
            }
 
            Maybe<Tuple<UsageAttribute, IEnumerable<Example>>> usage = GetUsageFromType(parserResult.TypeInfo.Current);
 
            if (usage.MatchNothing())
            {
                yield break;
            }
 
            Tuple<UsageAttribute, IEnumerable<Example>> usageTuple = usage.FromJustOrFail();
            IEnumerable<Example> examples = usageTuple.Item2;
            string appAlias = usageTuple.Item1.ApplicationAlias ?? ReflectionHelper.GetAssemblyName();
 
            foreach (Example e in examples)
            {
                Example example = mapperFunc(e);
 
                StringBuilder exampleText = new StringBuilder(example.HelpText)
                    .Append(':');
 
                yield return exampleText.ToString();
                IEnumerable<UnParserSettings> styles = example.GetFormatStylesOrDefault();
 
                foreach (UnParserSettings s in styles)
                {
                    StringBuilder commandLine = new StringBuilder(OptionPrefixWidth.Spaces())
                                                .Append(appAlias)
                                                .Append(' ')
                                                .Append(Parser.Default.FormatCommandLine(example.Sample,
                                                             config =>
                                                             {
                                                                 config.PreferShortName = s.PreferShortName;
                                                                 config.GroupSwitches = s.GroupSwitches;
                                                                 config.UseEqualToken = s.UseEqualToken;
                                                                 config.SkipDefault = s.SkipDefault;
                                                             }
                                                            )
                                                       );
 
                    yield return commandLine.ToString();
                }
            }
        }
 
        public override string ToString()
        {
            const int ExtraLength = 10;
 
            int sbLength = heading.SafeLength() +
                           copyright.SafeLength() +
                           preOptionsHelp.SafeLength() +
                           optionsHelp.SafeLength() +
                           postOptionsHelp.SafeLength() +
                           ExtraLength;
            StringBuilder result = new StringBuilder(sbLength);
 
            result.Append(heading)
                  .AppendWhen(!string.IsNullOrEmpty(copyright),
                              Environment.NewLine,
                              copyright
                             )
                  .AppendWhen(preOptionsHelp.SafeLength() > 0,
                              NewLineIfNeededBefore(preOptionsHelp),
                              Environment.NewLine,
                              preOptionsHelp.ToString()
                             )
                  .AppendWhen(optionsHelp.SafeLength() > 0,
                              Environment.NewLine,
                              Environment.NewLine,
                              optionsHelp.SafeToString()
                             )
                  .AppendWhen(postOptionsHelp.SafeLength() > 0,
                              NewLineIfNeededBefore(postOptionsHelp),
                              Environment.NewLine,
                              postOptionsHelp.ToString()
                             );
 
            string NewLineIfNeededBefore(StringBuilder sb)
            {
                if (AddNewLineBetweenHelpSections &&
                    result.Length > 0 &&
                    !result.SafeEndsWith(Environment.NewLine) &&
                    !sb.SafeStartsWith(Environment.NewLine))
                {
                    return Environment.NewLine;
                }
 
                return null;
            }
 
            return result.ToString();
        }
 
        internal static void AddLine(StringBuilder builder, string value, int maximumLength)
        {
            if (builder == null)
            {
                throw new ArgumentNullException(nameof(builder));
            }
 
            if (value == null)
            {
                throw new ArgumentNullException(nameof(value));
            }
 
            if (maximumLength < 1)
            {
                throw new ArgumentOutOfRangeException(nameof(value));
            }
 
            value = value.TrimEnd();
 
            builder.AppendWhen(builder.Length > 0, Environment.NewLine);
            builder.Append(TextWrapper.WrapAndIndentText(value, 0, maximumLength));
        }
 
        private IEnumerable<Specification> GetSpecificationsFromType(Type type)
        {
            IEnumerable<Specification> specs = type.GetSpecifications(Specification.FromProperty);
 
            IEnumerable<OptionSpecification> optionSpecs = specs
                .OfType<OptionSpecification>();
 
            if (AutoHelp)
            {
                optionSpecs = optionSpecs.Concat(new[] { MakeHelpEntry() });
            }
 
            if (AutoVersion)
            {
                optionSpecs = optionSpecs.Concat(new[] { MakeVersionEntry() });
            }
 
            IOrderedEnumerable<ValueSpecification> valueSpecs = specs
                                                                .OfType<ValueSpecification>()
                                                                .OrderBy(v => v.Index);
 
            return Enumerable.Empty<Specification>()
                             .Concat(optionSpecs)
                             .Concat(valueSpecs);
        }
 
        private static Maybe<Tuple<UsageAttribute, IEnumerable<Example>>> GetUsageFromType(Type type)
        {
            return type.GetUsageData()
                       .Map(tuple =>
                            {
                                PropertyInfo prop = tuple.Item1;
                                UsageAttribute attr = tuple.Item2;
 
                                IEnumerable<Example> examples = (IEnumerable<Example>)prop
                                    .GetValue(null,
                                              BindingFlags.Public | BindingFlags.Static | BindingFlags.GetProperty,
                                              null,
                                              null,
                                              null
                                             );
 
                                return Tuple.Create(attr, examples);
                            }
                           );
        }
 
        private IEnumerable<Specification> AdaptVerbsToSpecifications(IEnumerable<Type> types)
        {
            IEnumerable<OptionSpecification> optionSpecs = from verbTuple in Verb.SelectFromTypes(types)
                                                           select
                                                               OptionSpecification.NewSwitch(string.Empty,
                                                                    verbTuple.Item1.Name.Concat(verbTuple.Item1.Aliases)
                                                                             .ToDelimitedString(", "),
                                                                    false,
                                                                    verbTuple.Item1.IsDefault
                                                                        ? "(Default Verb) " + verbTuple.Item1.HelpText
                                                                        : verbTuple.Item1.HelpText, //Default verb
                                                                    string.Empty,
                                                                    verbTuple.Item1.Hidden
                                                                   );
 
            if (AutoHelp)
            {
                optionSpecs = optionSpecs.Concat(new[] { MakeHelpEntry() });
            }
 
            if (AutoVersion)
            {
                optionSpecs = optionSpecs.Concat(new[] { MakeVersionEntry() });
            }
 
            return optionSpecs;
        }
 
        private HelpText AddOptionsImpl(IEnumerable<Specification> specifications,
                                        string requiredWord,
                                        string optionGroupWord,
                                        int maximumLength)
        {
            int maxLength = GetMaxLength(specifications);
 
            optionsHelp = new StringBuilder(BuilderCapacity);
 
            int remainingSpace = maximumLength - (maxLength + TotalOptionPadding);
 
            if (OptionComparison != null)
            {
                int i = -1;
 
                List<ComparableOption> comparables = specifications.ToList()
                                                                   .Select(s =>
                                                                           {
                                                                               i++;
 
                                                                               return ToComparableOption(s, i);
                                                                           }
                                                                          )
                                                                   .ToList();
                comparables.Sort(OptionComparison);
 
                foreach (ComparableOption comparable in comparables)
                {
                    Specification spec = specifications.ElementAt(comparable.Index);
                    AddOption(requiredWord, optionGroupWord, maxLength, spec, remainingSpace);
                }
            }
            else
            {
                specifications.ForEach(option =>
                                           AddOption(requiredWord, optionGroupWord, maxLength, option, remainingSpace)
                                      );
            }
 
            return this;
        }
 
        private OptionSpecification MakeHelpEntry()
        {
            return OptionSpecification.NewSwitch(string.Empty,
                                                 "help",
                                                 false,
                                                 SentenceBuilder.HelpCommandText(AddDashesToOption),
                                                 string.Empty
                                                );
        }
 
        private OptionSpecification MakeVersionEntry()
        {
            return OptionSpecification.NewSwitch(string.Empty,
                                                 "version",
                                                 false,
                                                 SentenceBuilder.VersionCommandText(AddDashesToOption),
                                                 string.Empty
                                                );
        }
 
        private HelpText AddPreOptionsLine(string value, int maximumLength)
        {
            AddLine(preOptionsHelp, value, maximumLength);
 
            return this;
        }
 
        private HelpText AddOption(string requiredWord,
                                   string optionGroupWord,
                                   int maxLength,
                                   Specification specification,
                                   int widthOfHelpText)
        {
            OptionSpecification GetOptionGroupSpecification()
            {
                if (specification.Tag == SpecificationType.Option &&
                    specification is OptionSpecification optionSpecification &&
                    optionSpecification.Group.Length > 0
                   )
 
                {
                    return optionSpecification;
                }
 
                return null;
            }
 
            if (specification.Hidden)
            {
                return this;
            }
 
            optionsHelp.Append("  ");
 
            StringBuilder name = new StringBuilder(maxLength)
                .BimapIf(specification.Tag == SpecificationType.Option,
                         it => it.Append(AddOptionName(maxLength, (OptionSpecification)specification)),
                         it => it.Append(AddValueName(maxLength, (ValueSpecification)specification))
                        );
 
            optionsHelp
                .Append(name.Length < maxLength
                            ? name.ToString()
                                  .PadRight(maxLength)
                            : name.ToString()
                       )
                .Append(OptionToHelpTextSeparatorWidth.Spaces());
 
            string optionHelpText = specification.HelpText;
 
            if (AddEnumValuesToHelpText && specification.EnumValues.Any())
            {
                optionHelpText += " Valid values: " + string.Join(", ", specification.EnumValues);
            }
 
            specification.DefaultValue.Do(defaultValue =>
                                              optionHelpText =
                                                  "(Default: {0}) ".FormatInvariant(FormatDefaultValue(defaultValue)) +
                                                  optionHelpText
                                         );
 
            OptionSpecification optionGroupSpecification = GetOptionGroupSpecification();
 
            if (specification.Required && optionGroupSpecification == null)
            {
                optionHelpText = "{0} ".FormatInvariant(requiredWord) + optionHelpText;
            }
 
            if (optionGroupSpecification != null)
            {
                optionHelpText = "({0}: {1}) ".FormatInvariant(optionGroupWord, optionGroupSpecification.Group) +
                                 optionHelpText;
            }
 
            //note that we need to indent trim the start of the string because it's going to be 
            //appended to an existing line that is as long as the indent-level
            string indented = TextWrapper
                              .WrapAndIndentText(optionHelpText, maxLength + TotalOptionPadding, widthOfHelpText)
                              .TrimStart();
 
            optionsHelp
                .Append(indented)
                .Append(Environment.NewLine)
                .AppendWhen(AdditionalNewLineAfterOption, Environment.NewLine);
 
            return this;
        }
 
        private string AddOptionName(int maxLength, OptionSpecification specification)
        {
            return
                new StringBuilder(maxLength)
                    .MapIf(specification.ShortName.Length > 0,
                           it => it
                                 .AppendWhen(AddDashesToOption, '-')
                                 .AppendFormat("{0}", specification.ShortName)
                                 .AppendFormatWhen(specification.MetaValue.Length > 0, " {0}", specification.MetaValue)
                                 .AppendWhen(specification.LongName.Length > 0, ", ")
                          )
                    .MapIf(specification.LongName.Length > 0,
                           it => it
                                 .AppendWhen(AddDashesToOption, "--")
                                 .AppendFormat("{0}", specification.LongName)
                                 .AppendFormatWhen(specification.MetaValue.Length > 0, "={0}", specification.MetaValue)
                          )
                    .ToString();
        }
 
        private string AddValueName(int maxLength, ValueSpecification specification)
        {
            return new StringBuilder(maxLength)
                   .BimapIf(specification.MetaName.Length > 0,
                            it => it.AppendFormat("{0} (pos. {1})", specification.MetaName, specification.Index),
                            it => it.AppendFormat("value pos. {0}", specification.Index)
                           )
                   .AppendFormatWhen(specification.MetaValue.Length > 0,
                                     " {0}",
                                     specification.MetaValue
                                    )
                   .ToString();
        }
 
        private HelpText AddLine(StringBuilder builder, string value)
        {
            AddLine(builder, value, MaximumDisplayWidth);
 
            return this;
        }
 
        private int GetMaxLength(IEnumerable<Specification> specifications)
        {
            return specifications.Aggregate(0,
                                            (length, spec) =>
                                            {
                                                if (spec.Hidden)
                                                {
                                                    return length;
                                                }
 
                                                int specLength = spec.Tag == SpecificationType.Option
                                                                     ? GetMaxOptionLength((OptionSpecification)spec)
                                                                     : GetMaxValueLength((ValueSpecification)spec);
 
                                                return Math.Max(length, specLength);
                                            }
                                           );
        }
 
 
        private int GetMaxOptionLength(OptionSpecification spec)
        {
            int specLength = 0;
 
            bool hasShort = spec.ShortName.Length > 0;
            bool hasLong = spec.LongName.Length > 0;
 
            int metaLength = 0;
 
            if (spec.MetaValue.Length > 0)
            {
                metaLength = spec.MetaValue.Length + 1;
            }
 
            if (hasShort)
            {
                ++specLength;
 
                if (AddDashesToOption)
                {
                    ++specLength;
                }
 
                specLength += metaLength;
            }
 
            if (hasLong)
            {
                specLength += spec.LongName.Length;
 
                if (AddDashesToOption)
                {
                    specLength += OptionPrefixWidth;
                }
 
                specLength += metaLength;
            }
 
            if (hasShort && hasLong)
            {
                specLength += OptionPrefixWidth;
            }
 
            return specLength;
        }
 
        private int GetMaxValueLength(ValueSpecification spec)
        {
            int specLength = 0;
 
            bool hasMeta = spec.MetaName.Length > 0;
 
            int metaLength = 0;
 
            if (spec.MetaValue.Length > 0)
            {
                metaLength = spec.MetaValue.Length + 1;
            }
 
            if (hasMeta)
            {
                specLength += spec.MetaName.Length +
                              spec.Index.ToStringInvariant()
                                  .Length +
                              8; //METANAME (pos. N)
            }
            else
            {
                specLength += spec.Index.ToStringInvariant()
                                  .Length +
                              11; // "value pos. N"
            }
 
            specLength += metaLength;
 
            return specLength;
        }
 
        private static string FormatDefaultValue<T>(T value)
        {
            if (value is bool)
            {
                return value.ToStringLocal()
                            .ToLowerInvariant();
            }
 
            if (value is string)
            {
                return value.ToStringLocal();
            }
 
            IEnumerable asEnumerable = value as IEnumerable;
 
            if (asEnumerable == null)
            {
                return value.ToStringLocal();
            }
 
            StringBuilder builder = new StringBuilder();
 
            foreach (object item in asEnumerable)
            {
                builder
                    .Append(item.ToStringLocal())
                    .Append(" ");
            }
 
            return builder.Length > 0
                       ? builder.ToString(0, builder.Length - 1)
                       : string.Empty;
        }
 
#region ordering
 
        private ComparableOption ToComparableOption(Specification spec, int index)
        {
            OptionSpecification option = spec as OptionSpecification;
            ValueSpecification value = spec as ValueSpecification;
            bool required = option?.Required ?? false;
 
            return new ComparableOption
            {
                Required = required,
                IsOption = option != null,
                IsValue = value != null,
                LongName = option?.LongName ?? value?.MetaName,
                ShortName = option?.ShortName,
                Index = index,
            };
        }
 
 
        public Comparison<ComparableOption> OptionComparison { get; set; } = null;
 
        public static Comparison<ComparableOption> RequiredThenAlphaComparison = (attr1, attr2) =>
        {
            if (attr1.IsOption && attr2.IsOption)
            {
                if (attr1.Required && !attr2.Required)
                {
                    return -1;
                }
 
                if (!attr1.Required && attr2.Required)
                {
                    return 1;
                }
 
                return string.Compare(attr1.LongName, attr2.LongName, StringComparison.Ordinal);
            }
 
            if (attr1.IsOption && attr2.IsValue)
            {
                return -1;
            }
 
            return 1;
        };
 
#endregion
    }
}