NAME

Array::Slice - Provides array support operations.

SYNOPSIS

    use Array::Slice;
        $text = sliceByPattern($data,"Welcome to",'(C)\s*Copyright',5,-10,'\w+\s(\w+)',1);
        $text = sliceByPattern($data,"Welcome to",'(C)\s*Copyright','SECTION\s\d+');
        @lines = sliceByPattern($data,"Welcome to",'(C)\s*Copyright',5,-10,'\w+\s(\w+)',1);
        @text = sliceByPattern($data,"Welcome to");

EXPORTS

Default: sliceByPattern

Optional: none

REQUIRES

Perl5.005, Data::Handy

DESCRIPTION

Array::Slice extracts a portion of an array. The function sliceByPattern accepts an assortment of parameters to specify the portion. It was named after the analogous array slice concept in Perl. sliceByPattern returns an array slice of an array, but rather than specifying by line number, you specify by pattern (i.e. regular expression).

startPat and stopPat are the main selection patterns to define a range. Both of them match the first occurrence of their respective patterns in the file. You may refine the range, though, with startAdj and endAdj. With these, you may offset the range either forward or backward. startAdj and endAdj may be patterns or signed integers. A pattern p will move the range boundary forward; while !p will move the range boundary backward (i.e. prefix the pattern with a "!"). Similarly, a positive integer moves the boundary forward; a negative integer moves it backward. All of these movements are by line.

After slicing by rows via the various start and stop options, you may additionally slice by columns by specifying a colPattern pattern to match within each line. You must include exactly one subexpression group (with parentheses) within colPattern to grab a piece of text; otherwise, you'll just get a count of what was matched. If colPattern fails, the entire line is skipped; i.e. you do not get the original line, nor a blank line--you get no line.

Examples

Assume we have the following in an array A:

        Star light,
        Star bright,
        First star I see tonight,
        I wish I may,
        I wish I might,
        Have this wish I wish tonight.

To select all lines from "First" to the end of the array:

        $output = sliceByPattern(\@a, "First");
        First star I see tonight,
        I wish I may,
        I wish I might,
        Have this wish I wish tonight.

To select just the first line containing "wish":

        $output = sliceByPattern(\@a, "wish", "wish");
        I wish I may,

To select the word after "star" in all lines:

        $output = sliceByPattern(\@a, "Star", "star", undef, undef, 'tar\s+(\w+)');
        light
        bright
        I

Another way to do the same thing, since column selection collapses for lines which don't match the column pattern:

        @output = sliceByPattern(\@a, ".", undef, undef, undef, '[Ss]tar\s+(\w+)');
        light
        bright
        I

To select the lines containing "tonight" which appear after the first occurrence of "wish":

        print sliceByPattern(\@a, "wish", undef, "tonight");
        Have this wish I wish tonight.

FUNCTIONS

sliceByPattern

sliceByPattern(data, startPat, stopPat, startAdj, stopAdj, colPattern, verbose)

sliceByPattern(data, startPat, stopPat, startAdj, stopAdj, colPattern)

sliceByPattern(data, startPat, stopPat, startAdj, stopAdj)

sliceByPattern(data, startPat, stopPat, startAdj)

sliceByPattern(data, startPat, stopPat)

sliceByPattern(data, startPat)

Selects an array slice where the endpoints are defined by regular expressions (startPat and stopPat). (If startPat and stopPat are the same, just a single line will be extracted.) The endpoints so defined may be adjusted with positive or negative offsets specified as regular expressions or as integers (startAdj or stopAdj). Note that each pattern must be contained within a single line of the input.

Parameters:

data - string containing multiple lines or a reference to a string array

startPat - regular expression; indicates beginning of slice. If not found, returns entire file.

stopPat - optional; regular expression; indicates end of slice. If omitted, or if not found, extracts through the end of the file.

startAdj - optional; regular expression or integer. If a pattern, adjusts starting line determined by startPat by searching forward (or backward with ! prefix). If a number, adjusts the starting line by the number (positive or negative).

stopAdj - optional; regular expression or integer. If a pattern, adjusts ending line determined by stopPat by searching forward (or backward with ! prefix). If a number, adjusts the ending line by the number (positive or negative).

colPattern - optional; regular expression, containing one subexpression grouping, to grab text within each of the selected lines instead of the whole line.

verbose - optional; boolean; if true, prints info about matched line numbers.

Returns: