2 Invoking ponysay

The format for running the ponysay program is:

ponysay [option...] [--] [message]
ponythink [option...] [--] [message]

Running ponysay will print a speech balloon, ponythink will print a thought balloon. Otherwise ponysay and ponythink is the same thing.

ponysay supports the following options:

--

Parse the following arguments as parts of message.

-h

--help

Show summary of options.

-v

--verion

Show version of program.

-f PONY

--file PONY

--pony PONY

Specify the pony that should printed, this can either be a file name or a pony name printed by ponysay -l. This option can be used multiple times to specify a set of ponies from which one will be selected randomly. If no pony is specified one will be selected randomly.

If you have util-say installed, you can use .png-files as the arguments for this options.

In versions earlier than version 2.0, the if the pony were a file name it had to include a ‘/’. This is not longer required and any existing pony name supersedes file names.

+f PONY

++file PONY

++pony PONY

Just as +f, but it uses extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies

-F PONY

--any-file PONY

--anyfile PONY

--any-pony PONY

--anypony PONY

This option combines -f and +f.

-q PONY

--quote PONY

By using this option, a pony will be printed with quotes from her in My Little Pony: Friendship is Magic. The pony will be selected randomly, unless at least one pony is added as an argument to -q. If one or more ponies are added as an argument to -q, the pony will be selected randomly from that set of ponies. This option requires the extension ponyquotes4ponysay, which is included by default since version 1.2.

The argument can be a file name, but only if it ends with .pony.

--f [PONY...]

--files [PONY...]

--ponies [PONY...]

Variadic variant of -f, meaning that all arguments added after this one will parsed as an argument to this option. Additionally, those options are added to -f.

++f [PONY...]

++files [PONY...]

++ponies [PONY...]

Variadic variant of +f, meaning that all arguments added after this one will parsed as an argument to this option. Additionally, those options are added to +f.

An important feature of this options, is that you can but it in the end of the command line, without any argument to get a random non-MLP:FiM pony. However, altough it is not nice, since version 3.0, +f can also be unargumented if at the end of the command line.

--F [PONY...]

--any-files [PONY...]

--anyfiles [PONY...]

--any-ponies [PONY...]

--anyponies [PONY...]

This option combines --f and ++f.

--q [PONY...]

--quotes [PONY...]

Variadic variant of -q, meaning that all arguments added after this one will parsed as an argument to this option. Additionally, those options are added to -q.

An important feature of this options, is that you can but it in the end of the command line, without any argument to get a quote from any pony with a quote. However, altough it is not nice, since version 3.0, -q can also be unargumented if at the end of the command line.

-b STYLE

--bubble STYLE

--balloon STYLE

Specify the balloon style that should used, this can either be a file name or a balloon name printed by ponysay -B. This option can be used multiple times to specify a set of styles from which one will be selected randomly. If no balloon style is specified a fallback style will be used.

-W COLUMN

--wrap COLUMN

Specify the screen column where the message should be wrapped, this is by default 40, as with cowsay. The balloon’s extra width is taken into consideration.

If the argument is not a number, but starts instead with n (for ‘none’ or ‘no’), no wrapping is done, and if it starts with i (for ‘inherit’) the width of the terminal is used.

n and i is case insensitive, so you may use N and I instead. Additionally, typo correction is for QWERTY (and QWERTZ) and Dvorak is built in to ponysay; the nearest key, either to the left or to the right, depending on which hand is used to press the key, is also allowed.

-c

--compress

--compact

Compress the message in the same way cowsay does, that is basically without multiple spaces, and only paragraphs separations. Using this options will mean that you cannot display figlet and TOIlet style messages.

-l

--list

Lists all installed ponies. The ponies which have quotes, i.e. can be used with the -q option, will be marked by being printed in bold or bright (depending on the terminal.)

-L

--altlist

--symlist

Lists all installed ponies. The ponies which have quotes, i.e. can be used with the -q option, will be marked by being printed in bold or bright (depending on the terminal.) This options differs from -l by printing alternative names (symbolic links) inside brackets after their target ponies.

+l

++list

Just as -l, except it lists extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies.

+L

++symlist

++altlist

Just as -L, except it lists extra (non-MLP:FiM) ponies instead of standard (MLP:FiM) ponies.

-B

--bubblelist

--balloonlist

Prints a list of all balloon styles.

-A

--all

List all ponies, MLP:FiM and non-MLP:FiM, in this case the first list are MLP:FiM and the second are non-MLP:FiM.

+A

++all

--symall

--altall

List all ponies names, including alternatives, these from MLP:FiM and non-MLP:FiM. The first list are the MLP:FiM and the second one are non-MLP:FiM.

-o

--pony-only

--ponyonly

Print just the pony, nothing else like the speech balloon. Naturally the ponysay will not wait for a message from stdin.

-i

--info

By adding this flag you will get a metadata for a pony printed, rather than the pony itself. The output will beformated with bold tag names. The output will be wrapped according to the -W option.

+i

++info

This works just like the -i option, except the pony will use the output has her message rather that just print that information.

-r RESTRICTION

--restrict RESTRICTION

This option is used to restrict which ponies can be randomly select based one their metadata. The restrict is given is disjunctive normal form, and can hence express any logical combination, however only for tags with one entry. For tags with multiple values all values are tested and of one of them passes a test passes.

The argument for --restrict is a + separated list of values that all must be satisfied for a pony to be qualified for random selection. The option --restrict can be used multiply times, only one of them need to be satisfied for a pony to qualified for random selection.

A value in the argument is a combination of the tag name and tag value on the form NAME=VALUE. Additionally if the tag names ends with a question mark (?) the tag is satsified if the tag is missing; if the value starts with a bang (!) the test is inverted. Using just a bang means that the test passes for and only for all ponies with the tag definied; using the question mark and a empty value means that the test passes for all ponies; finally, using the question mark and just a bang for the value means that the test passes for and only for all ponies without the tag definied.

For most shells, if not all, trick to not need to use disjunctive normal form is to use { }. For example if you use --restrict={eye={blue,green,cyan}+coat={black,grey},coat=white} (note that there is no whitespaces) means that only ponies with white coat will be randomly selected as will as ponies with black or grey coat provided that they have either blue, green or cyan eyes.

-X

--256-colours

--256colours

--x-colours

Use xterm’s 256-colour support (supported by most X11 terminals), despite your terminal’s actual compatibilies.

-V

--tty-colours

--ttycolours

--vt-colours

Use Linux VT’s compatbilies without KMS utilisation, despite your terminal’s actual compatibilies.

-K

--kms-colours

--kmscolours

Use Linux VT’s compatbilies with KMS utilisation, despite your terminal’s actual compatibilies.

+c

--colour ANSI-COLOUR

Colour the balloon, including link and message (the parts that are not individually specified.) The argument, should be a ANSI colour sequence without leading CSI and without a tailing ‘m’, for example 1;31 will make it in red and bold (or bright depending on the terminal.)

--colour-bubble

--colour-balloon ANSI-COLOUR

Just like --colour, but it only colours the balloon, without the message or link.

--colour-link ANSI-COLOUR

Just like --colour, but it only colours the balloon link.

--colour-msg

--colour-message ANSI-COLOUR

Just like --colour, but it only colours the message.

--colour-pony ANSI-COLOUR

Just like --colour, but it colours the pony. This colouring has no effect ony regular pony files, as it has its own colouring.

--colour-wrap

--colour-hyphen ANSI-COLOUR

Just like --colour, but it colours hyphen added by the word wrapping. By default this is red (31), if you want uncoloured use 0, without 0 or 39, the default 31 is presistent.

If neither -q is used nor any message is specified, ponysay will read the message from stdin (standard input); however, if no arguments are used and nothing is piped to stdin, a help message will be printed. If you want to use ponysay without arguments and enter the message by hand, you can run cat | ponysay.

If no pony is selected, ponysay will look for a best.pony file, this file should be a symbolic link to the pony you want as a default. If it is not a symbolic link, -q cannot determine which quotes to use.