Obey

Obey is the scripting format of Acorn’s RISC OS. An Obey file is a plain text file of star commands, the same commands you would type at RISC OS’s * prompt. It has its own file type (&FEB) and a command (*Obey) to run it. It sits somewhere between an MS-DOS batch file and a Unix shell script, though it is much smaller than either. There are no loops, and conditional logic is borrowed from the command line itself.

What makes Obey matter is where it is used. Every RISC OS application is a directory whose name starts with !, and double-clicking it runs an Obey file inside it called !Run. So for more than thirty years almost every program launched on an Archimedes, Risc PC, Iyonix or Raspberry Pi running RISC OS has started with a few lines of Obey.

History & Origins

Arthur and Command files (1987)

The Acorn Archimedes launched in 1987 with an operating system called Arthur. Arthur, like the BBC Micro’s MOS before it, could script the command line only with Command files. These were text files fed to the computer with *Exec, as though their contents were being typed at the keyboard. The Arthur Programmer’s Reference Manual (November 1987) lists every file type defined at the time. Command is &FFE, and there is no Obey type.

Feeding a file in as keystrokes has awkward consequences, which Acorn’s later manual spells out. A Command file “is treated as if it were typed at the keyboard (and hence usually appears on the screen)”. It cannot take parameters. Command files cannot be nested. And because they really are keystrokes, a Command file that starts BASIC goes on to type its remaining lines into BASIC.

RISC OS 2 (1988-1989)

Arthur’s successor, developed during 1988 as “Arthur 2”, was renamed RISC OS. Chris’s Acorns dates the RISC OS 2.00 ROM to 5 October 1988, and it went on sale in April 1989. It introduced the desktop application directory, and with it the Obey module.

Archive magazine’s note on what changed from Arthur 1.20 to RISC OS 2.00 lists “the Obey module, somewhat like nestable Exec files”. It adds that “boot sequences can be written far more easily on RISC OS 2.00 because of the Obey file type”. In January 1989 Personal Computer World’s review of RISC OS explained the new application structure: !Run and !Boot “belong to a new file type called ‘obey’ files”, and “Obey files can find out what directory they were activated from by inspecting an operating system variable called Obey$Dir”.

The master list of languages gives 1987 for Obey. That is the year of Arthur, which had no Obey files, so this page uses 1988, the date of the RISC OS 2.00 ROM.

Design Philosophy

Obey is a thin layer over the RISC OS command line interpreter. It has no syntax of its own beyond a few rules:

1. One command per line. Each line is passed to the command line interpreter, the same as if it were typed at the * prompt (opened with F12 on the desktop). The leading * is optional.
2. Read the file, don’t type it. Unlike a Command file, an Obey file is read directly and does not pretend to be keyboard input. A program it starts does not consume the rest of the script.
3. Know where you are. Running an Obey file sets Obey$Dir to the directory it was run from. Applications can therefore be moved anywhere on any disc and still find their own resources.
4. Stop on error. An Obey file stops when an error is returned to the Obey module. The Error command is therefore the usual way to abandon a script with a message.

Anything more than this, such as variables, aliases and conditionals, belongs to the command line interpreter, not to Obey.

Key Features

A typical !Run file

RISC OS Open’s introduction to Obey uses this example of an application’s !Run file:

| !Run for MyApp
| January 2021
Set MyApp$Dir <Obey$Dir>
WimpSlot 32K
Run <MyApp$Dir>.!RunImage

Lines starting with | are comments. Set stores the application’s location in a system variable. <...> expands a variable. WimpSlot reserves memory for the program. Run starts the real program, !RunImage.

Parameters

An Obey file can take arguments. %0 is the first, %1 the second, and so on. %*0 means “the first argument and everything after it”. The Programmer’s Reference Manual’s example is a file called Display:

FileInfo %0
Type %0

Typing *Display MyFile runs FileInfo MyFile and then Type MyFile. A literal % is written %%. You need this when an Obey file defines an alias that takes its own parameters:

Set Alias$more %echo |<14>|m %type -tabexpand %%*0|m %echo |<15>

This line, also from the PRM, creates a new command more that turns on paged mode, types a file and turns paged mode off again.

Conditionals and version checks

Obey has no control flow of its own. In practice, scripts rely on two command-line tools that RISC OS provides:

If "<MyApp$Running>" <> "" Then Error MyApp is already running
RMEnsure UtilityModule 3.10 Error This version of MyApp requires RISC OS 3.1 or later.

RMEnsure runs the rest of its line only if a module is missing or too old. Its other common use, loading a module if it isn’t already present, appears in nearly every !Run file.

The *Obey command

*Obey [[-v][-c][-m] [filename [parameters]]]

The PRM notes that -v and -c “are not available in RISC OS 2”. -m appears in RISC OS Open’s current documentation. *Obey can also force any text file to run as an Obey file, whatever its file type. With no arguments it ends the current Obey file and any parent Obey files. Obey files can call other Obey files, up to a limited depth that the PRM gives as “currently 20, although you should not rely upon this”.

File-type dispatch

Obey fits into RISC OS’s general mechanism for running files by type. The system defines:

Set Alias$@RunType_FEB Obey %*0
Set File$Type_FEB Obey

So typing an Obey file’s name at the prompt, or double-clicking it on the desktop, becomes *Obey <file> <args>. The same mechanism lets a user type *!AppDir to run the !Run file inside an application directory.

Evolution

The Obey module has changed very little since 1988. The RISC OS Open source repository, whose history begins with an import from the RISC OS 3.60 sources in November 1996, records these changes:

Edit, RISC OS’s text editor, has a Create > Obey option. Under RISC OS 2 the PRM notes that you instead had to set the file type with *SetType after saving.

Current Relevance

Obey is still part of RISC OS 5, the open-source branch maintained by RISC OS Open. The source was relicensed under Apache 2.0 in October 2018, and RISC OS 5.30 was released on 27 April 2024. It runs on Raspberry Pi boards among other hardware. Nobody chooses Obey as a general-purpose scripting language, because nothing in RISC OS can avoid it: every application still starts from a !Run Obey file, and RISC OS Open’s wiki still teaches Obey files as the way to make simple scripts.

Larger RISC OS scripts are usually written in BBC BASIC instead, which is built into every RISC OS machine and has the loops, procedures and string handling that Obey leaves out.

Why It Matters

Obey solved a specific problem in a lasting way. Because Obey$Dir tells every script where it lives, a RISC OS application can be a self-contained directory: drag it to any disc, double-click it and it works, with no installer and no fixed paths. That design came from the interplay of three things introduced together in RISC OS 2: application directories, file-type dispatch and the Obey module. It is a large part of why RISC OS applications are still installed by copying a folder.

Sources

• Acorn, Archimedes Programmer’s Reference Manual, Volume 1 (Arthur, November 1987): file-type list and *Exec/Command files
• RISC OS Programmer’s Reference Manual, Volume 4, chapter “Command scripts” (riscos.com edition): Obey vs Command files, Obey$Dir, parameters, *Obey syntax, !Boot/!ArmBoot
• Archive magazine, “Changes” (Arthur 1.20 to RISC OS 2.00), on the Archive Magazine 1995 CD
• “RISC OS”, Personal Computer World, January 1989
• RISC OS Open wiki: *Obey, Introduction to Obey, CLI Basics
• RISC OS Open GitLab, RiscOS/Sources/Programmer/Obey (tag list)
• Chris’s Acorns, RISC OS versions (ROM dates)