PyGlk 0.1.0
Copyright (c) 2002, Joe Mason <jcmason@uwaterloo.ca>

This package is distributed under the BSD License - see the file License.txt
for details.


Building:


  - "make all" builds pyglk, glk.py, and glkcmodule.so

Before building, make sure the following variables are set correctly in
ther Makefile:

	GLKINCLUDEDIR - directory where glk.h and Make.<some glk lib> can be
	found
	GLKLIBDIR - directory where lib<some glk lib>.so can be found
	GLKMAKEFILE - Make.<some glk lib> (for instance, Make.glkloader for
	libglkloader.so)

	PYINCLUDEDIR - directory where Python.h can be found
	PYLIBDIR - directory where libpython<version> can be found
	PYLIB - -lpython<version> (for instance, -lpython2.1 for
	libpython2.1.so)

  - "make install" builds everything and installs it to your local Python
	packages directory

Before building, make sure the following variables are set correctly in
the Makefile:

	BINDIR - directory to install executables to (default: /usr/local/bin)
	PACKAGEDIR - directory to install python modules to (default:
	/usr/local/python<version>/site-packages)

  - "make pyglk" builds a modified Python terp that loads the glk library.
	(Basically, this is a Glk program where glk_main() just starts Python)
  - "make glkcmodule.so" builds the "glkc" modules, the C interface for Glk
  - "make glk.py" builds glk.py, some Python wrapper functions for Glk
	objects


Building without SWIG:

glkc.h and glkc.i are used as SWIG input files.  If you touch them, 'make
glkcmodule.so' (and therefore 'make all') will try to run SWIG to regenerate
glkc_wrap.c.  As long as you only change generate_glkmodule.py and pyglk.c,
you should be able to build without SWIG installed.

'make clean' removes all generated files except glkc_wrap.c.  'make
clean-swig' removes everything.

glk.py is also generated (by parsing glk.h), so don't edit it directly.
Edit generate_glkmodule.py instead.

Usage:

Hello, World in C glk:

#include "glk.h"

void glk_main(void)
{
    winid_t mainwin = glk_window_open(0, 0, 0, wintype_TextBuffer, 1);
    glk_set_window(mainwin);
    glk_put_string("Hello, world!\n");
    glk_put_string("Type 'quit' to exit.\n");

    while (1) {
        char commandbuf[256];
        int gotline, len;
        event_t ev;

        glk_put_string("\n> ");
        glk_request_line_event(mainwin, commandbuf, 255, 0);

        gotline = 0;
        while (!gotline) {
            glk_select(&ev);
            if (ev.type == evtype_LineInput && ev.win == mainwin) {
                gotline = 1;
            }
        }
        len = ev.val1;
        commandbuf[len] = '\0';

        if (strcmp(commandbuf, "quit") == 0) {
            glk_put_string("Goodbye, world!\n");
            glk_exit();
        }
    }
}

Hello, world in Python glk:

import glk

mainwin = glk.window_open(None, 0, 0, glk.wintype_TextBuffer, 1)
glk.set_window(mainwin)
glk.put_string("Hello, world!\n")

while 1:
	glk.put_string("\n> ")

	# Because Python strings are immutable, request_line_event (and
	# stream_open_memory) user buffer_t objects, which wrap strings that the
	# Glk library can alter.  To see what the current contents are, use the
	# snapshot() method to return an unmodifiable Python string.
	commandbuf = glk.buffer_t(None, 255)
	glk.request_line_event(mainwin, commandbuf, 0)

	gotline = 0
	while not gotline:
		ev = glk.select()
		if ev.type == glk.evtype_LineInput and ev.win == mainwin:
			gotline = 1

	if commandbuf.snapshot(ev.val1) == "quit":
		glk.put_string("Goodbye, world!\n")
		glk_exit()		# this closes the Python interpreter

Running the interpreter:

To use Glk calls, you have to run pyglk instead of python (otherwise you'll
get "undefined symbol" errors).  To pass arguments to python instead of the
Glk lib, put a - in front of each.  For instance, instead of "python -i
script.py" you'd run "python - -i - script.py".  This is because Glk's
startup code doesn't have any way to grab arbitrary arguments, so I just had
it look for the "-" argument and pass the following value to Python.

Things to do:

- It doesn't deal at all well with errors.  If you call a function with the
  wrong number of arguments, for instance, you get a Python error, but then
  the Glk library gets confused.
- Using "- -i - filename.py" really sucks.  A better way should be found. 
- There should be a way to detect when the glk module's loaded under a
  regular Python interpreter instead of pyglk, and print a legible error. 

Source Files:

  Makefile
    runs the build process
  generate_glkmodule.py
    generates some Python classes and functions to wrap C structs, in
    glk.py.  (Basically, this does SWIG's -shadow option by hand.)
  glkc.h
	A version of glk.h hacked-up to allow SWIG to parse it correctly
  glkc.i
    SWIG interface file to generate glkc_wrap.c
  glkc_wrap.c
    C code for wrapping the Glk API.  Generated by SWIG.
  glkc_wrap.doc
    SWIG summaries of the functions it creates
  pyglk.c
	Source for the python-interpreter-linked with Glk
  ref_llhash.h
    A linked-list hash table for holding refcounts
  buf_llhash.h
    A linked-list hash table for holding buffers

Target Files:

  glk.py
    The glk module, which wraps the glkc module and adds a more Python-esque
    interface 
  libglkcmodule.so
    The glkc module, the low-level Python-to-C conversion of the Glk API
  pyglk
    A replacement python interpreter linked with Glk
  model.py
    Python port of model.c, the Glk example program
