Dev:Logos

Logos is a component of the Theos development suite that allows method hooking code to be written easily and clearly, using a set of special preprocessor directives.

Overview
The syntax provided by Logos greatly simplifies the development of MobileSubstrate extensions ("tweaks") which can hook other methods throughout the OS. In this context, "method hooking" refers to a technique used to replace or modify methods of classes found in other applications on the phone.

Getting Logos
Logos is distributed with Theos, and you can use Logos' syntax in any Theos-built project without any extra setup. For more information about Theos, visit its page.

Block-level
The directives in this category open a block of code which must be closed by an %end directive (shown below). These should not exist within functions or methods.

%group
Begin a hook group (for conditional initialization or code organization) with the name Groupname. All ungrouped hooks are in the implicit "_ungrouped" group.

Grouping can be used to manage backwards compatibility with older code:

%hook
Open a hook block for the class named Classname.

Can be inside a %group block.

Here's a trivial example:

%new
Add a new method to a hooked class or subclass. signature is the Objective-C type encoding for the new method; if it is omitted, one will be generated.

Can be inside a %group block.

%subclass
Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported (use associated objects). The %new specifier is needed for a method that doesn't exist in the superclass. To instantiate an object of the new class, you can use the %c operator.

Can be inside a %group block.

Here's an example:

%end
Close a group/hook/subclass block.

Top level
The directives in this category should not exist within a group/hook/subclass block.

%config
Set a logos configuration flag.

Configuration Flags
dump to the perl source feature is removed since this commit.
 * generator
 * MobileSubstrate
 * generate code that uses MobileSubstrate for hooking.
 * internal
 * generate code that uses only internal Objective-C runtime methods for hooking.
 * warnings
 * none
 * suppress all warnings
 * default
 * non-fatal warnings
 * error
 * make all warnings fatal
 * dump
 * yaml
 * dump the internal parse tree in YAML format
 * perl
 * dump the internal parse tree in a format suitable for evaluation as perl source.

%ctor
Generate an anonymous constructor (of default priority).

%dtor
Generate a deconstructor

Function level
The directives in this category should only exist within a function block.

%init
Initialize a group (or the default group). Passing no group name will initialize "_ungrouped", and passing class=expr arguments will substitute the given expressions for those classes at initialization time. The + sigil (as in class methods in Objective-C) can be prepended to the classname to substitute an expression for the metaclass. If not specified, the sigil defaults to -, to substitute the class itself. If not specified, the metaclass is derived from the class. The class name replacement is specially useful for classes that contain characters that can't be used as the class name token for the %hook directive, such as spaces and dots.

Usage:

%class
Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.

%c
Evaluates to Class at runtime. If the + sigil is specified, it evaluates to MetaClass instead of Class. If not specified, the sigil defaults to -, evaluating to Class.

%orig
Call the original hooked method. Doesn't function in a %new</tt>'d method. Works in subclasses, strangely enough, because MobileSubstrate will generate a supercall closure at hook time. (If the hooked method doesn't exist in the class we're hooking, it creates a stub that just calls the superclass implementation.) args is passed to the original function - don't include self</tt> and _cmd</tt>, Logos does this for you.

%log
Dump the method arguments to syslog. Typed arguments included in %log</tt> will be logged as well.

File Extensions for Logos
xi or xmi files can use Logos directives in #define macros.

Splitting Logos Hooking Code Across Multiple Files
By default, the Logos pre-processor will only process one .xm file at build time. However, it is possible to split the Logos hooking code into multiple files. First, the main file has to be renamed to an .xmi file. Then, other .xm files can be included in it using the #include directive. The Logos pre-processor will add those files to the main file before processing it.

logify.pl
You can use logify.pl to create a Logos source file from a header file that will log all of the functions of that header file. Here is an example of a very simple Logos tweak generated by logify.pl

Given a header file:

You can find logify.pl at $THEOS/bin/logify.pl and you would use it as so:

The resulting output should be: