NOTE: This article has been depreciated along with all of the original ORLib Manual efforts. The newer manual can be found at http://www.onyxring.com/ORLibDocToc.aspx
Part A : Overview and Setup
Welcome to the ORLibrary Guide/Tutorial. The purpose of this guide is to explain the function of the ORLibrary, give working examples of what it can accomplish, and demonstrate how it can be leveraged to create more detailed games with less effort. This guide serves a dual purpose in that it can be used as both a reference and a tutorial.
As a reference, this text lists the most prevalent entries in the ORLibrary, describes each, and gives examples of its use.
The examples, taken as a whole, form a complete step-by-step tutorial and develop a complete game from the ground up.
1.1 What is ORLib?
The ORLibrary is based upon framework The ORLibrary is based upon framework theory discussed in the article "Building a Personal Library." It is a collection of objects, routines and enhancements that sits on top of the standard library. All the entries in the library are opt-in, meaning they have no effect whatsoever on the final produced code unless they have been selected for use. Using the ORLibrary framework simply makes them accessible.
1.2 Newbie ~=Newbie
This guide is intended to be usable by both newbie and advanced coder alike, but the term newbie carries a breadth of possible interpretations. First-time Informer's will have trouble getting much use from this text. If you are a newbie that has no idea what a for loop is, then this guide is not for you. If you have no idea what an object is, then this guide is not for you. If you cannot write a basic program in Inform, then this guide is not for you.
This is NOT a guide on programming in Inform. As such, it will not directly discuss topics such as "What are properties and attributes?" or "What does the Parser.h file do?" or "How do I implement a loop?" Further, it is not a tutorial on using the Standard Library, so questions such as "What is the switchable attribute?" and "How do I change a default message?" and "What is a before property?" are also not directly answered. It may be that you can find answers to these questions buried in the text of this guide, but these topics are only touched upon with the assumption that you already know them or at least have a basic understanding of their theory.
Don't despair if you do not have this understanding yet. There are a number of resources at your disposal. The most notable is the Inform Developer's Manual, written by the author of the Inform language, Graham Nelson. Additionally, the OnyxRing site hosts a guide written by other developers that you may find useful.
2 Setting up for ORLibrary use
Setting up ORLibrary is a trivial matter. It can be setup in virtually any directory and, with the addition of a couple of command-line properties, can be used immediately.
2.1 Where do I get ORLib?
The ORLibrary finds it's home at the OnyxRing website. The following URL joins to the ORLibrary page:
This page holds the most recent iteration of the ORLibrary. That is, the most recent version of each entry as well as any alpha entries that are currently being tested.
By far, the easiest way to download the ORLibrary is to get the ORLib_complete.zip file, which contains a snapshot of all the non-beta library entries as of the date-stamp indicated in the description.
2.2 Where do I install ORLib?
The best place to install the ORLibrary is entirely a matter of opinion. It can be anywhere that the Inform compiler can reach, from a networked drive, to your home directory. Some developers simply drop the ORLibrary files in the same directory as the standard library files. This saves them the initial fuss with command-line parameters but only at the cost of separation of code. This is not recommended.
Generally, it is a good idea to give the ORLibrary its own directory, possibly on the same directory tier as the standard library files. The important thing to remember is that this directory will need to be added as a parameter (or switch) to the Inform compiler's command-line.
2.3 ICL Settings
There are a couple of ICL options need to be made in order to have Inform compile in the ORLibrary. Depending on how the your development environment is set up, these might be put in a batch file (or other scripting file), or simply be part of a macro that runs when you press a special button in the IDE of your choosing. Preferably, these may be placed in a common ICL file, but for simplicity the examples given below are given in the context of command-line options.
See the Inform Developer's Manual or the compiler's –h1 option for specifics about ICL files.
2.3.1 Telling Inform where ORLibrary is installed
The ICL variable that tells the compiler where the ORLibrary files are installed is generally already used to specify the location of the standard library. It is the variable "include_path" and is most often set on the command line with the familiar "+ command" notation. Additional directories can be added to this variable by separating them with a comma. The following example shows one possibility as it might exist on a Microsoft platform:
2.3.2 Specifiying the OREnglish LDF
Strictly speaking, the second modification, which includes the OREnglish language definition file, is optional. Many basic library entries can be used without it, but the flexibility of this entry and its immediate transparency when implemented make it a veritable staple in the ORLibrary framework. Many of the library entries depend upon it entirely and will not work without it. The tutorial aspect of this guide expects its existence as well. OREnglish and ORPronouns (a dependency of OREnglish), will be among the first entries touched upon in this guide.
Inclusion of the OREnglish file can be accomplished with the following command line addition:
Note: A complete Inform command-line example is shown in section 3.1.
3 Verifying ORLibrary installation
Verifying that ORLibrary is installed is a simple matter and can be accomplished by checking the compiler's output. We'll compile the OR_Blankgame.inf file to do this.
The OR_blankgame.inf file that comes with ORLibrary has several features that make it an ideal starting point for an ORLibrary program. These will be covered more thoroughly in later sections. For now, simply compiling the file with the above-specified ICL settings (as in the following example)...
...should render output similar to the following:
If errors occur, or if the results are not similar to the above, then go back and review section 2. Most problems that occur are usually related to directory locations and invalid attempts to signify to the compiler where files are located.
3.2 Compiler Output Verification
If the ORLibrary is correctly installed and functional, then the compiler output should tip you off immediately. Even without using any ORLibrary entries, the library framework alone leaves an obvious signature in the output.
3.2.1 Checking for framework reference
If you are referencing the ORLibrary correctly, then right at the top of the compiler output will be the following text:
Additionally, the compiler will list the steps it goes through during the compilation of the ORLibrary files. This can be seen with lines that are similar to:
The four sections that are referred to in the output will be made clear in the section entitled "Adding your own entries".
3.2.2 Checking for OREnglish
Lines similar to the following signify that a library entry is being compiled:
Since the OREnglish library entry, in particular, is not compiled in the same fashion as other library entries (it is included by the parserm.h file, which is included by the parser.h file) and is, in fact, quite significant to the ORLibrary as a whole, the compiler output indicating its presence is highlighted by the inclusion of two lines. The first line appears with the text that indicates compilation of OREnglish is under way. For this reason, making sure that the ICL command was processed and therefore OREnglish language definition file was processed is also easily determined by checking the output. The following lines will appear if it has:
The second line appears with text that indicates that the compilation of OREnglish has been completed:
All compiler output generated during the compilation of OREnglish will appear between these two lines. A glance will tell you that including OREnglish also includes two additional all library entries. We'll talk about this next...
3.2.3 Automatic Dependencies
In addition to OREnglish, you may notice an unexpected side effect: three unselected library entries are pulled in. It is common practice for library entries to attempt to meet their own dependencies. That is, needed entries will often be pulled into the compilation process automatically.
Strictly speaking, the first, ORBanner, is not really a dependency. The framework itself pulls this in to implement versioning functionality. The additional two library entries that are pulled in are ORTextFormatting and ORPronoun. These are dependencies of OREnglish and are included by that module.
After detecting that a dependency is not referenced, and forcing it to be included, an entry will then volunteer what it has done. This way, the developer is never left unaware of the source of an unexpected entry's inclusion. The following lines in the previous output example indicate this:
A quick view of the output will show that these entries where included while processing the OREnglish file.
4 Philosophies to keep in mind
There are a few common practices that should be kept in mind when coding. These are practices are good ideas all of the time, even when not leveraging the ORLibrary, but they are especially useful when you are:
4.1 Layers (or base classes) by Inheritance
Using inheritance (creating derived classes) gives us the ability to design layers for common changes. This principal is especially helpful when dealing with objects and yields benefits that cannot always be seen at first glance. This is not a guide on OOP techniques but to briefly skim the surface:
- Layers allow for easy broad changes. Changing code in a single location can affect dozens, or even hundreds, of objects. This provides us with the ability to make broad-scoped changes in seconds that might otherwise take us weeks.
- Layers allows for a common place to implement similarities. This can help eliminate the need to implement common code. Certain properties or attributes are, by default used, all the time. Implementing them at the base class layer causes them to be inherited automatically by all derived objects and can shrink the size of the final program.
4.2 Behavior Granularity by Multiple Inheritance
I have always felt that Multiple Inheritance (creating objects derived from two or more classes at the same time) was an under appreciated technology. It is only by understanding and leveraging MI that a developer can truly weld the full power OOP provides. In Inform, MI is best suited for the design of behaviors, that is, creating a collection of unrelated objects that each do specific and unrelated thing, then applying them each to a single class to create an object that can do several things.
One example of this can be seen in the ORNPC class and its related classes each of which encapsulate different NPC behaviors. By writing NPC behaviors in separate classes we've given the developer a granularity that was not available previously. It is just as easy to write an NPC that walks around and talks as it is an NPC that simply talks, or one that simply walks around. More on this will be discussed in the section on NPCs "Advanced Library Entries".
Table of Contents
Part B: Basic ORLibrary