Resourcerers Apprentice

In the previous chapter we learnt the fundamentals and found that, as is always the case with fundamentals, they're pretty dull; escpecially if you're a quick learner and spotted the important parts just by inspecting the first idoc! In this chapter we're going to build a real application. Something useful that uses dynamic data. Well we'll try, you can judge the usefulness for yourself when we're done.

First things first. We need some live data. Fortunately the kernel provides us with a number of introspective data sources, one of which is a document showing all the resources across the virtual filesystem. Here's an idoc that shows all idocs in the system.

Try this application here

What you saw was an XML representation of all the idocs in the virtual filesystem tree of the doc-netkernel module (this documentation). Whilst it's nice to know this is available it's not in the easiest form to use. So, we're going to build a resource browser.

The first step to building the application is to understand what's going on in the embryonic application you just executed. Previously the only instruction type we've used has been copy. Here we've used mls, which is short for module list but nobody ever remembers why things are named what they are. mls is an Active Universal Resource Accessor which dynamically generates the application module resource document. As you've seen this is somewhat like a directory listing in a regular operating system, only in this case it is an XML document containing dir directories and res resources with their URI reference and the URI of the module they are located in. We'll reveal more about the NetKernel and how it manages the virtual filesystem later.

Another important new aspect of this instruction is that it has no <operand>. This is because mls does not process a document it generates one from it's own internal resources. However it does require some guidance as to what to produce. This guidance is provided by the <operator>.

In general information which qualifies how a URA is to process or generate a resource is passed by the <operator>. The <operator> accepts exactly the same types as the <operand>, namely URI references to resources and literal documents.

MLS I'm very much mistaken

In this case the operator has a literal document with a root node mls. The operator document is inlined as a literal since it is convenient to be able to modifiy it as though it were part of the idoc code. It could equally be an xml file in the filesystem referenced by a URI. In addition there is nothing special about the root node name being the same as the URA type, it's just a useful convention observered by most kernel accessors that means you don't have to remember two things!

If we look at the <mls> literal <operator> document we see it contains four elements. The first element <filter> holds a regular expression. Now regular expressions give people cold sweats and migraines just at the mention but don't be afraid, this example is very simple. All we need to take from this is that the pattern is selecting all resources who's URI ends with 'idoc'. Other elements instruct mls to recurse the resource tree and to include the uri and module for each located resource. You can learn more about mls here.

Casting Off

Now we've met the operator we can explain the cast instruction used in the previous section. It was using a literal operator to indicate to the cast Accessor how the operand should be processed. In that case we were telling it to give us a text/html mimetype. You'll note that we've not got a cast instruction in the example above. That is because we're post-processing the the results of the example applications in a hidden application layer. This makes them easier to examine and allows us to produce nicely styled XML output for your browser - don't worry for now just remember the cast is being taken care of. We'll reveal much more later.

Summary

So although that was a very basic application it contained most of the final pieces we need to build a real application. We learned that Accessors can be generative resource providers. We also learned that the <operator> is used to provide the resource necessary to qualify how an Accessor will generate it's result. Finally we learned that the <operator> is exactly the same as the <operand> in it's syntax and the types that it uses.

On the way we learned a little about the mls URA and that it can provide a document describing the set of system resources.

In the next section we'll make something real...