FormatAsColumns 1.0.0

FormatAsColumns provides easy-to-use tools for formatting strings for output within a fixed amount of horizontal space. Unlike most other tools for rendering columnar data, this one performs tidy text wrapping within a column. See examples below.

Install this nuget package and put the following code at the top of your class in order to use it:

using DTS.FormatAsColumns;

Example 1 -- Render parameter descriptions

Code

// Here's some command-line parameter information we want to render, containing a switch, name, and description.
var argDocumentation = new List<object>
{
    new List<object> { "o", "optimize", "Iku noci rete hamen ni, bona itani ne sun, tonni berogin hin co." },
    new List<object> { "b", "blah", "Lorem ipsum dolor sit amet, sanctus legendos disputando ut quo." },
    new List<object> { "foo", "foobar", "Here is a description for this command-line parameter." }
};

// Configure a new ColumnLayout object for displaying the above data.
var cl = new ColumnLayout()
    .Indent(4)                          // indents the whole layout 4 spaces
    .ValueCol(5, Align.Right, "-{0}:")  // 'switch' will render in this column (5 chars wide, right aligned, and using the given format)
    .DividerCol("   ")
    .ValueCol(10)                       // 'name' will render in this column (10 chars wide, left-aligned)
    .DividerCol("   ")
    .ValueCol(40)                       // 'description' will render in this column (40 chars wide, left-aligned)
    .Capture(Console.WriteLine);        // Tells all Format* methods to call the Console.WriteLine method when generating output

// Write it all out.
Console.WriteLine("PARAMETERS:\r\n");
foreach (List<object> arg in argDocumentation)
{
    cl.Format(arg);    // This applies the layout above to the provided data
    cl.FormatEmpty();
};

Output

PARAMETERS:

      -o:   optimize     Iku noci rete hamen ni, bona itani ne
                         sun, tonni berogin hin co.

      -b:   blah         Lorem ipsum dolor sit amet, sanctus
                         legendos disputando ut quo.

    -foo:   foobar       Here is a description for this
                         command-line parameter.

Example2 -- Render a table with arbitrary data & dividers

Code

var left = "This block of text is left justified within a 20 character space.  Note also the 3 character indent for the whole layout.";
var right = "This text is right justified within a 10 character space.";
var centered = "This text is centered within its alotted space.";
var number = 500.123456;
var otherInfo = "<-- Numbers format like you would expect.\r\n\r\nNote carriage returns within a string are preserved.";

var cl1 = new ColumnLayout()
    .Indent(3)                                  // Indents the entire layout 3 space
    .DividerCol("|")
    .ValueCol(20, Align.Left)
    .DividerCol(" |~| ")
    .ValueCol(10, Align.Center)
    .DividerCol(" | ")
    .ValueCol(10, Align.Right)
    .ValueCol(10, Align.Right, "{0:C}")
    .DividerCol("  ")
    .ValueCol(14, Align.Right)
    .DividerCol(" |")
    .Capture(Console.WriteLine);               // Tells all Format* methods to call the Console.WriteLine method when generating output

cl1.Format("Header1", "Header2", "Header3", "Header4");
cl1.FormatHorizontalDivider("=-");
cl1.Format(left, centered, right, number, otherInfo);
cl1.FormatHorizontalDivider("+--");

Output

   |Header1              |~|  Header2   |    Header3   Header4                 |
   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   |This block of text   |~| This text  |  This text   $500.12     <-- Numbers |
   |is left justified    |~|     is     |   is right               format like |
   |within a 20          |~|  centered  |  justified                 you would |
   |character space.     |~| within its |   within a                   expect. |
   |Note also the 3      |~|  alotted   |         10                           |
   |character indent for |~|   space.   |  character             Note carriage |
   |the whole layout.    |~|            |     space.            returns within |
   |                     |~|            |                         a string are |
   |                     |~|            |                           preserved. |
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+-

Example 3 -- Extension methods -- SplitForWidth() and Combine()

Code

// Here's a really long strong we want to display nicely.
var text1 =
    $"The {nameof(StringExtensions.SplitForWidth)}() string extension method splits text into a IEnumerable<string>"
         + " such that each element fits within the specified horizontal space."
         + $"  No alignment features are provided.  Use the {nameof(ColumnLayout)} class for that."
         + $"\r\n\r\nThe {nameof(StringExtensions.Combine)}() extension method combines"
         + $" an IEnumerable<string> into a single string.";

// Here SplitForWidth() splits our long string it into 50 character chunks to give us an
// IEnumerable<string> of lines.  Then Combine() joins all the elements together using
// Environment.NewLine character as the delimiter.
Console.WriteLine(
    text1
    .SplitForWidth(50)
    .Combine());

Console.WriteLine();
Console.WriteLine();
Console.WriteLine("-----------------");

// Here is the same output, but overriding the default delimiter with <br>.
Console.WriteLine(
    text1
    .SplitForWidth(50)
    .Combine("<br>"));

Output

The SplitForWidth() string extension method splits
text into a IEnumerable<string> such that each
element fits within the specified horizontal
space.  No alignment features are provided.  Use
the ColumnLayout class for that.

The Combine() extension method combines an
IEnumerable<string> into a single string.

-----------------
The SplitForWidth() string extension method splits<br>text into a IEnumerable<string> such that each<br>element fits within the specified horizontal<br>space.  No alignment features are provided.  Use<br>the ColumnLayout class for that.<br><br>The Combine() extension method combines an<br>IEnumerable<string> into a single string.