The mapfile builtin

incomplete

mapfile [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY]

The mapfile builtin command is used to assign lines of standard input (e.g. from a file with redirection) to an array named by ARRAY, each line in a separate element. If no array is named, the default array name is MAPFILE.

The mapfile builtin is also accessible as readarray.

Option	Description
-c QUANTUM	Specifies the number of lines that have to be read between every call to the callback specified witgh -C. The default QUANTUM is 5000
-C CALLBACK	Specifies a callback. The string CALLBACK can be any shell code, the index of the array that will be assigned is appended at evaluation time. .
-n COUNT	Reads at most COUNT lines, then terminates. If COUNT is 0, then all lines are read (default).
-O ORIGIN	Starts populating the given array ARRAY at the index ORIGIN rather than clearing it and starting at index 0.
-s COUNT	Discards the first COUNT lines read.
-t	Remove any trailing newline from a line read, before it is assigned to an array element.
-u FD	Read from filedescriptor FD rather than standard input.

The mapfile builtin returns success (0) unless an invalid option is given or the given array ARRAY is set readonly.

mapfile reads the lines from a file descriptor and load them into an array. The target array must be a “normal” indexed array, i.e. not an associative array (for the current pre-4.1 versions there's a bug making Bash crashing if the referenced array is an associative one, in 4.1 there will be a check).

The call back function, if defined is called before the assignement of the array element, thus you can only use it as a kind of progress bar,

mapfile -n 11 -c 2 -C echo <file
0   #as of 4.0rc1 there is a bug
2
4
8

if you want to get rid of the counter, you can use tricks like

$ mapfile -n 11 -c 2 -C 'printf . \#' <file
.....

if you want to use it elsewhere, you can use a function:

$ mapfile -n 11 -c 2 -C 'foo () { echo "|$1|" ;};foo ' <file
|2|
|4|
etc..

mapfile doesn't introduce a new feature. All mapfile provides can be done with a small while read loop, too.

Infact, mapfile could be easily implemented as shell function.

I don't understand why something like that is implemented.

Beware: the callback is appended to the history when used interactively.

As of RC1, there still are some implementation bugs, for example mapfile filling the readline history buffer with calls to the CALLBACK.

* Update(1): This is still present at Bash 4.1 alpha release, I wonder if this is considered a bug. * Update(2): Might be “fixed” (eliminated) in 4.1 beta, thanks Chet * Update(3): Fixed according to Changelog in 4.1 beta, thanks

• Arrays