BHSPitMonkey (talk | contribs) (→%hook: Added example) |
BHSPitMonkey (talk | contribs) m (→List of Logos Directives: Fixed a bunch of extra spacing) |
||
Line 22: | Line 22: | ||
===== %init ===== | ===== %init ===== | ||
%init | |||
%init([<class>=<expr>, …]) | |||
%init(Group[, [+|-]<class>=<expr>, …]) | |||
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. | 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. | ||
Line 34: | Line 34: | ||
===== %config ===== | ===== %config ===== | ||
%config(X=Y) | |||
Set a logos configuration flag - currently unused, but the only existing configurable flag is 'generator', and the only generator that exists is "MobileSubstrate" | Set a logos configuration flag - currently unused, but the only existing configurable flag is 'generator', and the only generator that exists is "MobileSubstrate" | ||
Line 56: | Line 56: | ||
===== %subclass ===== | ===== %subclass ===== | ||
%subclass Classname Superclass <Protocol, Protocol> | |||
Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported. | Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported. | ||
Line 62: | Line 62: | ||
===== %group ===== | ===== %group ===== | ||
%group Groupname | |||
Begin a hook group (for conditional initialization or code organization) with the name ''Groupname''. All ungrouped hooks are in the implicit "_ungrouped" group. | Begin a hook group (for conditional initialization or code organization) with the name ''Groupname''. All ungrouped hooks are in the implicit "_ungrouped" group. | ||
Line 68: | Line 68: | ||
===== %class ===== | ===== %class ===== | ||
%class Class | |||
Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group. | Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group. | ||
Line 74: | Line 74: | ||
===== %new ===== | ===== %new ===== | ||
%new(signature) | |||
Add a new method to a hooked class or subclass. | Add a new method to a hooked class or subclass. | ||
Line 80: | Line 80: | ||
===== %ctor ===== | ===== %ctor ===== | ||
%ctor { … } | |||
Generate an anonymous constructor (of default priority). | Generate an anonymous constructor (of default priority). | ||
Line 86: | Line 86: | ||
===== %end ===== | ===== %end ===== | ||
%end | |||
Close a hook/subclass/group block. | Close a hook/subclass/group block. | ||
Line 94: | Line 94: | ||
===== %c ===== | ===== %c ===== | ||
%c(Class) | |||
Effectively evaluates to Class, at runtime. Technically, creates $Class and populates it when the "_ungrouped" group is initialized. | Effectively evaluates to Class, at runtime. Technically, creates $Class and populates it when the "_ungrouped" group is initialized. | ||
Line 100: | Line 100: | ||
===== %orig ===== | ===== %orig ===== | ||
%orig | |||
%orig(args) | |||
Call the original hooked method. Doesn't function in a %new'd method. Works in subclasses, strangely enough, because MobileSubstrate will generate a supercall closure at hook time. (If the hooked | Call the original hooked method. Doesn't function in a `%new`'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 and _cmd, Logos does this for you. | 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` and `_cmd`, Logos does this for you. | ||
===== %log ===== | ===== %log ===== | ||
%log | |||
Dump the method arguments to syslog. | Dump the method arguments to syslog. | ||
[[Category:Development Tools]] | [[Category:Development Tools]] |
Revision as of 08:04, 24 July 2011
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.
Using Logos
Examples
Write me!
List of Logos Directives
Initialization
%init
%init %init([<class>=<expr>, …]) %init(Group[, [+|-]<class>=<expr>, …])
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.
Block-level
The directives in this category open a block of code which must be closed by an %end directive (shown below).
%config
%config(X=Y)
Set a logos configuration flag - currently unused, but the only existing configurable flag is 'generator', and the only generator that exists is "MobileSubstrate"
%hook
%hook Classname
Open a hook block for the class named Classname.
Here's a trivial example:
%hook SBApplicationController -(void)uninstallApplication:(SBApplication *)application { NSLog(@"Hey, we're hooking uninstallApplication:!"); %orig; return; } %end
%subclass
%subclass Classname Superclass <Protocol, Protocol>
Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported.
%group
%group Groupname
Begin a hook group (for conditional initialization or code organization) with the name Groupname. All ungrouped hooks are in the implicit "_ungrouped" group.
%class
%class Class
Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.
%new
%new(signature)
Add a new method to a hooked class or subclass.
%ctor
%ctor { … }
Generate an anonymous constructor (of default priority).
%end
%end
Close a hook/subclass/group block.
Inline
%c
%c(Class)
Effectively evaluates to Class, at runtime. Technically, creates $Class and populates it when the "_ungrouped" group is initialized.
%orig
%orig %orig(args)
Call the original hooked method. Doesn't function in a `%new`'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` and `_cmd`, Logos does this for you.
%log
%log
Dump the method arguments to syslog.