#       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