[Contents]

## `output::asciiArt` -- A domain for 2D ascii art graphics

#### Introduction

This domain allows for creating 2D ascii art graphics, which can be displayed by the text pretty-printer of MuPAD.

#### Details

- A graphic `g` consists of a rectangle of characters, where the bottom left corner has coordinates `[1,1]`, and the upper right corner has coordinates `[g::dom::width(g),g::dom::height(g)]`.

- With MuPAD up to version 2.5.3, an element of this domain is aligned vertically on its topmost row.

- Starting from MuPAD 3.0.0, an element of this domain is centered vertically by default. Furthermore, you can choose the alignment style between Bottom, Center, Top, or set the baseline explicitly, as a number in the range `[1..g::dom::height(g)]`. Setting a baseline of 1 has the same effect as choosing the style Bottom.

- Internally, the first operand of an element of this domain is a list of strings of same lengths. The character of coordinate `[x,y]` is stored in the `x`-th character of the `y`-th string. The second operand describes the alignment style.

#### Creating Elements

`output::asciiArt(list)`

#### Parameters

`list` | - | A list of strings.

#### Details

- Construct a graphic by stacking vertically the strings in `list`, ragged left, from bottom to top (and not from top to bottom, in order to be consistent with the orientation of the y axis).

#### Method fromArray: boxed cell graphic from 2D array

- `fromArray(2D array a)`

- Constructs a graphic made of vertically and horizontally aligned boxed cells filled with the initialized values of the array. Currently, the values themselves are represented in 1D and not pretty printed.

#### Method width: width of a graphic

- `width(graphic g)`

- Returns the width of `g` in characters.

#### Method height: height of a graphic

- `height(graphic g)`

- Returns the height of `g` in characters.

#### Method alignment: vertical alignment

- `alignment(graphic g)`

- Returns the vertical alignment style or base line of `g`.

#### Method setAlignment: sets the vertical alignment

- `setAlignment(graphic g, style align)`

- Returns a copy of `g`, with the vertical alignment style set to align.

- `setAlignment(graphic g, integer baseline)`

- Returns a copy of `g` with the baseline set to `baseline`. If needed, the result is extended vertically so that its height is no less than its baseline.

- This method has no effect with MuPAD up to version 2.5.3.

#### Method flipx: horizontal flip

- `flipx(graphic g)`

- Returns a copy of `g` flipped horizontally.

#### Method flipy: vertical flip

- `flipy(graphic g)`

- Returns a copy of `g` flipped vertically.

#### Example 1

We demonstrate some basic usage of this domain. Here is a little graphic:

    >> a := output::asciiArt([" \\_/ ", "| _ |", "|o o|", "//|\\\\", " ___"])

                                        ___
                                       //|\\
                                       |o o|
                                       | _ |
                                        \_/

The output is not yet quite perfect, but such a graphic can be included in a complex formula:

    >> (2*a + 1)/(x + a^2)

                                       ___
                                      //|\\
                                    2 |o o| + 1
                                      | _ |
                                       \_/
                                    -----------
                                          ___ 2
                                         //|\\
                                     x + |o o|
                                         | _ |
                                          \_/

We fetch some information on this graphic. This is its size:

    >> [a::dom::height(a), a::dom::width(a)]

                                      [5, 5]

Here are some of its characters:

    >> a[1, 1], a[3, 1], a[1, 3], a[2, 3]

                                " ", "_", "|", "o"

Fetching a character out of bounds raises an error.

    >> a[6, 6]

          Error: Out of range [output::asciiArt::_index]

The graphic can more or less be fliped around:

    >> a::dom::flipx(a)

                                        ___
                                       \\|//
                                       |o o|
                                       | _ |
                                        /_\

    >> a::dom::flipy(a)

                                        \_/
                                       | _ |
                                       |o o|
                                       //|\\
                                        ___

    >> a::dom::transpose(a)

                                        /_\
                                       | _ |
                                       |o o|
                                       \\|//
                                        ___

It is time to do some drawing now:

    >> a[2, 3] := "v":
       a

                                        ___
                                       //|\\
                                       |v o|
                                       | _ |
                                        \_/

    >> a[3, 5] := a[4, 6] := "/":
       a[4, 7] := "ooo": a[5, 8] := a[5, 6] := "o":
       a;

                                          o
                                         ooo
                                         /o
                                       _/_
                                      //|\\
                                      |v o|
                                      | _ |
                                       \_/

All of this does not look very serious, does it? Well, do not be misleaded. This hack is very hand for quick and simple display of combinatorial structures. And as usual with combinatorics, fun and seriousness are never very far away.

    >> combinat::dyckWords::printPretty([1, 1, 1, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 1, 0, 0, 0])

                                             /\
                                /\          /  \/\
                               /  \/\/\  /\/      \
                              /        \/          \

    >> combinat::binaryTrees(([1, [1,[1], [1]], [1, [],[1]]]));

                                         o
                                       /  \
                                      / \  \

    >> combinat::partitions::printPretty([5, 3, 1])

                               +---+
                               |   |
                               +---+---+---+
                               |   |   |   |
                               +---+---+---+---+---+
                               |   |   |   |   |   |
                               +---+---+---+---+---+

    >> combinat::tableaux::printPretty([[3], [1, 2, 4]])

                                   +---+
                                   | 3 |
                                   +---+---+---+
                                   | 1 | 2 | 4 |
                                   +---+---+---+

#### Example 2

The constructor `output::asciiArt::fromArray` is handy to create graphics with boxed cells. Here is how to draw a ribbon:

    >> output::asciiArt::fromArray(
           array(1..6, 1..6,
                 (3, 1) = 1, (3, 2) = 3, (3, 3) = 5,
                                         (2, 3) = 4, (2, 4) = 6,
                                                     (1, 4) = 2))

                                 +---+---+---+
                                 | 1 | 3 | 5 |
                                 +---+---+---+---+
                                         | 4 | 6 |
                                         +---+---+
                                             | 2 |
                                             +---+

#### Changes

- `output::asciiArt` is a new function

[Contents]

MuPAD Combinat, an open source algebraic combinatorics package