Purpose: Provides functions to generate permutations of sequences and sets..
Unit Test Scripts: tests/seq.sh provides unit tests for the seq module.
| Unit Test Group | Description |
|---|---|
intseq |
Unit tests for function intSeq |
nvseq |
Unit tests for function nameValueSeq |
perseq |
Unit tests for function permutedSeq |
perset |
Unit tests for function permutedSet |
Requires Modules: list
Required By Modules: ssh-spec
| Variable Name | Purpose |
|---|---|
BASHFUL_LOADED_seq |
Declares that seq has been loaded |
| Function Name | Description |
|---|---|
intSeq |
Returns a separated list of non-negative integers, based on one or more input sequences of integers or integer ranges passed in as arguments. |
nameValueSeq |
Returns a separated list of name/value pairs, with each pair separated from the next by the specified pair separator, and each name separated from its value by the specified value separator. Each argument passed into the function will be interpreted as a name/value pair to be separated into a name and value, according to the first occurrence of the specified value delimiter. The name and/or value, if they contain text or numeric sequences, will be permuted into multiple resulting name/value pairs. |
permutedSeq |
Returns a separated list of strings representing permutations of static text mingled with non-negative integer sequences or static text sequences. The function reads each argument passed to it, and parses them by looking for embedded sequences within them. |
permutedSet |
Returns a separated list of permuted items. Each argument passed into the function will be split by the input delimiter and turned into a set of items. The set resulting from each argument will be permuted with every other set. |
Description: Returns a separated list of non-negative integers, based on one or more input sequences of integers or integer ranges passed in as arguments.
Parameters:
-n: optionally preserves null items.
-s: optionally specifies an output separator. Defaults to ' '.
-u: optionally generates only unique numbers, discarding duplicate numbers from the output.
Each number generated by an integer range will be padded with zeroes, if the number has less characters than any zero-padded numbers used to specify the integer range. For example, integer range 10-08 will generate 10 09 08, while integer range 10-8 will generate 10 9 8.
Examples:
intSeq 2 4 6 10-08
2 4 6 10 09 08
intSeq -u 5-8 10-6
5 6 7 8 10 9
intSeq -s ':' 1-5
1:2:3:4:5
intSeq -s ',' '1' '2' '' '4' '5' ' ' '6'
1,2,4,5,6
intSeq -s ',' -n '1' '2' '' '4' '5' ' ' '6'
1,2,,4,5,,6
intSeq -s ',' -n -u '1' '2' '' '4' '5' ' ' '6'
1,2,,4,5,6
Description: Returns a separated list of name/value pairs, with each pair separated from the next by the specified pair separator, and each name separated from its value by the specified value separator. Each argument passed into the function will be interpreted as a name/value pair to be separated into a name and value, according to the first occurrence of the specified value delimiter. The name and/or value, if they contain text or numeric sequences, will be permuted into multiple resulting name/value pairs.
Parameters:
-b: optionally bypasses the permuting of any text or numeric sequences that may exist in the names of name/value pairs.
-B: optionally bypasses the permuting of any text or numeric sequences that may exist in the values of name/value pairs.
-d: optionally specifies one or more value delimiter characters. The first occurrence of an input delimiter within a name/value pair will be used to split the name and value. All subsequent occurrences will be considered part of the value. Defaults to =. An error is returned if null, or if it contains [, ], or - characters.
-q: optionally escapes each item being output, in a way that protects spaces, quotes, and other special characters from being misinterpreted by the shell. Useful for assigning the output of this function to an array, via the following construct:
declare -a ARRAY="( `nameValueSeq -q "${INPUT_ARRAY[@]}"` )"
Note that while this option can be used simultaneously with an output separator specified via -S, such usage is not guaranteed to be parsable, depending upon the value of the separator.
-r: optionally removes name/value pairs containing null values. By default, such pairs are preserved.
-R: optionally removes name/value pairs containing null names. By default, such pairs are preserved.
-s: optionally specifies a value separator for separating each name from value. Defaults to =.
-S: optionally specified a pair separator for separating each name/value pair from the next. Defaults to ;.
-t: optionally trims whitespace from values.
-T: optionally trims whitespace from names.
-u: optionally outputs only unique name/value pairs, discarding duplicates from the output.
-v: optionally treats arguments without an input delimiter as a value with a null name. By default, such entries are treated as a name with a null value.
Examples:
nameValueSeq 'a=1' 'b=2' 'c=3'
a=1;b=2;c=3
nameValueSeq '=1' 'b=' 'c=3'
=1;b=;c=3
nameValueSeq '[,]=1' 'b=[,]' 'c=3'
=1;=1;b=;b=;c=3
nameValueSeq -r '=1' 'b=' 'c=3'
=1;c=3
nameValueSeq -r '[,]=1' 'b=[,]' 'c=3'
=1;c=3
nameValueSeq -R '=1' 'b=' 'c=3'
b=;c=3
nameValueSeq -R '[,]=1' 'b=[,]' 'c=3'
b=;c=3
nameValueSeq 'a=1' 'b'
a=1;b=
nameValueSeq -v 'a=1' 'b'
a=1;=b
nameValueSeq -s ':' 'a=1' 'b=2' 'c=3'
a:1;b:2;c:3
nameValueSeq -S ',' 'a=1' 'b=2' 'c=3'
a=1,b=2,c=3
nameValueSeq -u 'a=1' 'b=2' 'a=2' 'b=2'
a=1;b=2;a=2
nameValueSeq -t 'a= 1 ' 'b=2 ' 'c= 3'
a=1;b=2;a=2
nameValueSeq -T ' a =1' 'b =2' ' c=3'
a=1;b=2;a=2
nameValueSeq -d ':' 'url:http://example.com:80' 'val:start:stop'
url=http://example.com:80;val=start:stop
nameValueSeq -S ' ' '[a,b]=[1,2]' '[c,d]=[3,4]'
a=1 a=2 b=1 b=2 c=3 c=4 d=3 d=4
nameValueSeq -S ' ' -b '[a,b]=[1,2]' '[c,d]=[3,4]'
[a,b]=1 [a,b]=2 [c,d]=3 [c,d]=4
nameValueSeq -S ' ' -B '[a,b]=[1,2]' '[c,d]=[3,4]'
a=[1,2] b=[1,2] c=[3,4] d=[3,4]
nameValueSeq -S ' ' -b -B '[a,b]=[1,2]' '[c,d]=[3,4]'
[a,b]=[1,2] [c,d]=[3,4]
nameValueSeq -S ' ' -q "My Name=[No one,Doesn't matter]"
My\ Name=No\ one My\ Name=Doesn\'t\ matter
Description: Returns a separated list of strings representing permutations of static text mingled with non-negative integer sequences or static text sequences. The function reads each argument passed to it, and parses them by looking for embedded sequences within them.
Parameters:
-d: optionally specifies one or more text delimiter characters to separate values within a text sequence. Defaults to ,. An error is returned if null, or if it contains any character also contained by the starting or ending delimiters.
-m: optionally specifies one or more characters to serve as delimiters that mark the start of a sequence. Defaults to [. An error is returned if null, or if it contains - or any character also contained by the ending or text delimiters.
-M: optionally specifies one or more characters to serve as delimiters that mark the end of a sequence. Defaults to ]. An error is returned if null, or if it contains - or any character also contained by the starting or text delimiters.
-n: optionally preserves null values within permutations. By default, null values are discarded.
-N: optionally preserves separators that appear between null values and any adjacent null or non-null value. By default, separators adjacent to null values are discarded.
-p: optionally preserves null values within permutations, and preserves entirely null permutations within the output. By default, null values are discarded.
-q: optionally escapes each item being output, in a way that protects spaces, quotes, and other special characters from being misinterpreted by the shell. Useful for assigning the output of this function to an array, via the following construct:
declare -a ARRAY="( `permutedSeq -q "${INPUT_ARRAY[@]}"` )"
Note that while this option can be used simultaneously with an output separator specified via -s, such usage is not guaranteed to be parsable, depending upon the value of the separator.
-s: optionally specifies an output separator for each permutation. Defaults to ' '.
-u: optionally generates only unique permutations, removing duplicates from the results.
Sequences are delimited by the characters specified as the opening and closing delimiters, which may not appear elsewhere within the text.
Integer sequences are zero or more integers or integer ranges, separated by commas. An integer range is two integers separated by a dash -.
To specify a text sequence that contains characters that would otherwise be interpreted as integer sequences, specify a non-comma text delimiter:
permutedSeq -d ';' -s "\n" 'School is open from [8-9;10-11] [am;pm]'
School is open from 8-9 am
School is open from 8-9 pm
School is open from 10-11 am
School is open from 10-11 pm
Examples:
permutedSeq -s "\n" 'Trains depart at [1,09-10][am,pm]'
Trains depart at 1am
Trains depart at 1pm
Trains depart at 09am
Trains depart at 09pm
Trains depart at 10am
Trains depart at 10pm
permutedSeq -m '<' -M '>' '<1,2,1><8,9>'
18 19 28 29 18 19
permutedSeq -u -m '<' -M '>' '<1,2,1><8,9>'
18 19 28 29
permutedSeq -s ',' '[sub,,super][script,,sonic]'
subscript,subsonic,superscript,supersonic
permutedSeq -s ',' -n '[sub,,super][script,,sonic]'
subscript,sub,subsonic,script,sonic,superscript,super,supersonic
permutedSeq -s ',' -N '[sub,,super][script,,sonic]'
subscript,sub,subsonic,script,,sonic,superscript,super,supersonic
permutedSeq -s ';' '[Hello,Goodbye], [world,you]' '[Regards,Thanks]'
Hello, world;Hello, you;Goodbye, world;Goodbye, you;Regards;Thanks
permutedSeq -q '[Hi,Bye] [there,you]'
Hi\ there Hi\ you Bye\ there Bye\ you
permutedSeq -s ':' -N '[,,]'
:
Description: Returns a separated list of permuted items. Each argument passed into the function will be split by the input delimiter and turned into a set of items. The set resulting from each argument will be permuted with every other set.
By default, null items and null permutations are discarded.
Parameters:
-d: optionally specifies one or more input delimiter characters. Defaults to $IFS. An error is returned if null.
-i: optionally specifies an output separator for each set item. Defaults to ' '.
-n: optionally preserves null values within permutations. By default, null values are discarded.
-N: optionally preserves null separators that appear between null values and any adjacent null or non-null value. By default, separators adjacent to null values are discarded.
-p: optionally preserves null values within permutations, and preserves entirely null permutations within the output. By default, null values are discarded.
-q: optionally escapes each item being output, in a way that protects spaces, quotes, and other special characters from being misinterpreted by the shell. Useful for assigning the output of this function to an array, via the following construct:
declare -a ARRAY="( `permutedSet -q "${INPUT_ARRAY[@]}"` )"
Note that while this option can be used simultaneously with an output separator specified via -s, such usage is not guaranteed to be parsable, depending upon the value of the separator.
-s: optionally specifies an output separator for each permutation. Defaults to ' '.
-S: optionally appends an output separator at the end of the output. By default, no output separator appears at the end of the output.
-u: optionally generates only unique permutations, discarding duplicates from the output.
Examples:
permutedSet '1 2' 'a b'
1 a 1 b 2 a 2 b
permutedSet -d ',' '1,2' 'a,b'
1 a 1 b 2 a 2 b
permutedSet -i ':' -s ',' '1 2' 'a b'
1:a,1:b,2:a,2:b
permutedSet -i ':' -s ',' -S '1 2' 'a b'
1:a,1:b,2:a,2:b,
permutedSet -d ',' -s ',' '1,,2' 'a,,b'
1 a,1 b,2 a,2 b
permutedSet -d ',' -s ',' -n '1,,2' 'a,,b'
1 a,1,1 b,a,b,2 a,2,2 b
permutedSet -d ',' -s ',' -p '1,,2' 'a,,b'
1 a,1,1 b,a,,b,2 a,2,2 b
permutedSet -d ',' -s ',' -N -p '1,,2' 'a,,b'
1 a,1 ,1 b, a, , b,2 a,2 ,2 b
permutedSet -d ',' -s ',' -n 'a big' 'bad,,' 'wolf'
a big bad wolf,a big wolf
permutedSet -d ',' -n -q 'a big' 'bad,,' 'wolf'
a\ big\ bad\ wolf a\ big\ wolf
permutedSet -d ',' -s ',' -n -q 'a big' 'bad,,' 'wolf'
a\ big\ bad\ wolf,a\ big\ wolf
permutedSet -d ',' -i '' -s ',' -u '1,,2,,1' 'a,,b,,a'
1a,1b,2a,2b
permutedSet -d ',' -i '' -s ',' -u -n '1,,2,,1' 'a,,b,,a'
1a,1,1b,a,b,2a,2,2b
permutedSet -d ',' -i '' -s ',' -u -p '1,,2,,1' 'a,,b,,a'
1a,1,1b,a,,b,2a,2,2b