NAME

ansifold/ansicolrm/ansicut - fold/colrm/cut command handling ANSI terminal sequences

SYNOPSIS

ansifold [ options ]

  -w#    --width=#                Folding width (default 72)
         --boundary=word|space    Fold on word boundary
         --padding[=#]            Padding to margin space
         --padchar=_              Default padding character
         --prefix=string          Set prefix string (default empty)
         --autoindent=pattern     Set auto-indent pattern
         --ambiguous=narrow|wide  Unicode ambiguous character handling
  -p     --paragraph              Print extra newline
  -r     --refill                 Join paragraph into single line first
         --separate=string        Set the output separator string (default newline)
  -n     --nonewline              Same as --separate ''
  --lb=# --linebreak=mode         Line-break mode (all, runin, runout, none)
         --runin=#                Run-in width (default 4)
         --runout=#               Run-out width (default 4)
         --runlen=#               Set run-in and run-out both
  -s     --smart                  Same as --boundary=word --linebreak=all
  -x[#]  --expand[=#]             Expand tabs
         --tabstop=n              Tab-stop position (default 8)
         --tabhead=char           Tab-head character (default space)
         --tabspace=char          Tab-space character (default space)
         --tabstyle=style         Tab expansion style (shade, dot, symbol)
         --colrm start [ end ]    colrm(1) command compatible
  -c#    --cut list               cut(1) command compatible
  -h     --help                   Show help message
  -v     --version                Show version

ansicolrm [ options ]

ansicut -c list

VERSION

Version 1.29

DESCRIPTION

ansifold is a fold(1) compatible command utilizing Text::ANSI::Fold module, which enables to handle ANSI terminal sequences.

ansicolrm works like colrm(1) command. This is an alias for ansifold command and works exactly same except option --colrm is enabled by default.

ansicut works like cut(1) command. This is an alias for ansifold command and works exactly same except default output separator string is set as empty by default. Support only -c (or --cut) option of the original cut(1) command.

FOLD BY WIDTH

ansifold folds lines in 72 column by default. Use option -w to change the folding width.

$ ansifold -w132

Single field is used repeatedly for the same line.

With option --padding, remained columns are filled by padding character, space by default, or specified by optional value like --padding=_. Default padding character can be set by --padchar option.

ansifold handles Unicode multi-byte characters properly. Option --ambiguous takes wide or narrow and it specifies the visual width of Unicode ambiguous characters.

TERMINAL WIDTH and CALCULATION

If the width argument begins with =, it is interpreted as an RPN (Reverse Polish Notation) expression with the terminal width as the initial value. Therefore,

ansifold -w=

will wrap at the width of the terminal, and

ansifold -w=2/

will wrap at half the width of the terminal.

MULTIPLE WIDTH

Unlike the original fold(1) command, multiple numbers can be specified.

$ LANG=C date | ansifold -w 3,1,3,1,2 | cat -n
     1  Wed
     2   
     3  Dec
     4   
     5  19

With multiple fields, unmatched part is discarded as in the above example. So you can truncate lines by putting comma at the end of single field.

ansifold -w80,

Option -w80, is equivalent to -w80,0. Zero width is ignored when seen as a final number, but not ignored otherwise.

If the data is shorter and there is no corresponding string, an empty string is returned. If the padding option is specified, a string padded to the given width is returned.

NEGATIVE WIDTH

Negative number fields are discarded.

$ LANG=C date | ansifold -w 3,-1,3,-1,2
Wed
Dec
19

If the final width is negative, it is not discarded but takes all the rest instead. So next commands do the same thing.

$ colrm 7 10

$ ansifold -nw 6,-4,-1

Option --width -1 does nothing effectively. Using it with --expand option implements ANSI/Unicode aware expand(1) command.

$ ansifold --expand --width -1

This can be written as this.

$ ansifold -xw-1

NUMBERS

Number description is handled by Getopt::EX::Numbers module, and consists of start, end, step and length elements. For example,

$ echo AABBBBCCCCCCDDDDDDDDEEEEEEEEEE | ansifold -w 2:10:2

is equivalent to:

$ echo AABBBBCCCCCCDDDDDDDDEEEEEEEEEE | ansifold -w 2,4,6,8,10

and produces output like this:

AA
BBBB
CCCCCC
DDDDDDDD
EEEEEEEEEE

SEPARATOR/TERMINATOR

Option -n eliminates newlines between columns.

$ LANG=C date | ansifold -w 3,-1,3,-1,2 -n
WedDec19

Option --separate set the output separator string.

$ echo ABCDEF | ansifold --separate=: -w 1,0,1,0,1,-1
A::B::C:DEF

Option -n is a short-cut for --separate ''.

Option --paragraph (or -p) print extra newline after each line. This is convenient when a paragraph is made up of single line, like microsoft word document. The -p option can be repeated multiple times and will output that many newline characters.

PREFIX

--prefix=string

If a string is given by --prefix option, that string is inserted at the beginning of each folded text. This is convenient to produce indented text block. Because the first line is not affected, insert appropiate prefix if necessary. Originally made for App::Greple::frame module.

--autoindent=pattern

An experimental --autoindent option takes a regex pattern for the indent label, and set the prefix string as a space string of that label length. For example, command ps auxgw produce very long line output and you may want to fold COMMAND portion with appropiate indentation. In this case use --autoindent option like this:

$ ps axgw | ansifold --autoindent '.*TIME (?=COMMAND)' -w= --boundary=word
  PID   TT  STAT      TIME COMMAND
    1   ??  Ss   817:25.87 /sbin/launchd
  354   ??  S      4:30.01 /System/Applications/TextEdit.app/Contents/
                           MacOS/TextEdit
  522   ??  Ss     2:50.67 /System/Library/PrivateFrameworks/Uninstall.
                           framework/Resources/uninstalld

REFILL

Option --refill (or -r) makes the command to run in paragraph mode, which read consecutive non-blank lines at once, and join them into single line before processing. So all paragraphs are reformatted by new text width. You can use this with --autoindent option.

Option -rw-1 will just fill paragraphs without reformatting.

LINE BREAKING

Line break adjustment is supported for ASCII word boundaries. As for Japanese, more complicated prohibition processing is performed. Use option -s to enable everything.

--boundary=word|space

This option prohibit breaking line in the middle of ASCII/Latin word. Context of word is defined by option value; word means alpha-numeric sequence, while space means simply non-space printables.

--linebreak=all|runin|runout|none, --lb=...

Option --linebreak takes a value of all, runin, runout or none. Default value is none.

When --linebreak option is enabled, if the cut-off text start with space or prohibited characters (e.g. closing parenthesis), they are ran-in at the end of current line as much as possible.

If the trimmed text end with prohibited characters (e.g. opening parenthesis), they are ran-out to the head of next line, provided it fits to maximum width.

--runin=width, --runout=width

--runlen=width

Maximum width of run-in/run-out characters are defined by --runin and --runout option. Default values are 4.

Option --runlen set both run-in/run-out width at once.

--smart, -s

Option --smart (or simply -s) set both --boundary=word and --linebreak=all, and enables all smart text formatting capability.

Use option --boundary=space if you want the command to behave more like -s option of fold(1) command.

TAB EXPANSION

--expand

Option --expand (or -x) enables tab character expansion.

$ ansifold --expand

Takes optional number for tabstop and it precedes to --tabstop option.

$ ansifold -x4w-1

If the command is executed with the name ansiexpand, it works as if the --expand option were given, and set default folding width to -1. App::ansiexpand is a bit more sophisticated and we recommend using that one rather.

--tabhead, --tabspace

Each tab character is converted to tabhead and following tabspace characters (both are space by default). They can be specified by --tabhead and --tabspace option. If the option value is longer than single characger, it is evaluated as unicode name. Next example makes tab character visible keeping text layout.

$ ansifold --expand --tabhead="MEDIUM SHADE" --tabspace="LIGHT SHADE"

--tabstyle

Option --tabstyle allow to set --tabhead and --tabspace characters at once according to the given style name. Select from dot, symbol or shade. Styles are defined in Text::ANSI::Fold library.

$ ansifold --expand --tabstyle=shade

COLRM COMPATIBLE

--colrm [ start [ end ] ... ]

Option --colrm takes colrm(1) command compatible arguments.

Since the output separator string is not set, use the -n option to get the same result as the colrm(1) command; when invoked as ansicolrm command, the separator string is set to the empty by default.

Next command behave exactly like colrm start end and takes care of ANSI terminal sequences.

$ ansifold -n --colrm start end

$ ansicolrm start end

Unlike standard colrm(1), start and end can be repeated as many times as desired. Next command removes column 1-3 and 7-9 and produces 4560 as a result.

$ echo 1234567890 | ansifold -n --colrm 1 3 7 9
       ^^^   ^^^

CUT COMPATIBLE

--cut list ...

-c list ...

Option --cut (or -c) takes cut(1) command compatible arguments.

Since the output separator string is set, use the -n option to get the same result as the cut(1) command; when invoked as ansicut command, the separator string is set to the empty by default.

Next command behave exactly like cut -c list and takes care of ANSI terminal sequences.

$ ansifold -n -c list ...

$ ansicut -c list ...

Next command retrieve column 4-6,9- and produces 45690 as a result.

$ echo 1234567890 | ansifold -nc 4-6,9-
          ^^^  ^^

Unlike cut(1)'s -c option, parameter number is taken as screen columns of the terminal, rather than number of logical characters.

BUGS

Option --refill will join Hangul string without space. Probably this is not a correct behavior.

FILES

~/.ansifoldrc: Start-up file. See Getopt::EX::Module for format.

INSTALL

CPANMINUS

$ cpanm App::ansifold

AUTHOR

Kazumasa Utashiro

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install App::ansifold, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::ansifold

CPAN shell

perl -MCPAN -e shell
install App::ansifold

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)