Leo and pyf: literate IF development? (interactive fiction in Python #2)

Originally when I started the IF with Python series I thought I would methodically go through each Python IF lib, write a small game, compare and contrast, and so on. I still plan to do that. But as might be expected, I’ve just gone down a rabbit hole, so I’d like to see where it leads.

On a TIGSource thread maybe a month ago I heard of the programming tool Leo, which is a ‘literate editor with outlines’. By literate it means it’s a tool for literate programming (LP).

I’ve always been interested in LP, but now I suspect it was for the wrong reasons — or at least for reasons that aren’t really fundamental to literate programming. I’d checked out PyLit a bit, and my experiment with Pawsy was in a similar vein of trying to find out how to weave IF’s prose with its code in a pleasing way. I was attracted to LP because it seeemd like ‘prose, with code’. Since I like prose, I thought, hey, this might be for me.

But I had some free time today, so I finally opened up the Leo zip I downloaded a few weeks ago. Now I’m not so sure that LP is about ‘prose with code’ — at least with Leo, LP seems to say instead that a program is not just a set of code instructions, and not just a commented explanation of itself, or that thing combined — but a program is a structure that operates on multiple levels, and restricting yourself to one view of that structure, or to one way of investigating, exploring, and manipulating that structure, is an extremely limiting way to work.

I know I’m not being that coherent, as I’ve been working with Leo for less than a day. Maybe some examples will help. Here’s a screen of Leo with a pyf IF project:

Here are some closeups — first, the top left pane, the outline view.

The right hand pane is simply a log window — the bottom pane is the code view:

The @others keyword there is a Leo directive that says, ‘insert here all nodes below this one in the outline’.

So what you can do here is create the world model structure of your game, and in the top level, organize these nodes into your program structure. Already I find that this makes for much more readable code.

In the outline view you’ll see node names (headlines) that begin with @thin. This is one way of telling Leo to write that node to an external file; when Leo writes the file it expands all @others type directives, so basically you end up with a file that assembles all the code in your nodes into a single game file ready to run.

My workflow, then, involves creating the Leo outline, and then running from within SciTE the assembled program. In an ideal world I’d be able to do this directly from within Leo; Leo stores its outline files in a .leo directory, so I guess it’s possible to run the Leo outline from the project directory instead, in order to have easy access to any modules that I’m importing into the game but are not available to the whole system from site-packages (like the pyf module, for example).

So far this may not seem much different from an IDE with class/function browsing, or an editor with multiple levels of code folding. However there are some important differences.

First of all you can put anything you want in a Leo outline — you can mix Python code, xml, html, plain text, etcetera, and choose what goes into the assembled file that is the actual game source. In this way a single outline can hold many disparate components you’re using for your game, but still produce the working game code as you need it.

Second, you can do more with the outline structure than you might expect. You can clone nodes in Leo, such that a single chunk of code or text can exist at multiple points in the outline hierarchy. When you change the node at one of these points, all of its clone nodes change as well.

In other words you have multiple views of the same piece of data. When I first read about that I immediately thought this would be a great way to write IF conversation. Of course I have no idea if that will work in practice, but imagine writing an IF conversation as an outline, where you can easily reuse quips as necessary. Compare that to a flat view of conversation, as you’d find in any IF source. The question is whether the additional overhead of the outline is a net plus over a conventional layout, but intuitively it seems like this could really work.

Anyway, the real test will be to write a non-trivial game in pyf using Leo, so that’s my next step. I have to say I’ve never been this excited about a programming tool though. Most of the IDEs I’ve checked out are not that inspiring; this feels completely different.


4 comments so far

  1. unixtechie on

    Hmm.. the creator of Leo never understood what Literate Programming was about, by his own admission, and after some hard thinking decided it was outlining instead.

    So he created an outlining editor which by the freak of its history shares some markup with a literate programming too, “noweb”.

    As an outlining editor it’s not bad at all, especially with node clones, easy tree rearrangement and ability to re-import back into the main project your code snippets you may have edited agter tangling them out.

    It fails however on two accounts: (a) it is not a literate programming tool and (b) it maintains in the user a fractured, “mosaic” representation of code because Leo won’t allow you to see several sections open at the same time.

    I tried to combine literate programming with outlining myself, and came up with a tool in simple perl which “weaves” into a “folding HTML” (and can run as a CGI script, too, to eliminate intermediary file savings).
    The idea is that MOLLY.pl is a fully-fledged literate programming tool, which can run from command line and in the “quick mode”, and that “folding HTML” will allow you, the programmer, to see 5 pages relevant to what you are doing although there may be 5000 in the project – those will remain folded away and invisible.


  2. georgek on

    Thanks for the comment, as a newcomer to all this stuff it’s especially valuable to me hear people’s thoughts on LP and how it can be done.

  3. felix on

    plese i beg u from the bottom of my heart, give me detailed steps to follow to install leo. i know nothing about python (a complete novice) so i just do not understand all the help on the net. PLEASE help me.

    • georgek on

      felix, just go to this page and follow the steps:


      You download two files and double click on them both. The Python file will install Python and the Leo file is just the Leo directory. You can unzip that to whatever location you want.

      It doesn’t require any knowledge of Python, though as you learn Python you’ll be able to do more things with Leo — since Leo is scriptable with Python. But you don’t need to understand it at this point. Leo can work just like any other software out of the box.

      Here’s a simple way to make working with Leo easier. If you want to automatically open files that end with .leo with the Leo editor, open up a text editor (like Notepad, or preferably your programming editor — I use SciTE, but there are many options), and write something like this:

      python “c:\documents and settings\george\my documents\bin\leo-4-6-2-final\launchLeo.py” –file=%1

      Substitute the path of where you put the Leo directory for the path above. You see that I put my Leo directory in ‘my documents\bin’, but you can put it wherever. Save this file as launchLeo.bat. Then go to the Leo directory and launch leo (by running launchLeo.py) and create and save a workbook.

      Leo will automatically save workbooks on Windows in your ‘documents and settings\username\.leo’ directory. Go to that directory and right click on it to open. You’ll see the Windows dialog that asks what program you want to use to open the workbook.leo file. Browse to your launchLeo.bat file and select that, and check the box so that all .leo files in the future get opened with that bat file. From now on you can double click on .leo files and they’ll get opened by Leo as you expect.

      You’ll need to make sure that Python is in your Windows environmental PATH variable. You set that in the System dialog — look for advanced settings.

      Let me know if you need more help.

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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: