Using filters outside the box

NOTE: I decided to drop the support of this feature. If you want to use it, check out this branch, instead of the default.

Many of my previous posts have focused on the filter module, which makes it easy ti run an external program on the contents of an environment and include the result back in ConTeXt. This is useful when you do not have the patience (or, like me, the skill) to write the required functionality in TeX. The past posts have shown how to do this for markdown, R, and word clouds. But they are getting repetitive. Of course, once the module is working, I can use any program that I want. What the point in hooting my horn for each program that I can think of? Well, here is something out of the box — literally — what if the external program were a web-service?

Lets take the example of yUML, a website that creates UML class, activity, and case diagrams from the URL. For example

<img src="http://yuml.me/diagram/scruffy/class/[Company]<>-1>[Location], [Location]+->[Point]"/>

gives

Its that simple! Behind the schemes, yUML parses its input to a dot file, runs it through graphviz to create a svg, adds a few custom stylesheets, and exports the result as a png. However, it is available only as a web service and not a downloadable program. So what if I want to include such a figure in my ConTeXt document? I could create the image on a browser and save it on my computer. But where is the fun in that? Wouldn’t it be nice if I could just write

\startUMLclass
  [Company]<>-1>[Location]
  [Location]+->[Point]
\stopUMLclass

and automatically get the above figure. There is a new feature in the filter module that makes it easy to define such an environment. Download the latest t-filter.tex and t-filter.lua files and then just use

\usemodule[filter]
\defineexternalfilter
  [UMLclass]
  [method=httpget,
   filter={http://yuml.me/diagram/scruffy/class/},
   readcommand=\ExternalPngFigure,
   separator={,}]

\def\ExternalPngFigure#1{\externalfigure[#1][method=png]}
  • The option method=httpget indicates that the contents should be processed by a web service (using HTTP-GET; in the future I also plan to add the option of using HTTP-POST).
  • The option filter=... tells the base url of the web service
  • The option readcommand=... specifies the command that will read the result.
  • The option separator=... is used as the separtor to join
    lines. For example with separator={,} both the following are the
    same
\startUMLclass
  [Company]<>-1>[Location], [Location]+->[Point]
\stopUMLclass

and

\startUMLclass
  [Company]<>-1>[Location]
  [Location]+->[Point]
\stopUMLclass

So, how does it work? As I mentioned sometime ago, ConTeXt can read files off the web using the socket library included with LuaTeX. The filter module simply creates the correct URL from the input, asks ConTeXt to download the file, and displays the result. ConTeXt is a smart about downloading a file. Before starting a download, it checks that the same file was not downloaded less than 24 hours ago.

The same idea also works for other web-services. For example, for Google charts I can use

\usemodule[filter]

\defineexternalfilter
  [GoogleCharts]
  [method=httpget,
   filter={http://chart.apis.google.com/chart?},
   readcommand=\ExternalPngFigure,
   separator={&}]

Then

\startGoogleCharts
  cht=bhg
  chs=550x230
  chd=t:100,50,115,80
  chxt=x,y
  chxl=1:|Python|Java|Ruby|.NET
  chxr=0,0,120
  chds=0,120
  chco=4D89F9
  chbh=35,0,15
  chg=8.33,0,5,5
\stopGoogleCharts

gives

Advertisements

2 thoughts on “Using filters outside the box

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s