Glk is an attempt to define a portable API (programming interface) for applications with text UIs (user interfaces.)
Rather than go into a detailed explanation of what that means, let me give examples from the world of text adventures. TADS and Infocom's Z-machine have nearly identical interface capabilities; each allows a program to...
and so on. However, the implementation of these capabilities vary widely between platforms and operating systems. Furthermore, this variance is transparent to the program (the adventure game.) The game does not care whether output is displayed via a character terminal emulator or a GUI window; nor whether input uses Mac-style mouse editing or EMACS-style control key editing.
On the third hand, the user is likely to care deeply about these interface decisions. This is why there are Mac-native interpreters on Macintoshes, pen-controlled interpreters on Newtons and Pilots, and so on -- and (ultimately) why there Macintoshes and Pilots and X-windows platforms in the first place.
On the fourth hand, TADS and Inform are not alone; there is historically a large number of text adventure systems. Most are obsolete or effectively dead; but it is inevitable that more will appear. Users want each living system ported to all the platforms in use. Users also prefer these ports to use the same interface, as much as possible.
This all adds up to a pain in the ass.
Glk tries to draw a line between the parts of the text adventure world which are identical on all IF systems, and different on different operating systems, from the parts which are unique to each IF system but identical in all OSs. The border between these two worlds is the Glk API.
My hope is that a new IF system, or existing ones which are less-supported (Hugo, AGT, etc) can be written using Glk for all input and output function. The IF system would then be in truly portable C. On the other side of the line, there would be a Glk library for each operating system and interface (Macintosh, X-windows, curses-terminal, etc.) Porting the IF system to every platform would be trivial; compile the system, and link in the library.
Glk can also serve as a nice interface for applications other than games -- data manglers, quick hacks, or anything else which would normally lack niceties such as editable input, macros, scrolling, or whatever is native to your machine's interface idiom.
Java is the ultimate tool for cross-platform development. You wanna buy a bridge? How about some shares of Sun stock? Onna stick?
Java has several disadvantages for my purpose. First, it is resource-intensive. It is unlikely that Java will ever run on a 386/68030 generation computer, which is perfectly adequate for text IF. Java may run on a palmtop, but the standard Java library will not. It is also impossible for a single person to port Java to a new platform -- both legally and practically, Java is in the control of large corporations.
Secondly, Java allows too fine-grained a control over the interface. It is not possible to create a text interface using the standard Java library; it is not even really possible to make a graphical interface in the Mac idiom. Java programs have their own Java-specific interface idiom. This trend is accelerating.
On the other hand, it is perfectly possible to implement a Glk library in Java and using the Java interface idiom. This would allow a Glk-based IF system to be easily ported to any machine that runs Java -- if the player likes the way Java looks, of course.
You can think of Glk as an IF virtual machine, without the virtual machine part. The "machine" is just portable C code.
It is not inconceivable that a new IF virtual machine might be designed to go along with Glk. This VM would use Glk as its interface; each Glk call would correspond to an input/output opcode of the VM.
For more discussion of this approach, see section 10.3, "Glk and the Virtual Machine".
Glk does not handle the things which should be handled by the program (or the IF system, or the virtual machine) which is linked to Glk. This means that Glk does not address
This document defines the Glk API. I have tried to specify exactly what everything does, what is legal, what is illegal, and why.
Sections in square brackets [like this] are notes. They do not define anything; they clarify or explain what has already been defined. If there seems to be a conflict, ignore the note and follow the definition.
[Notes with the label "WORK" are things which I have not yet fully resolved. Your comments requested and welcome.]
This document is written for the point of view of the game programmer -- the person who wants to use the Glk library to print text, input text, and so on. By saying what the Glk library does, of course, this document also defines the task of the Glk programmer -- the person who wants to port the Glk library to a new platform or operating system. If the Glk library guarantees something, the game programmer can rely on it, and the Glk programmer is required to support it. Contrariwise, if the library does not guarantee something, the Glk programmer may handle it however he likes, and the game programmer must not rely on it. If something is illegal, the game programmer must not do it, and the Glk programmer is not required to worry about it. [It is preferable, but not required, that the Glk library detect illegal requests and display error messages. The Glk library may simply crash when the game program does something illegal. This is why the game programmer must not do it. Right?]
Hereafter, "Glk" or "the library" refers to the Glk library, and "the program" is the game program (or whatever) which is using the Glk library to print text, input text, or whatever. "You" are the person writing the program. "The player" is the person who will use the program/Glk library combination to actually play a game. Or whatever.
The Glk API is declared in a C header file called "glk.h". Please refer to that file when reading this one.