Since then I have been on holiday – driving up the coast (via Sonoma) to Seattle for the external research symposium at Microsoft – so have been out of contact. On reconnecting to WiFi (bless it) I am delighted to find that the add-in has been downloaded 27,000 times in the first week. Oh my!

I am going to be heading up the project when it goes open source (we are expecting this to happen in a couple of weeks and it will be available here) so I’m delighted to find so much interest out there and, of course, so many potential developers.

However, mostly the reason for this entry is to make sure that I commit myself publicly to writing up a list of TODOs for the project and where we see it going in the short to medium term. I would try to look far into the future but we all know that whatever I come back with will certainly come back to haunt me.

So there you have it. My commitment in print. It is for my own good; when I get back to Cambridge I am definitely going to have to hit the ground running. How exciting”

If you would like a file containing CML to test this out with, one is available here.

Now for the code:

using System.Collections.Generic;
using System.IO;
using System.IO.Packaging;
using System.Linq;
using System.Xml.Linq;
using System.Xml.XPath;

namespace Chem4Word.Tools
{
  public class OOXMLTools
  {
    public ICollection GetCML(string path)
    {
      ICollection list = new List();
      using (Package package = Package.Open(path, FileMode.Open))
      {
        foreach (PackagePart packagePart in package.GetParts())
        {
          if (packagePart.ContentType == "application/xml")
          {
            using (StreamReader streamReader =
               new StreamReader(packagePart.GetStream()))
            {
              try
              {
                XDocument xDocument =
                  XDocument.Parse(streamReader.ReadToEnd());
                if (xDocument.XPathSelectElements(
              "//*[local-name()='cml' and namespace-uri()=
              'http://www.xml-cml.org/schema']").Count() > 0)
                {
                  list.Add(xDocument);
                }
              }
              catch
              {
                  // not valid XML so therefore can't be CML
              }
            }
          }
        }
      }
      return list;
    }
  }
}

So there we go. Pretty similar to the Java version really. Just in case you were wondering, I know I haven’t done a load of exception checking.

A very quick into to DOCX and OOXML

There are plenty of blogs, papers, videos and the like out there which explain OOXML in various levels of detail. I don’t want to replicate that here but I think it will be useful to have a quick overview for reference. Microsoft developed the Open Packaging Convention (OPC) specification as a successor to its binary Microsoft Office file formats. The file-extension DOCX indicates an OPC document which should be edited using Microsoft Office Word 2007 (as opposed to the XSLX file extension for example which are OPC documents editable using Excel). A DOCX document is effectively a zip-file (the package) which contains the original text as a marked-up XML component (document.xml), with images and other embedded objects stored as separate files.

The package-part word\document.xml contains the main text and body of the document. Chem4Word stores CML files in the customXml folder within the package. This directory contains pairs of files with names item[\d].xml and itemProps[\d].xml – itemProps[n] contains a list of all the namespaces and schemas used in item[n].

Getting the CML out – the brute force extraction method

The first method of extracting the CML files is the simplest. This method does not allow us to know anything more about the data other than it has been included somewhere in the document by the user. For example, we don’t know where and how it is being used in the document (or how many times). So, for the algorithm: iterate through all those files where the CML may be found, attempt to build each file as a XOM document, if it builds then search within it for a cml element from the cml namespace (see code below).

import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.zip.ZipEntry;
import java.util.zip.ZipException;
import java.util.zip.ZipFile;

import nu.xom.Builder;
import nu.xom.Document;

public class OOXMLTools {

  public static List<Document> GetCML(File file)
    throws ZipException, IOException  {

    ZipFile zipFile = new ZipFile(file);
    List<Document> list = new ArrayList<Document>();
    Builder builder = new Builder();
    Matcher m =
      Pattern.compile("customXml/item([1-9][0-9]*)\\.xml")
        .matcher("");

    for (Enumeration <? extends ZipEntry>
      entries = zipFile.entries(); entries.hasMoreElements();) {

      ZipEntry entry = entries.nextElement();
      if (m.reset(entry.getName()).matches()) {
        try {
          Document doc =
            builder.build(zipFile.getInputStream(entry));

          if (doc.query("//*[local-name()='cml' and
            namespace-uri()='http://www.xml-cml.org/schema']")
              .size() > 0) {

            list.add(doc);
          }

        } catch (Exception e) {
          // not an XML file so can't be CML
        }
      }
    }
    return list;
  }
}

If you would like to try it out here is a DOCX file with some chemistry in it. There are three chemistry zones in the document (containing testosterone [item1] and acetic acid [item3]) but only two CML files in the customXml directory because both testosterone instances point to the same backing CML file.

In following posts I will go further into how you can discover which representation is being used in the document, how many times a particular CML file is referenced and how the data is converted into the on screen representation.

I have spent the last couple of days investigating other options and having got a good solution up and running thought I should share this with the world. This definitely isn’t meant to be an introduction to mercurial in general and I won’t be explaining all the terms (good intros are available from the mercurial website and elsewhere). I will be giving both command line and GUI instructions.

Installing VisualHG

The instructions on the VisualHG site are pretty good – but you only need to go through the first three. Basically you need to download and install TortoiseHg and then VisualHG.

Next make VisualHG the current active Source Control Plugin in Visual Studio 2008. <Tools> -> <Options> -> <Source Control>. Set the value of the drop-down list (Current Source Control plug-in) to <VisualHG>.

How to create a new repository and add it to source control

Open Visual Studio 2008 and create a new solution (in my case I went for a Console Application called cs-walkthrough under C:\projects\c# and I didn’t want a new directory for the solution)

In a command window change directory so you are in cs-walkthrough.

>hg init

this will create the .hg directory

create a file called .hgignore as a sibling of the .hg directory the contents of the file should be:



syntax: glob

*.csproj.user
obj/
bin/
*.ncb
*.suo
_ReSharper.*
*.resharper.user

Create a project on bitbucket with the same name as the solution (doesn’t have to be but will make things easier). So in this case I now have a publicly viewable repository on bitbucket http://bitbucket.org/jat45/cs-walkthrough.

Now create a file called hgrc under the .hg directory. This file should contain the following text:

[paths]
default = http://bitbucket.org/jat45/cs-walkthrough

[ui]
username = Joe Townsend

where jat45 should be replaced with your bitbucket id and cs-walkthrough should be replaced by the name of the bitbucket repository you just created.

From here on in you can do everything either from the command line or from within Visual Studio. I will give both commands (to access the VisualHG commands right-click on any of the files in the solution). All the command line commands should be run from the [cs-walkthrough] directory.

>hg status

or <HG status> from VisualHG

We want all these files under source control so either use

>hg add
or select all the files from the GUI and click Add then close the window

To commit these additions either use
>hg commit -m "initial commit"
or commit using <HG Commit>

Now push these changes to bitbucket

>hg push
or <HG Synchronize>(this will allow you to push, pull and see the incoming and outgoing changes).

Warning

Before committing or pushing changes you must make sure you build the solution first. This ensures that the [project].csproj file is correctly updated.

Getting an existing project

This is much easier than creating a new repository from scratch. Once again though we are back to the command line.

Change directory to the parent of where you would like the new project repository to be checked out to. In my case this is c:\projects\c#.

I am now going to get a clone of the cs-walkthough code from bitbucket but put it in a new location.

c:\projects\c#>hg clone http://bitbucket.org/jat45/cs-walkthrough my-new-source-dir

You can use the same command because the project is public so you can access the source code but not commit.

So I think that is it. You can do all the usual, push, pull, diff and so on either from the command line or from the VisualHG add-in. The one only thing that must be done from the command line is the initial clone or init. I am also investigating if everything works in VS2010 – so far no problems but if I run into any I will update you.

XPathDocument xPathDocument = null;
using (StringReader sr = new StringReader(source)) {
  xPathDocument = new XPathDocument(sr);
}

This ensures that the StringReader can be disposed of as soon as it has been used to create the XPathDocument. I am not at all surprised that Nick would spot this as it reminds me of the first Clojure macro that I finally got – though that was for a HTTP request.

Of course I could always have done the more conventional (and Java like):

StringReader sr = new StringReader(source);
XPathDocument xPathDocument = new XPathDocument(sr);
sr.Close();
sr.Dispose();

but I find the first way far more elegant and clear and it ensures that the resources are cleaned up no matter what – even if the creation of the XPathDocument throws exceptions.

Primarily I just wanted to capture this for reference rather than keeping it in my inbox.

Had a bit of a dig around the unchecked conversion issue.
The solutions to the problem, in my opinion and in Miss World order: -

1. I think the _worst_ thing to do is the default eclipse behaviour; adding @SuppressWarnings(“unchecked”) to the method declaration, since this will mask other warnings too, some of which can be much more severe than this one.
2. The next worst thing to do is to suppress warnings by annotating the individual line. I dislike this one because the annotation is just distracting noisy cruft.
3. Live with it. Stop your IDE whinging about it so much – the code will still compile.
4. The best solution is given in the answer at

http://stackoverflow.com/questions/367626/how-do-i-fix-the-expression-of-type-list-needs-unchecked-conversion/367673#367673

The main point in the answer given above is that doing an unchecked conversion results in the ClassCastException coming from the guts of the compiled code somewhere, rather than from your code, which is a Bad Thing. So the best thing to do is: -

Rather than : -
List<String> whatYoudLike = foo.getUntypedList(); // Exception gets thrown from the guts of whatever the compile generates to do this.

for(String s: whatYoudLike) {
//
}

the best way to do it would be: -

for(Object o : foo.getUntypedList()) {
String s = (String) o; // Exception gets thrown here if at all.
//
}

This approach can get a bit more verbose, but that is, I’m afraid, tough luck.

One of the things to come out of the Chem4Word project has been the idea of performing chemical changes via a stateless interface (CID – the Chemistry Interface Definition). This approach was strongly pushed by Savas and Jim (possibly as an excuse to learn yet another language). A stateless system lends itself beautifully to a functional language and as a bonus Clojure has both a CLR and JVM implementation so we can have a single definition which we can use on both platforms.

As a CompSci at Cambridge the first programming language you see is ML – probably because it makes it fairly easy to work out the big O. So I have some fond memories of functional programming (though quite what aroma it would require to really take me back does not bear thinking about) and (conveniently) a need for it.

The CLR implementation is still fairly bleeding edge and the installation process reminded me of the bad old days of Open Source software. Still 3 hours into the process and I had my REPL up and running and a function which would say Hello! not just to the world, but whoever happened to be passed to it. Tomorrow I shall be dusting off the ML part 1a handout by Larry Paulson (who broke off in lectures to teach us how to make bread the traditional way) and attempting any of the exercises I can find.

I’m looking forward to the Cambridge Clojure user group meeting and all this ML and functional talk means that a sneaky peak at F# over the long weekend is probably coming up too.

As we near a release date (we have function freeze and are now bug fixing) I was thinking about the branding etc and realised that we don’t have a logo, favicon or anything so was wondering if anyone has any suggestions.

I have to get back to writing a paper but first of all I was pleased to discover (thanks to Helen) that there is a Townsend unit (Td) but slightly less pleased that it is most important in gas discharge physics.