The Autopackage API

String utility functions

String manipulation, version matching, etc.

Functions in this category

NameParameters
compareVersions <REQUIRED> <CURRENT>
countDownVersions <VERSION> [VERSION...]
countStringLines <STRING>
escapeFilename <FILENAME>
escapeValue <VALUE>
getKey [<INPUT>] <KEY>
getLine <STRING> <N>
getMajor <VERSION>
getMinor <VERSION>
grepBeginsWith <INPUT> <FIND>
isInList [-F?] <SEARCH-ITEM> <LIST>
isInteger <INTEGER>
joinLines <JOIN-POINT> <STR1> <STR2>
justRootName <ROOTNAME>
matchVersionList <FIRST> <VERSION> [VERSION...]
replaceStr <FROM> <TO>
substituteCode <SOURCE-FILE> <START-MARKER> <END-MARKER> <TEMPLATE> <TEMPLATE-MARKER>
stripBlankLines <STRING>
stripComments <STRING>
stripDupedItems [STRINGS]
versionFromRootName <ROOTNAME>

Details

compareVersions
Syntax: compareVersions <REQUIRED> <CURRENT>
REQUIRED: Required version.
CURRENT: Current version.
Returns: 0 if CURRENT equals or is bigger than REQUIRED, 1 not.
This function compares 2 strings - infinite level of decimal groups. REQUIRED string for required version; CURRENT string for current version. Returns 1 if REQUIRED is > CURRENT, else 0. [ 0 - PASS, 1 - FAIL ]
Parameter string format: "x.y.z", where y and z are optional. Wildcards can only be used for an entire decimal group like "1.6.x" or "2.x" NOT "2.5x" . Function looks ahead in the decimal groups with alphabetic and numeric identifers to match full numbers. For instance REQUIRED:2-RC10f and CURRENT:2-rc2d, it ends up comparing 10 to 2 and returns 1 [ FAIL ] instead of 1 to 2 returning 0 [ PASS ].
Example:
                    Required    Current          Return Value
   compareVersions  "1"         "1.2"       --->  0 [ PASS ]
   compareVersions  "1.2"       "1"         --->  1 [ FAIL ]
   compareVersions  "1.1"       "1.2"       --->  0 [ PASS ]
   compareVersions  "1.3"       "1.2"       --->  1 [ FAIL ]
   compareVersions  "1.2"       "1.2"       --->  0 [ PASS ]
   compareVersions  "1.2b"      "1.2b"      --->  0 [ PASS ]
   compareVersions  "2.5-pre3"  "2.5"       --->  0 [ PASS ]
   compareVersions  "2.5-pre3"  "2.5-pre2"  --->  1 [ FAIL ]
   compareVersions  "2-RC10f"   "2-rc2d"    --->  1 [ FAIL ]
   compareVersions  "3.1-RC3"   "3.1-rc12"  --->  0 [ PASS ]
   compareVersions  "1.3"       "0.1.5"     --->  1 [ FAIL ]
   compareVersions  "1.99.6"    "2"         --->  0 [ PASS ]
   compareVersions  "1.6.x"     "1.6.7"     --->  0 [ PASS ]
   compareVersions  "1.6.x"     "1.6"       --->  0 [ PASS ]
   compareVersions  "1.6.x"     "1.5.7"     --->  1 [ FAIL ]
   compareVersions  "1.x"       "1.5.7"     --->  0 [ PASS ]


countDownVersions
Syntax: countDownVersions <VERSION> [VERSION...]
Given a version of the form A.B, will output a space delimited string consisting of A.B, A.(B-1), A.(B-2) and so on, until B is zero. You can use this to produce a list of supported interfaces from the highest interface version in the major set. If B is not specified, it will be assumed to be zero.
The micro version, if present, is ignored - only the major and minor numbers are included in the output.
Example:
countDownVersions 6.2
# -> 6.2 6.1 6.0
countDownVersion 1.8.6
# -> 1.8 1.7 1.6 1.5 1.4 1.3 1.2 1.1 1.0


countStringLines
Syntax: countStringLines <STRING>
STRING: a multi-lined string.
Outputs: The number of lines in STRING.
Calculate how many lines STRING has.
See also: countFileLines()


escapeFilename
Syntax: escapeFilename <FILENAME>
FILENAME: A filename.
Outputs: The escaped filename.
Escape quotes and other special characters in a filename, for use in bash.
Example:
# We want a file that's literally called: "The $cript's World\".txt
fn=`escapeFilename "\"The \$cript's World\\\".txt"`
eval "touch $fn"      # touch touch \"The\ \$cript\'s\ World\\\".txt


escapeValue
Syntax: escapeValue <VALUE>
VALUE: A string.
Outputs: The escaped value.
Escape VALUE for sed (useful for strings that contain / or .).
Example:
value=`escapeValue "usr/local"`
echo "usr/bin/foo" | sed 's/usr/$value/g'


getKey
Syntax: getKey [<INPUT>] <KEY>
KEY: A string.
INPUT: A string, or - indicating stdin. If not specified, - is used
Outputs: The KEY's value.
getKey searches the input text for a line of the form "KEY: VALUE", and outputs VALUE.
Example:
cat <<EOF | getKey - name    # => keymaker
name: keymaker
age: 27
occupation: making keys
EOF


getLine
Syntax: getLine <STRING> <N>
N: A line number. The first line is 1.
STRING: A multi-lined string.
Outputs: The Nth line of STRING.
Prints a certain line from STRING.
Example:
foo=`echo -e "hello\nworld"`
getLine "$foo" 2  # Outputs "world"


getMajor
Syntax: getMajor <VERSION>
VERSION: A version number.
Outputs: The major version number.
Extract the major version from a version number (anything before the first dot)
Example:
getMajor 2.3.4pre      # =>  2


getMinor
Syntax: getMinor <VERSION>
VERSION: A version number.
Outputs: The minor version number.
Extract the minor version from a version number (anything between the first and second dots)
Example:
getMajor 2.3.4pre      # =>  3


grepBeginsWith
Syntax: grepBeginsWith <INPUT> <FIND>
FIND: The string to search for.
INPUT: A string to search in. If - is given, input will be read from stdin.
Outputs: The found line(s).
Returns: 0 if one or more lines are found, 1 if nothing's found.
Find a line in INPUT that starts with FIND.
Example:
str=`cat << EOF
hello=1
world=2
anotherworld=3
EOF`
grepBeginsWith "$str" "world="   # =>  "world=2"


isInList
Syntax: isInList [-F?] <SEARCH-ITEM> <LIST>
LIST: string containing the items separated by the field separator
-F: specify the list separator, defaults to :
SEARCH-ITEM: which item to look for
isInList returns 0 if the given SEARCH-ITEM is one of the members of LIST. LIST is a string with members separated by either : or the specified separator character.
Example:
isInList a a:b:c -> returns 0
isInList -F/ x a/b/c -> returns 1


isInteger
Syntax: isInteger <INTEGER>
INTEGER: string to check if an integer.
Returns: 1 for failure and 0 for passing.
Function is to check for an integer variable type.
A string which is "" (blank) will pass.
Example:
if [[ "$variable" == "" ]] || ! isInteger "$variable"; then
	err variable is blank or not an integer
fi


joinLines
Syntax: joinLines <JOIN-POINT> <STR1> <STR2>
STR1: A multiline string that contains a line equal to JOIN-POINT
STR2: The string to insert at that point. It doesn't have to be multi-line.
JOIN-POINT: A string that identifies the line where str2 will be inserted
Outputs: The result;
Inserts str2 into str1 at the line which is equal to join-point. The result is sent to stdout.

The line containing the join point is removed first. You should remember to quote all the parameters, this will probably mess up: joinPoint foo $a $b, if a or b contain any spaces. Look at the example below to see how to call this function.

Example:
# (somefile is a text file which contains the line %UserScript%
# somewhere in the middle)
a=`cat somefile`
b=`cat userscript`
joinLines "%UserScript" "$a" "$b" >fullfile
# (fullfile now contains the contents of userscript inserted at the
# given point)


justRootName
Syntax: justRootName <ROOTNAME>
ROOTNAME: A rootname
Outputs: The unique string part of the name, without any version information
This function is useful to strip any version info from a root name, leaving you with just the part before the first colon. It outputs the result on stdout
Example:
justRootName "@foo.org/foo:2.2:1"      # => @foo.org/foo


matchVersionList
Syntax: matchVersionList <FIRST> <VERSION> [VERSION...]
Returns: 0 on success, 1 on failure.
Given a list of versions, will ensure that at least one of them is >= the first version given.
Example:
matchVersionList 2.4 1.8 2.0.3 2.5.3   # =>  0


replaceStr
Syntax: replaceStr <FROM> <TO>
FROM: A string.
TO: A string.
Outputs: The result.
Reads input from stdin, replaces all occurances of FROM to TO, and output the result. Use this function instead of sed s/$from/$to/g, because it can handle special characters (/, \, $, etc.) correctly.


substituteCode
Syntax: substituteCode <SOURCE-FILE> <START-MARKER> <END-MARKER> <TEMPLATE> <TEMPLATE-MARKER>
TEMPLATE: string which contains the TEMPLATE-MARKER.
END-MARKER: string which locates the line number to end gathering code.
TEMPLATE-MARKER: string which locates the line number to place the gathering code.
START-MARKER: string which locates the line number to start gathering code.
SOURCE-FILE: file which contains the START-MARKER and END-MARKER.
Outputs: The substituted code weaved into the TEMPLATE.
Substitutes gathered code into a template. This is useful such that only one copy of a function is actually within the codebase, while it is copied into other locations at package build time.
Example:
output-file=`cat output-file`
substituteCode "useful-stuff" "START SOMEFUNCTION" "END SOMEFUNCTION" "$output-file" "%InsertSomeFunctionHere%"` >output-file


stripBlankLines
Syntax: stripBlankLines <STRING>
STRING: A string.
Outputs: STRING without blank lines.
Removes all blank lines from STRING.


stripComments
Syntax: stripComments <STRING>
STRING: A string.
Outputs: STRING without comments.
Removes all content after a # mark.


stripDupedItems
Syntax: stripDupedItems [STRINGS]
STRINGS: A single string containing items, seperated by whitespace.
Given a list separated by spaces, like "a b c d c d b e" will eliminate the duplicated items and produce a list like "a b c d e" on stdout. If no parameters are supplied, input will be read from stdin.
Example:
stripDupedItems 6.2 6.1 6.0 6.1 6.0  # ==> 6.2 6.1 6.0
countDownVersions `testForLib -v libfoo.so.3` | stripDupedItems
  # ==> a list of all interface versions supported by installed libs, with
  #     duplicates that could be caused by multiple versions of the
  #     library being installed at once stripped.


versionFromRootName
Syntax: versionFromRootName <ROOTNAME>
ROOTNAME: A rootname
Outputs: The root name's version number.
Returns: 0 if there was a version in the root name, 1 if not.
Extract the version number from a root name.
Example:
versionFromRootName "@foo.org/foobar:2.2"    # =>  2.2