NAME

util::filter - optex filter utility module

SYNOPSIS

optex -Mutil::filter [ --if/--of/--ef command ] command

optex -Mutil::filter [ --if/--of/--ef &function ] command

optex -Mutil::filter [ --isub/--osub/--esub/--psub function ] command

OPTION

--if command

--of command

--ef command

Set input/output filter command for STDIN, STDOUT and STDERR. If the command start by &, module function is called instead.

--isub function

--osub function

--esub function

Set filter function. These are shortcut for --if &function and such.

--psub function, --pf &function

Set pre-fork filter function. This function is called before executing the target command process, and expected to return text data, that will be poured into target process's STDIN. This allows you to share information between pre-fork and output filter processes.

See App::optex::xform for actual use case.

--set-io-color IO=color

Set color filter to filehandle. You can set color filter for STDERR like this:

--set-io-color STDERR=R

Use comma to set multiple filehandles at once.

--set-io-color STDIN=B,STDERR=R

--io-color

Set default color to STDOUT and STDERR.

DESCRIPTION

This module is a collection of sample utility functions for command optex.

Function can be called with option declaration. Parameters for the function are passed by name and value list: name=value. Value 1 is assigned for the name without value.

In this example,

optex -Mutil::function(debug,message=hello,count=3)

option debug has value 1, message has string "hello", and count also has string "3".

FUNCTION

set(io=command)

set(io=&function)

Primitive function to prepare input/output filter. All options are implemented by this function. Takes STDIN, STDOUT, STDERR, PREFORK as an io name and command or &function as a vaule.

mode function
option --if   &set(STDIN=$<shift>)
option --isub &set(STDIN=&$<shift>)

unctrl()

Visualize control characters.

visible(name=flag)

Make control and space characters visible.

By default, ESCAPE and NEWLINE is not touched. Other control characters and space are shown in unicode symbol. Tab character and following space is visualized in unicode mark.

When newline character is visualized, it is not deleted and shown with visible representation.

name

Name is tabstop, tabstyle, all, or one of these:

000 nul  001 soh  002 stx  003 etx  004 eot  005 enq  006 ack  007 bel
010 bs   011 ht   012 nl   013 vt   014 np   015 cr   016 so   017 si
020 dle  021 dc1  022 dc2  023 dc3  024 dc4  025 nak  026 syn  027 etb
030 can  031 em   032 sub  033 esc  034 fs   035 gs   036 rs   037 us
040 sp
240 nbsp

If the name is all, the value is set for all characters. Default is equivalent to:

visible(tabstyle=bar,all=s,esc=0,nl=0)

Tab width can be set by tabstop. As for tabstyle, use anything defined in Text::ANSI::Fold.

flag

If the flag is empty or 0, the character is displayed as is. If flag is c, it is shown in ^c format. Otherwise shown in unicode symbol.

rev_line()

Reverse output.

rev_char()

Reverse characters in each line.

shuffle_line()

Shuffle lines.

interval()

Output each line at regular intervals of time.

io_color( IO=color )

Colorize text. IO is either of STDOUT or STDERR. Use comma to set both at a same time: STDOUT=C,STDERR=R.

splice_line( offset=n, [ length=m ] )

Splice lines.

timestamp( [ format=strftime_format ] )

Put timestamp on each line of output.

Format is interpreted by strftime function. Default format is "%T.%f" where %T is 24h style time %H:%M:%S, and %f is microsecond. %L means millisecond. %nN can be used to specify precision.

gunzip()

Gunzip standard input.

gzip()

Gzip standard input.

EXAMPLE

Next command print ping command output with timestamp.

optex -Mutil::filter --osub timestamp ping -c 10 localhost

Put next line in your ~/.optex.d/optex.rc. Then for any command executed by optex, standard error output will be shown in visible and colored. This is convenient or debug.

option default -Mutil::filter --io-color --esub visible

Above setting is not effective for command executed through symbolic link. You can set ~/.optex.d/default.rc, but it sometime calls unexpected behavior. This is a future issue.

SEE ALSO

App::optex::xform

https://qiita.com/kaz-utashiro/items/2df8c7fbd2fcb880cee6