The Autopackage API

Table of Contents / Public library / String utility functions

String utility functions

String manipulation, version matching, etc.

Functions in this category

versionFromRootName<ROOTNAME>
justRootName<ROOTNAME>
getMajor<VERSION>
getMinor<VERSION>
compareVersions<REQUIRED> <CURRENT>
matchVersionList<FIRST> <VERSION> [VERSION...]
escapeFilename<FILENAME>
escapeValue<VALUE>
grepBeginsWith<INPUT> <FIND>
getKey<INPUT> <KEY>
getLine<STRING> <N>
getLineCount<STRING>
stripComments<STRING>
stripBlankLines<STRING>
joinLines<JOIN-POINT> <STR1> <STR2>
countDownVersions<VERSION> [VERSION...]
stripDupedItems[STRINGS]


Details

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


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


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


compareVersions
Syntax: compareVersions <REQUIRED> <CURRENT>
REQUIRED: Required version.
CURRENT: Current version.
Returns: 0 if passed, 1 if failed.
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 ]


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


escapeFilename
Syntax: escapeFilename <FILENAME>
FILENAME: A filename.
Outputs: The escaped filename.
Escape quotes and other special characters in a filename.
Example:
# We want a file 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 with / or . in).
Example:
value=`escapeValue "$whatever"`
echo "$something" | sed 's/hello/$value/g'


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"


getKey
Syntax: getKey <INPUT> <KEY>
KEY: A string.
INPUT: A string, or - indicating stdin.
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"


getLineCount
Syntax: getLineCount <STRING>
STRING: a multi-lined string.
Outputs: The number of lines in STRING.
Calculate how many lines STRING has.


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


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


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)


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


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.


Last update: 10/6/2003