source: branches/lib/HELP_SOURCE/source/srt.hlp

#       main topics:
UP      arb.hlp
UP      glossary.hlp

#       sub topics:
SUB     reg.hlp

TITLE   Search and Replace Tool (SRT)


DESCRIPTION     The String Parser is used to search and replace substrings.


OCCURRENCE      TREE/Species/Search:PARSE FIELD
                TREE/Properties/NDS


SECTION         SYNTAX

        Basic search replace command:

# PREFORMATTED 1
                'search=replace'

                searches all occurrences of 'search' and replace each by 'replace'

        Multiple search/replace commands can be separated by the character ':':

# PREFORMATTED 1
                'search1=replace1:search2=replace2: ... :searchn=replacen'

                first searches all 'search1' and replaces each with 'replace1',
                then searches all 'search2' and replaces each with 'replace2',
                and so on.

                The order of the SRT commands will affect the result.
                Examples:
                 * 'i=o:a=i' replaces all 'i' by 'o' and all 'a' by 'i'.
                 * 'a=i:i=o' effectively replaces all 'a' and all 'i' by 'o'.
                   Each 'a' first gets replaced by 'i', which later gets replaced by 'o'.

SECTION SPECIAL CHARACTERS

        Search && Replace string:

                ':'                separates two commands
                '='                separates the search from the replace string
                '\'                Escape symbol
                '\\'               the '\' symbol itself
                '\n'               newline
                '\t'               tabulator
                '\:'               ':' (w/o special meaning)
                '\='               '=' (--- " ---)
                '\?'               '?' (--- " ---)
                '\*'               '*' (--- " ---)

        Search string:

                '?'                single letter wildcard
                '*'                multi letter wildcard

        Replace string:

# PREFORMATTED 1
                '?'

                        inserts the character which matched the corresponding single
                        letter wildcard ('?') in the search string.
                        Inserts a '?' if there is no corresponding wildcard.
                        Does not apply if a digit or '(' follows.

# PREFORMATTED 1
                '?n'

                        inserts the character which matched the n'th single
                        letter wildcard in the search string.
                        Inserts a '?' if there is no corresponding wildcard.
                        n = { 1,...,9 }

# PREFORMATTED 1
                '*'

                        inserts the substring which matched the corresponding multi
                        letter wildcard ('*') in the search string.
                        Inserts a '*' if there is no corresponding wildcard.
                        Does not apply if a digit or '(' follows.

# PREFORMATTED 1
                '*n'

                        inserts the substring which matched the n'th multi
                        letter wildcard in the search string.
                        Inserts a '*' if there is no corresponding wildcard.
                        n = { 1,...,9 }

# PREFORMATTED 1
                '*(key)'

                        inserts the value of the database field named 'key'
                        (or an empty string, if value is empty or missing)

# PREFORMATTED 1
                '*([key]#default)'

                        inserts the value of the database field named 'key'
                        (or 'default', if value is empty or missing)

# PREFORMATTED 1
                '*([key]\:SRT)'

                        reads the value of the database field named 'key',
                        applies the SRT on that value
                        and inserts the result.

# PREFORMATTED 1
                '*([key]|ACI)'

                        reads the value of the database field named 'key',
                        applies the LINK{aci.hlp} ACI on that value
                        and inserts the result.

# PREFORMATTED 1
                '*([key]|/REG/)'

                        reads the value of the database field named 'key',
                        applies the LINK{reg.hlp} REG on that value
                        and inserts the result.
                        Also allows replace by regular expression using '/REG/replace/'.


                Notes:
                * all above '*(key...)'-constructs read the content of DB field 'key'.
                * an empty string is used instead, if
                  * the field does not exists, or
                  * no fieldname is specified.
                    Skipping the fieldname is possible where '[key]' is used in the description above.
                * '?(key...)' does the same as '*(key...)'
                * the SRT, ACI and REG expressions used in '*(key...)' require escaping of the
                  characters ':', '=', '\', '*' and '?' by prefixing a '\'.
                  Nesting SRT expressions require additional levels of escaping (i.e. ':' -> '\:' -> '\\\:' -> '\\\\\\\:').
                * if an error occurs, the error message is inserted as result.
                  When used for LINK{props_nds.hlp} such an error often gets truncated.
                  Increasing the width of the display field helps to see the whole error message.

EXAMPLES

                Below you find some examples of SRT expressions.

# PREFORMATTED 1
                'p?r=p?w'

                        replaces all 'par' to 'paw', 'pbr' to 'pbw', 'pcr' to 'pcw', ...

# PREFORMATTED 1
                'p??r=p?2?1r'

                        swaps the two letters between p and r

# PREFORMATTED 1
                'a*=b*'

                        replaces only the first 'a' by 'b'

# PREFORMATTED 1
                'a=b'

                        replaces all 'a' by 'b'

# PREFORMATTED 1
                '?* *=?. *2'

                        replaces the first word by its first letter + '.'

# PREFORMATTED 1
                '\:=\n'

                        replaces all ':' by <newline>

# PREFORMATTED 1
                '*=* *(key1)'

                        appends the database field <key1>.
                        If <key1> does not exist, append a single space.

# PREFORMATTED 1
                '*=* *(key1):* =*'

                        appends the database field <key1>.
                        If <key1> does not exist, append a single space.
                        The second expression removes such a trailing space again.

# PREFORMATTED 1
                '*=* *(key1#no info)'

                        appends the database field <key1>.
                        If <key1> does not exist, then append 'no info'.

# PREFORMATTED 1
                '*=*(key2\: =)'

                        replace the whole input with the value of 'key2',
                        with all spaces removed.

# PREFORMATTED 1
                '*=*(key2|remove(.-))'

                        replace the whole input with the value of the database entry
                        'key2', with all '.' and '-' characters removed.

WARNINGS
                Be careful when search or replace string contain
                special characters (such as ':'). Avoid to write too
                complicated commands.

BUGS
                None