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

#       main topics:
UP      sp_search.hlp
UP      gene_search.hlp
UP      security.hlp

#       sub topics:
SUB     tags.hlp

# format described in ../help.readme


TITLE           Modify fields of listed

OCCURRENCE      ARB_NT/Species/Search and Query/More Functions/Modify fields of listed
                ARB_NT/Genome/Search and query/More Functions/Modify fields of listed
                ARB_NT/Genome/Experiment/Search and query/More Functions/Modify fields of listed

DESCRIPTION     Finds and replaces substrings within fields/tagged subfields of
                all listed species/genes. The entries within the selected
                fields of all listed species/genes can be modified either
                individually or globally.

SECTION Target field

                Select the target field to modify by pressing the button in the upper part of the window.

                Target field related options:
                * 'Accept conversion errors':
                  - if checked, accepts modifications like writing "hello" to a
                    numeric field (which will be written as '0')
                  - otherwise arb will abort with an error in such cases (Note
                    that writing a string like "4711" to numeric fields will work w/o error)
                * 'Allow overwrite of species ID':
                  - normally writing to field 'name' is not permitted, because doing so is
                    dangerous and may destroy access to your data.
                  - if checked, arb will write the name field. Please make sure the written
                    values are unique. If the same value is used for e.g. two species, you
                    will loose access to one these species.

SECTION Expert options

                * 'Use Tags' allows to tag entries or modify only tagged parts of entries. See LINK{tags.hlp} for details.
                * 'Double Pars' causes the result of the 'Command' to be interpreted and executed as command once again (special; in doubt don't use)

SECTION Command

                Three different languages can be used to modify an entry:

                SRT:    indicated by a leading ':' character
                ACI:    indicated by a leading '|' character
                REG:    indicated by sourrounding '/' characters

        Details:

                REG: Simple Regular Expressions (not for beginners)

                        '/Search RegExpr/Replace String/'  or
                        '/Search RegExpr/'

                        (see LINK{reg.hlp} for more details)

                SRT: Replaces substrings

                        Syntax: ':old_string=new_string' (see LINK{srt.hlp} for more details)

                        Example: remove all spaces with SRT ': ='

                        Different search/replace commands can be performed
                        simultaneously and have to be separated by ':'

                                      ':search1=replace1:search2=replace2:  ...  :searchn=replacen'.

                        '*' and '?' are wild cards for multiple and single
                        characters, respectively.

                ACI: More sophisticated string manipulations

                     Read LINK{aci.hlp} for more information.

SECTION         Predefined commands

                Clicking on one of the predefined commands in the list at the bottom
                of the window
                 * will set the content of the 'Command' field and
                 * may change the selected target field (!!!)

SECTION         Defining custom commands

                You may add new commands by editing one of the files:

                        $ARBHOME/lib/sellists/mod_fields.sellst

                        $ARBHOME/lib/sellists/mod_gene_fields.sellst

                You should save this file to another location when
                installing new versions of ARB or it will be overwritten.

                A better way is to create your own list(s). All list
                matching 'mod_fields*.sellst' will be loaded, where
                'mod_fields.sellst' is loaded.

                If you have created any scripts which might be useful for
                other ARB users send them to LINK{devel@arb-home.de}.

EXAMPLES        ':p?r=p?1w'      replaces       par to paw
                                                pbr to pbw
                                                pcr to pcw ...

                ':p??r=p?2?1r'   swaps the two letters between p and r

                ':a*=b*1'        replaces only the first 'a' by 'b'

                ':?* *=?1. *2'   Replaces the first word by its first
                                 letter + '.'

                ':\:=\n'         replaces all ':' by <newline>

                ':*=*1 *(key1)'  appends the database field <key1>

                ':*=*1 *(key1|nothing found)'
                                appends the database field <key1>
                                if <key1> does not contain entries
                                append 'nothing  found'

                1. Global modification: Replace 'spec.' by 'sp.' within
                        the field full_name of all listed species:

                        Press:          'MODIFY FIELDS OF LISTED SPECIES'
                        Select Field:   'full_name'
                        Type Command:   ':spec.=sp.'
                        Press:          'GO'

                2. Individual modification: Append the particular entries
                        of fields 'title' and 'journal' to that of the
                        fields 'author' of all listed species if there
                        are any entries:

                        Press:          'MODIFY FIELDS OF LISTED SPECIES'
                        Select Field:   'author'
                        Type Command:   ':*=*1 *(title) *(journal)'
                        Press:          'GO'

NOTE            Undo does work.

WARNINGS        Be careful if search or replace string contains
                special characters (such as ':').

BUGS            No bugs known