Merge lp:~spud/spud/alias into lp:spud

[Fraser Waters]

Allows schemata files to list key value pairs of alias name and xml path.

[Patrick Farrell (pefarrell)]

Can you give an example of the new format in the manual, too?

[Patrick Farrell (pefarrell)]

Adam, can you please try out this branch and see if it satisfies your blueprint?

I don't like the idea of putting things into a schema_alias. It really doesn't fit with the whole system; but the first half of your proposal is useful.

[Florian Rathgeber (florian-rathgeber)]

Unfortunately the check in diamond:29 is not robust. The schema file will seldom be only alphabetic: if it's an actual path to a schema file, it will never be and even if it's an alias it might contain - or _ (unless this is explicitly disallowed). Any characters that are a valid branch name should be allowed as aliases.

review: Needs Fixing

[Florian Rathgeber (florian-rathgeber)]

Seems the case when it's an actual path to a schema file is not supposed to satisfy the if in diamond:29. However, any one non-alpha characters in the alias causes it to be treated as a path, which does obviously not exist. I suggest all alphanumeric characters and - and _ should be allowed in an alias.

[Fraser Waters (fraser-waters08)]

> Seems the case when it's an actual path to a schema file is not supposed to
> satisfy the if in diamond:29. However, any one non-alpha characters in the
> alias causes it to be treated as a path, which does obviously not exist. I
> suggest all alphanumeric characters and - and _ should be allowed in an alias.

Correct. I'll change this to allow those characters.

[Adam Candy (asc)]

This looks good and adds some pretty helpful functionality.

Just a few points:

1. It would be good to have a description of this usage from diamond -h - i.e. that the argument to -s is a path or alias.

2. Blank lines in the .diamond/schemata/flml file are not skipped, leading to erroneous 'Warning: not a valid path: ' errors (with a blank path).

3. Currently the invalid path warning, e.g.
      Warning: not a valid path: /home/asc/cur/pgnonlinear/schemas/fluidity_options.rng
  occurs when any of the paths do not exist.
  It might be better to restrict this behaviour to when the -v verbosity switch is supplied,
  OR in the case where the missing path is actually the schema file diamond requires (well, in this case you see the error, 'Could not find alias ...' - this is enough).
  I have schemas listed that do not exist on all machines I'm working on.

And finally, just a suggestion:

The alias could be supplied without -s. Any argument with a dot suffix is a file to be loaded. An argument that does not contain a dot could be considered an alias.

review: Needs Fixing

[Stephan Kramer (s-kramer)]

My 2 cents:
Could we not make the alias use a different option, say -a. So we don't need to do any interpreting of arguments to see whether they're an alias for a schema, a path to a schema, or an .xml options file. I'd like to stick to conventions that filenames can have arbitrary (os allowed) names.

[Fraser Waters (fraser-waters08)]

@asc
1. Yes that help will be added once this is finalized.
2. Will fix to ignore blank lines.
3. Will fix to only print under verbose.
@s-kramer
I'm assuming -s and -a would be mutually exclusive? If you've already given a schema to load an alias means nothing. If they're both given should one override the other or is that an error?

[Florian Rathgeber (florian-rathgeber)]

I guess -s would override -a if in doubt. But since this is an assumption that is not clear to the user I think raising an error is preferred.

I agree with s-kramer that any "legal" file name should be allowed.

Just a thought I had the other day: bzr branches (can) have a nickname you can read and set with `bzr nick` (it is automatically set if you `bzr branch`). In case neither -a nor -s are given, diamond could try using the bzr nick to auto-select the alias. In case bzr nick is not available (i.e. you're not running diamond from within a bzr branch) it could go back to the defaults.

[Fraser Waters (fraser-waters08)]

> I guess -s would override -a if in doubt. But since this is an assumption that
> is not clear to the user I think raising an error is preferred.

What about pointing it out in the help and raising a warning if both are set. I'm just wondering if people might shortcut their diamond to use one alias normally and then add -s sometimes to load a file? Is that a valid use case?

> I agree with s-kramer that any "legal" file name should be allowed.

Yes in hind sight it wasn't a good idea to try and differentiate on one option.

> Just a thought I had the other day: bzr branches (can) have a nickname you can
> read and set with `bzr nick` (it is automatically set if you `bzr branch`). In
> case neither -a nor -s are given, diamond could try using the bzr nick to
> auto-select the alias. In case bzr nick is not available (i.e. you're not
> running diamond from within a bzr branch) it could go back to the defaults.

If others agree I'm sure it can be put in.

[Patrick Farrell (pefarrell)]

I think -s and -a should be mutually exclusive (i.e. error if both are set).

I don't think diamond should have any bzr-specific code.

[Patrick Farrell (pefarrell)]

Hi Fraser,

Can you please document your changes in the manual? People need to be able to discover this feature. At a minimum, you should add some text to sections 4.2.1 and 4.2.2.

[lp:~spud/spud/alias]

446. By Fraser Waters on 2011-08-12

Updated manual

447. By Fraser Waters on 2011-08-17

Missed a colon before the -s command line option

448. By Fraser Waters on 2011-08-25

Merge from trunk

[Adam Candy (asc)]

This looks good to me - I can put away the wrapper I've been using!

The only comment I have relates to my point 3 above, using an alias with an invalid path gives the error:

  Could not find alias "aliasname"!

when actually the alias does exist, it's just that the path is invalid. Something like the following might be more suitable:

  Path 'path' for alias 'aliasname' does not exist.

review: Approve

[Fraser Waters (fraser-waters08)]

Thats fixed, it was the case that it couldn't find the alias, but only because the alias loader was checking paths were valid (superfluous as it's done later)

=== modified file 'diamond/bin/diamond'
--- diamond/bin/diamond	2011-08-24 16:51:39 +0000
+++ diamond/bin/diamond	2011-08-25 14:38:35 +0000
@@ -20,6 +20,7 @@
 import os.path
 import sys
 import traceback
+import string
 
 import gtk
 import gtk.gdk
@@ -49,6 +50,7 @@
                "-h               Display this message\n" + \
                "-f               Forks at startup\n" + \
                "-s [SCHEMAFILE]  Use the supplied schema file *\n" + \
+               "-a [ALIAS]       Use the supplied alias, if not given use \"default\"\n" + \
                "-t [TRONFILE]    Use the supplied schematron file for extended validation\n" + \
                "-d [FILE]        Diff against the supplied file. (FILE must be specified)\n" + \
                "-v               Verbosity switch - if supplied Diamond prints additional\n" + \
@@ -62,7 +64,7 @@
 def main():
 
   try:
-    opts, args = getopt.gnu_getopt(sys.argv[1:], "hvfs:t:d:")
+    opts, args = getopt.gnu_getopt(sys.argv[1:], "hvfs:a:t:d:")
   except:
     Help()
     sys.exit(1)
@@ -119,45 +121,60 @@
   # if the user specifies a schema on the command line, use that.
 
   input_schemafile = None
+  input_alias = None
   input_schematron_file = None
   for opt in opts:
     if opt[0] == "-s":
       input_schemafile = opt[1]
+    elif opt[0] == "-a":
+      input_alias = opt[1]    
     elif opt[0] == "-t":
       input_schematron_file = opt[1]
 
-  # if the user has specified a file to work on, use the suffix as a key
-
-  if input_filename is not None and input_schemafile is None:
-    suffix = input_filename.split(".")[-1]
-    try:
-      input_schemafile = config.schemata[suffix][1]
-    except:
-      debug.deprint("Could not find schema matching suffix %s." % suffix, 0)
-      debug.deprint("Have you registered it in /etc/diamond/schemata/ or $HOME/.diamond/schemata?", 0)
-      debug.deprint("To register a schema, place a file in one of those directories, and let its name be the suffix of your language.", 0)
-      debug.deprint("The file should have two lines in it:", 0)
-      debug.deprint("A Verbal Description Of The Language Purpose", 0)
-      debug.deprint("/path/to/the/schema/file.rng", 0)
-      sys.exit(1)
-
-  # if there is only one schema, use that
-
+  if input_schemafile is not None and input_alias is not None:
+    debug.deprint("-s and -a are mutually exclusive", 0)
+    sys.exit(1)
+
+  #schemafile is not given so look up actual path
   if input_schemafile is None:
-    if len(config.schemata) == 1:
+
+    # if the user has specified a file to work on, use the suffix as a key
+    if input_filename is not None:
+      suffix = input_filename.split(".")[-1]
+      try:
+        schemata = config.schemata[suffix]
+      except:
+        debug.deprint("Could not find schema matching suffix %s." % suffix, 0)
+        debug.deprint("Have you registered it in /etc/diamond/schemata/ or $HOME/.diamond/schemata?", 0)
+        debug.deprint("To register a schema, place a file in one of those directories, and let its name be the suffix of your language.", 0)
+        debug.deprint("The file should consist of:", 0)
+        debug.deprint("  A Verbal Description Of The Language Purpose", 0)
+        debug.deprint("  Lines of the format alias=/path/to/the/schema/file.rng", 0)
+        debug.deprint("  alias= is optional, if not given default= is added automaticly")
+        sys.exit(1)
+      
+    # if there is only one schema, use that
+    elif len(config.schemata) == 1:
       suffix = config.schemata.keys()[0]
-      input_schemafile = config.schemata[suffix][1]
-
-  # otherwise ask the user to choose
-
-  if input_schemafile is None:
-    choices = [key + ": " + config.schemata[key][0] for key in config.schemata]
-    choice = dialogs.radio_dialog("Choose a schema", "Choose a schema to use:", choices, logofile)
-    suffix = choice.split(":")[0]
-    input_schemafile = config.schemata[suffix][1]
+      schemata = config.schemata[suffix]
+    
+    # otherwise ask the user to choose
+    else:
+      choices = [key + ": " + value[0] for key, value in config.schemata.iteritems()]
+      choice = dialogs.radio_dialog("Choose a schema", "Choose a schema to use:", choices, logofile)
+      suffix = choice.split(":")[0]
+      schemata = config.schemata[suffix]
+
+    try:
+      #if input_alias is None it will just use the default
+      input_schemafile = schemata[1][input_alias]   
+    except KeyError:
+      debug.deprint("""Could not find alias "%s"!""" % (input_alias or "default"), 0)
+      sys.exit(1)
+
+  #endif
 
   # ensure that the specified schema actually exists!
-
   try:
     if 'http' not in input_schemafile:
       os.stat(input_schemafile)

=== modified file 'diamond/diamond/config.py'
--- diamond/diamond/config.py	2011-08-01 15:19:52 +0000
+++ diamond/diamond/config.py	2011-08-25 14:38:35 +0000
@@ -29,7 +29,7 @@
 
 # Here we hard-code a default for flml
 # so that users don't have to tweak this to run it.
-schemata = {'flml': ('Fluidity markup language', 'http://bazaar.launchpad.net/~fluidity-core/fluidity/4.0-release/download/head:/fluidity_options.rng-20110415014759-hdavpx17hi2vz53z-811/fluidity_options.rng')}
+schemata = {'flml': ('Fluidity markup language', { None: 'http://bazaar.launchpad.net/~fluidity-core/fluidity/4.0-release/download/head:/fluidity_options.rng-20110415014759-hdavpx17hi2vz53z-811/fluidity_options.rng'})}
 
 for dir in dirs:
   try:
@@ -44,30 +44,37 @@
       except:
         debug.deprint("Failure to examine entry " + file + " in folder " + dir + ".")
         continue
-      newSchemata = [x.strip() for x in handle]
-      if len(newSchemata) < 2:
+      lines = [x.strip() for x in handle if x.strip()]
+      if len(lines) < 2:
         debug.deprint("Warning: Found schema registration file \"" + file + "\", but file is improperly formatted - schema type not registered", 0)
         continue
+
       # Expand environment variables in the schema path
-      newSchemata[1] = os.path.expandvars(newSchemata[1])
-      if not os.path.exists(newSchemata[1]) and 'http' not in newSchemata[1]:
-        debug.deprint("Warning: not a valid path: %s" % newSchemata[1], 0)
-        debug.deprint("schema type not registered")
-        continue
-      schemata[file] = tuple(newSchemata)
+      alias = {}
+      for i in range(1, len(lines)):
+        line = lines[i]
+
+        keyvalue = [x.strip() for x in line.split("=")]
+        key, value = ("default", keyvalue[0]) if len(keyvalue) == 1 else keyvalue
+
+        value = os.path.expandvars(value)
+        if not os.path.exists(value) and 'http' not in value:
+          debug.deprint("Warning: not a valid path: %s" % value)
+          debug.deprint("schema type not registered")
+          continue
+
+        if key in alias:
+          debug.deprint("""alias "%s" already registered, ignoring""" % key)
+        else:
+          alias[key] = value
+          if key == "default":
+            alias[None] = value
+
+      schemata[file] = (lines[0], alias)
       debug.dprint("Registered schema type: " + file)
   except OSError:
     pass
 
-if len(schemata) == 0 and "-s" not in sys.argv:
-  debug.deprint("Error: could not find any registered schemata.", 0)
-  debug.deprint("Have you registered any in one of the directores %s?" % dirs, 0)
-  debug.deprint("To register a schema, place a file in one of those directories, and let its name be the suffix of your language.", 0)
-  debug.deprint("The file should have two lines in it:", 0)
-  debug.deprint(" A Verbal Description Of The Language Purpose", 0)
-  debug.deprint(" /path/to/the/schema/file.rng", 0)
-  sys.exit(1)
-
 if __name__ == "__main__":
   for key in schemata:
     debug.dprint("%s: %s" % (key, schemata[key]), 0)

=== modified file 'doc/spud_manual.tex'
--- doc/spud_manual.tex	2011-08-22 16:29:08 +0000
+++ doc/spud_manual.tex	2011-08-25 14:38:35 +0000
@@ -1388,10 +1388,11 @@
 current system. This is specified in the \verb+schemata+ subdirectory of the
 \verb+/etc/diamond+ and \verb+~/.diamond+ directories. The file names in the
 \verb+schemata+ directory give the filename extension associated with a
-particular problem description language. The content of the file is two
-lines. The first line is the name of the problem description language while
-the second line contains the path of the XML syntax (\verb+.rng+) version of
-the corresponding schema.
+particular problem description language. The content of the file is two or
+more lines. The first line is the name of the problem description language,
+the remaining lines are key value pairs (key = value) of alias names and the 
+path of the XML syntax (\verb+.rng+) version of the corresponding schema.
+A line with no "key =" part will be interpreted as "default =".
 
 For example, the Fluidity package has a problem description language called
 the Fluidity Markup Language which uses the file extension
@@ -1412,6 +1413,12 @@
 \end{verbatim}
 Now Diamond will pick up the version of the schema in \verb+jrluser+'s svn
 tree rather than the version the sysadmin installed.
+Alternativly they could just add an alias to the existing \verb+//home/jrluser/.diamond/schemata/flml+:
+\begin{verbatim}
+Fluidity Markup Language
+/usr/share/fluidity/fluidity_options.rng
+jrl = /home/jrluser/fluidity/tools/fluidity_options.rng
+\end{verbatim}
 
 It is also possible to specify a URL over HTTP for the location of the
 schema. For example:
@@ -1446,6 +1453,9 @@
 Diamond will inspect the registered schemas for the suffix specified
 and use that schema.
 
+Except for when \verb+-s+ is given \verb+-a ALIAS+ can be supplied to select an alias
+other than the default. If \verb+-a+ is not given \verb+-a default+ is used.
+
 \subsection{Dynamic validation}
 Diamond uses the schema to guide the editing of valid documents that the schema
 permits. When a blank document is opened, information necessary to make a valid