Repository: ESMCI/cime

Issue:
Clean up of xmlquery usage
This request is partly about documentation and partly about what options are supported by xmlquery.

Looking at the new xmlquery (after #930), I see two classes of things that could be improved in the usage information:

1. I feel that there are more options than there need to be here: I don't see the need for the separate `--description`, `--type` and `--valid-values` options: I'd generally just want to run `--full` if I were interested in seeing that extra information. Also, the `--group` option appears not to work, though I don't see the need for that one either. I get overwhelmed trying to figure out how to use a tool when there are so many options. But I'm fine being overruled if others like having this flexibility.

2. The documentation (`-h`) could be improved:

    1. I get the impression that there are multiple possible uses: ./xmlquery -listall isn't compatible with some of the other options. This should be stated explicitly in the top usage message - i.e., it should give the different possible uses (similarly to what you get with, e.g., 'git help checkout')

    2. Important options should be listed first - as opposed to listing the deprecated '-file' first

    3. Need more information for some options like subgroup and no-resolve: I feel like these descriptions only make sense for someone who is intimately familiar with the system

    4. Is the documentation for 'caseroot' really correct? ("Case directory to build")

cc @jedwards4b @mvertens @bertinia
Clean up of xmlquery usage
This request is partly about documentation and partly about what options are supported by xmlquery.

Looking at the new xmlquery (after #930), I see two classes of things that could be improved in the usage information:

1. I feel that there are more options than there need to be here: I don't see the need for the separate `--description`, `--type` and `--valid-values` options: I'd generally just want to run `--full` if I were interested in seeing that extra information. Also, the `--group` option appears not to work, though I don't see the need for that one either. I get overwhelmed trying to figure out how to use a tool when there are so many options. But I'm fine being overruled if others like having this flexibility.

2. The documentation (`-h`) could be improved:

    1. I get the impression that there are multiple possible uses: ./xmlquery -listall isn't compatible with some of the other options. This should be stated explicitly in the top usage message - i.e., it should give the different possible uses (similarly to what you get with, e.g., 'git help checkout')

    2. Important options should be listed first - as opposed to listing the deprecated '-file' first

    3. Need more information for some options like subgroup and no-resolve: I feel like these descriptions only make sense for someone who is intimately familiar with the system

    4. Is the documentation for 'caseroot' really correct? ("Case directory to build")

cc @jedwards4b @mvertens @bertinia


Discussion:
It would also be nice to have the arguments to xmlquery and xmlchange be consistent. 

For example:
./xmlquery --subgroup case.run JOB_WALLCLOCK_TIME
but:
./xmlchange --id case.run JOB_WALLCLOCK_TIME=02:00

so, they should both be either --id or both --subgroup. 
Both use subgroup, your xmlchange example is incorrect.
There is an error with the --listall option to xmlquery:

/xmlquery --listall 
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'dependency'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g16.test.03.cylc/env_batch.xml'
I think this was supposed to be addressed by #1261, is it still broken in master?
@gold2718 - yes, I updated my sandbox to the master and it is working correctly. Thanks!
I'm still not sure what command line options to use in order to see the list of all 
possible subgroups. xmlquery --listall --verbose isn't any different than xmlquery --listall
which lists all the GROUPS and their associated id, value settings. 
 xmlquery --listall --subgroup expects a subgroup name and if I use a group name, then it works but how do I know what the possible subgroup options are? 

If I run 'grep subgroup *.xml' on all the caseroot XML files, then there are no elements with a 
subgroup attribute so that doesn't help.

Can we clarify the distinction between group and subgroup in the help message? Right now it just says:
   -subgroup SUBGROUP, --subgroup SUBGROUP
                        apply to this subgroup only

This really isn't helpful if you don't know what the subgroup options are before hand. Maybe we could setup the parser option to be:

   _subgroups = ['case.run','case.test','case.st_archive','case.lt_archive']

   parser.add_argument('--subgroup', nargs=1, required=False, choices=_subgroups,
                        help='Subgroup specification for resolving different batch configurations ' \
                             'associated with specific jobs that are submitted to a queue. ' \
                             'Must be one of {0}'.format(_subgroups))



Just found this error - are these args incompatible?

./xmlquery --listall --full
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'JOB_QUEUE'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g16.test.03.cylc/env_batch.xml'
> I'm still not sure what command line options to use in order to see the list of all
> possible subgroups.

@bertinia , I know it's hacky, but this would work I think:
```
./xmlquery --listall | grep 'Results in group' | sed 's/Results in group //g'
```
I believe that this issue has been addressed in #1504
Most of the comments from my original report have _not_ been addressed on master.
I disagree with your request to remove specific command line arguments --valid-values, --type and --description.    I just tested --group and it seems to work fine.   Documentation has been updated.   
`--group` doesn't work for me on master:

```
[roo2:~/cime_for_comparison/scripts/test_0511d]$ ./xmlquery --group STOP_N
	STOP_N: 5
```
... xmlquery --file env_batch.xml --listall is still broken on master:

```
./xmlquery --file env_batch.xml --listall
setting case file to env_batch.xml
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'prereq'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g17/env_batch.xml'

```
A number of external tools (cylc, DART, user scripts) use xmlquery and xmlchange to 
interface with the caseroot env_*.xml files and are reporting errors.
@bertinia I'm seeing this too, although I'm quite confused because I added a test for this in scripts_regression_tests and it's not flagging it as failing.
Given our usage in DART and Cylc I would elevate this problem to critical.

On Mon, May 22, 2017 at 2:48 PM, Alice Bertini <notifications@github.com>
wrote:

> ... xmlquery --file env_batch.xml --listall is still broken on master:
>
> ./xmlquery --file env_batch.xml --listall
> setting case file to env_batch.xml
> ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'prereq'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g17/env_batch.xml'
>
>
> A number of external tools (cylc, DART, user scripts) use xmlquery and
> xmlchange to
> interface with the caseroot env_*.xml files and are reporting errors.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/ESMCI/cime/issues/946#issuecomment-303215788>, or mute
> the thread
> <https://github.com/notifications/unsubscribe-auth/AHlxE4VYI1qILj01VNvfg_3S3h7rPmn_ks5r8fSLgaJpZM4LTSNh>
> .
>

@jedwards4b - the label has been migrated to CRITICAL since the error that is showing up is effect how DART and Cylc interact with the system.
This was partially but not completely addressed via #1593 .

Remaining issues are:

(1) `--group` doesn't work:

```
[roo2:~/cime/scripts/test_0523a]$ ./xmlquery --group STOP_N
	STOP_N: 5
```

(2) The combination of `--listall` and `--full` still gives a cryptic error, as mentioned in https://github.com/ESMCI/cime/issues/946#issuecomment-292837600

(3) I think the comment https://github.com/ESMCI/cime/issues/946#issuecomment-292822483 still has not been addressed

(4) Some of the pieces from point 2 of my original comment still have not been addressed. Of these, the most important is listing which options do and do not work with `--listall`. (I perceive that `--listall` is a fundamentally different use of this tool, which supports a different set of options.) I think it would be helpful to list the possible combinations of options similar to what `git help` does - e.g., for `git help checkout`:

```
       git checkout [-q] [-f] [-m] [<branch>]
       git checkout [-q] [-f] [-m] --detach [<branch>]
       git checkout [-q] [-f] [-m] [--detach] <commit>
       git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]
```
It would also be nice to have the arguments to xmlquery and xmlchange be consistent. 

For example:
./xmlquery --subgroup case.run JOB_WALLCLOCK_TIME
but:
./xmlchange --id case.run JOB_WALLCLOCK_TIME=02:00

so, they should both be either --id or both --subgroup. 
Both use subgroup, your xmlchange example is incorrect.
There is an error with the --listall option to xmlquery:

/xmlquery --listall 
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'dependency'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g16.test.03.cylc/env_batch.xml'
I think this was supposed to be addressed by #1261, is it still broken in master?
@gold2718 - yes, I updated my sandbox to the master and it is working correctly. Thanks!
I'm still not sure what command line options to use in order to see the list of all 
possible subgroups. xmlquery --listall --verbose isn't any different than xmlquery --listall
which lists all the GROUPS and their associated id, value settings. 
 xmlquery --listall --subgroup expects a subgroup name and if I use a group name, then it works but how do I know what the possible subgroup options are? 

If I run 'grep subgroup *.xml' on all the caseroot XML files, then there are no elements with a 
subgroup attribute so that doesn't help.

Can we clarify the distinction between group and subgroup in the help message? Right now it just says:
   -subgroup SUBGROUP, --subgroup SUBGROUP
                        apply to this subgroup only

This really isn't helpful if you don't know what the subgroup options are before hand. Maybe we could setup the parser option to be:

   _subgroups = ['case.run','case.test','case.st_archive','case.lt_archive']

   parser.add_argument('--subgroup', nargs=1, required=False, choices=_subgroups,
                        help='Subgroup specification for resolving different batch configurations ' \
                             'associated with specific jobs that are submitted to a queue. ' \
                             'Must be one of {0}'.format(_subgroups))



Just found this error - are these args incompatible?

./xmlquery --listall --full
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'JOB_QUEUE'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g16.test.03.cylc/env_batch.xml'
> I'm still not sure what command line options to use in order to see the list of all
> possible subgroups.

@bertinia , I know it's hacky, but this would work I think:
```
./xmlquery --listall | grep 'Results in group' | sed 's/Results in group //g'
```
I believe that this issue has been addressed in #1504
Most of the comments from my original report have _not_ been addressed on master.
I disagree with your request to remove specific command line arguments --valid-values, --type and --description.    I just tested --group and it seems to work fine.   Documentation has been updated.   
`--group` doesn't work for me on master:

```
[roo2:~/cime_for_comparison/scripts/test_0511d]$ ./xmlquery --group STOP_N
	STOP_N: 5
```
... xmlquery --file env_batch.xml --listall is still broken on master:

```
./xmlquery --file env_batch.xml --listall
setting case file to env_batch.xml
ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'prereq'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g17/env_batch.xml'

```
A number of external tools (cylc, DART, user scripts) use xmlquery and xmlchange to 
interface with the caseroot env_*.xml files and are reporting errors.
@bertinia I'm seeing this too, although I'm quite confused because I added a test for this in scripts_regression_tests and it's not flagging it as failing.
Given our usage in DART and Cylc I would elevate this problem to critical.

On Mon, May 22, 2017 at 2:48 PM, Alice Bertini <notifications@github.com>
wrote:

> ... xmlquery --file env_batch.xml --listall is still broken on master:
>
> ./xmlquery --file env_batch.xml --listall
> setting case file to env_batch.xml
> ERROR: Multiple matches for nodename 'entry' and attrs '{'id': 'prereq'}' in file '/glade/p/work/aliceb/sandboxes/tests/b.e20.B1850.f09_g17/env_batch.xml'
>
>
> A number of external tools (cylc, DART, user scripts) use xmlquery and
> xmlchange to
> interface with the caseroot env_*.xml files and are reporting errors.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/ESMCI/cime/issues/946#issuecomment-303215788>, or mute
> the thread
> <https://github.com/notifications/unsubscribe-auth/AHlxE4VYI1qILj01VNvfg_3S3h7rPmn_ks5r8fSLgaJpZM4LTSNh>
> .
>

@jedwards4b - the label has been migrated to CRITICAL since the error that is showing up is effect how DART and Cylc interact with the system.
This was partially but not completely addressed via #1593 .

Remaining issues are:

(1) `--group` doesn't work:

```
[roo2:~/cime/scripts/test_0523a]$ ./xmlquery --group STOP_N
	STOP_N: 5
```

(2) The combination of `--listall` and `--full` still gives a cryptic error, as mentioned in https://github.com/ESMCI/cime/issues/946#issuecomment-292837600

(3) I think the comment https://github.com/ESMCI/cime/issues/946#issuecomment-292822483 still has not been addressed

(4) Some of the pieces from point 2 of my original comment still have not been addressed. Of these, the most important is listing which options do and do not work with `--listall`. (I perceive that `--listall` is a fundamentally different use of this tool, which supports a different set of options.) I think it would be helpful to list the possible combinations of options similar to what `git help` does - e.g., for `git help checkout`:

```
       git checkout [-q] [-f] [-m] [<branch>]
       git checkout [-q] [-f] [-m] --detach [<branch>]
       git checkout [-q] [-f] [-m] [--detach] <commit>
       git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
       git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]
```

Resolving patch:
diff --git a/scripts/lib/CIME/case.py b/scripts/lib/CIME/case.py
--- a/scripts/lib/CIME/case.py
+++ b/scripts/lib/CIME/case.py
@@ -321,7 +321,8 @@ def get_record_fields(self, variable, field):
                     elif field == "group":
                         result.extend(env_file.get_groups(root))
                     elif field == "valid_values":
-                        vv = env_file.get_valid_values(variable)
+                        # pylint: disable=private-member
+                        vv = env_file._get_valid_values(root) 
                         if vv:
                             result.extend(vv)
                     elif field == "file":
@@ -1320,7 +1321,8 @@ def set_file(self, xmlfile):
         """
         expect(os.path.isfile(xmlfile), "Could not find file {}".format(xmlfile))
 
-        self.flush(flushall=True)
+        if not self._read_only_mode:
+            self.flush(flushall=True)
 
         gfile = GenericXML(infile=xmlfile)
         ftype = gfile.get_id()


Test patch: