Orion

https://orion.theos.dev/
Admin
Orion is a DSL designed to make it entirely effortless to interact with Objective-C's dynamic...
Tokens:21,351
Snippets:303
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build and Install Orion Tweak

Source: https://orion.theos.dev/getting-started

Execute the `make do` command in your tweak's project directory to build, package, and install the tweak onto your device. This command automates the entire process.

```bash
~/mytweak $ make do
> **Making all for tweak MyTweak…**
==> **Preprocessing Sources/MyTweak/Tweak.x.swift…**
==> **Preprocessing Sources/MyTweak/Tweak.x.swift…**
==> **Compiling Sources/MyTweak/Tweak.x.swift (arm64e)…**
==> **Compiling Sources/MyTweak/Tweak.x.swift (arm64)…**
==> **Generating MyTweak-Swift.h (arm64)…**
==> **Generating MyTweak-Swift.h (arm64e)…**
==> **Compiling Sources/MyTweakC/Tweak.m (arm64e)…**
==> **Compiling Sources/MyTweakC/Tweak.m (arm64)…**
==> **Linking tweak MyTweak (arm64)…**
==> **Linking tweak MyTweak (arm64e)…**
==> **Generating debug symbols for MyTweak…**
==> **Generating debug symbols for MyTweak…**
==> **Merging tweak MyTweak…**
==> **Signing MyTweak…**
> **Making stage for tweak MyTweak…**
dm.pl: building package `com.kabiroberai.mytweak:iphoneos-arm' in `./packages/com.kabiroberai.mytweak_0.0.1-1+debug_iphoneos-arm.deb'
==> **Installing…**
(Reading database ... 3540 files and directories currently installed.)
Preparing to unpack /tmp/_theos_install.deb ...
Unpacking com.kabiroberai.mytweak (0.0.1-1+debug) ...
Setting up com.kabiroberai.mytweak (0.0.1-1+debug) ...
==> **Unloading 'VLC for iOS'…**


```

--------------------------------

### Example: Hooking the atoi function

Source: https://orion.theos.dev/typealiases/functionhook

This example demonstrates how to hook the C standard library function `atoi`. It modifies the behavior for the input "1234" to return 4321, while other inputs are handled by the original function.

```swift
class AtoiHook: FunctionHook {
    static let target = Function.symbol("atoi", image: nil)

    func function(_ string: UnsafePointer<Int8>) -> Int32 {
        if String(cString: string) == "1234" {
            return 4321
        } else {
            return orig.function(string)
        }
    }
}
```

--------------------------------

### Hooking Initializers with initWithFrame

Source: https://orion.theos.dev/typealiases/classhook

Example of hooking an initializer for a UIView. The original initializer is called via `orig.initWithFrame(frame)`, and the target object is then configured before being returned.

```swift
class ViewHook: ClassHook<UIView> {
    func initWithFrame(_ frame: CGRect) -> Target {
        let target = orig.initWithFrame(frame)
        // configure target
        return target
    }
}
```

--------------------------------

### Hooking UILabel setText

Source: https://orion.theos.dev/typealiases/classhook

An example demonstrating how to hook the `setText` method of `UILabel` to change the text to 'hello'. The original implementation is called via `orig.setText`.

```swift
class MyHook: ClassHook<UILabel> {
    func setText(_ text: String) {
        orig.setText("hello")
    }
}
```

--------------------------------

### Swift Example of Updating Orion Error Handler

Source: https://orion.theos.dev/Functions/updateOrionErrorHandler%28_%3A%29_%24syys5NeverOSSyXK_s12StaticStringVSutcABSSyXK_ADSutcXEcD.html

Demonstrates how to update the Orion error handler to log errors before calling the previous handler. This example shows a common pattern for integrating custom error logging.

```swift
updateOrionErrorHandler { old in
    return { message, file, line in
        let str = message()
        // save (str, file, line) to a file
        old(str, file, line)
    }
}
```

--------------------------------

### Swift UILabel Text Hook Example

Source: https://orion.theos.dev/

This snippet demonstrates how to use Orion to hook a UILabel's setText method in Swift to change all label texts to 'hello'. It requires defining a ClassHook for UILabel.

```swift
class MyHook: ClassHook<UILabel> {
    func setText(_ text: String) {
        orig.setText("hello")
    }
}

```

--------------------------------

### Dynamic Member Lookup for Type Access

Source: https://orion.theos.dev/structs/dynamic

Use `Dynamic.TypeName` to get a `Dynamic` instance representing a type. This enables ergonomic access to Objective-C classes and protocols by name.

```swift
@dynamicMemberLookup
public struct Dynamic
```

--------------------------------

### Substrate()

Source: https://orion.theos.dev/enums/backends/substrate

Initializes the Substrate backend.

```APIDOC
## Substrate()

### Description
Initializes the Substrate backend.

### Declaration
Swift
```swift
public init()
```
```

--------------------------------

### Initialize Orion Tweak with nic.pl

Source: https://orion.theos.dev/getting-started

Use nic.pl with the tweak_swift template to create a new Orion tweak project. Provide the target application's bundle ID and name when prompted.

```bash
~ $ nic.pl
NIC 2.0 - New Instance Creator
------------------------------
  [1.] iphone/activator_event
  [2.] iphone/activator_listener
  [...]
  [16.] iphone/tweak
  [17.] iphone/tweak_swift
  [18.] iphone/tweak_with_simple_preferences
  [19.] iphone/xpc_service
Choose a Template (required): 17
Project Name (required): My Tweak
Package Name [com.yourcompany.mytweak]: com.kabiroberai.mytweak
Author/Maintainer Name [Your Name]: Kabir Oberai
[iphone/tweak_swift] MobileSubstrate Bundle filter [com.apple.springboard]: org.videolan.vlc-ios
[iphone/tweak_swift] List of applications to terminate upon installation (space-separated, '-' for none) [SpringBoard]: 'VLC for iOS' 
Instantiating iphone/tweak_swift in mytweak/...
Done.

```

--------------------------------

### Initialize DefaultBackend

Source: https://orion.theos.dev/protocols/defaultbackend

Initializes the backend with a default configuration. Use this when setting up a default backend for Orion.

```swift
init()
```

--------------------------------

### DefaultBackend Initialization

Source: https://orion.theos.dev/protocols/defaultbackend

Initializes the DefaultBackend with a default configuration.

```APIDOC
## init()

### Description
Initializes the backend with a default configuration.

### Declaration
Swift
```swift
init()
```
```

--------------------------------

### Initialize Internal Backend

Source: https://orion.theos.dev/enums/backends/internal

Initializes the Internal backend. This is the default constructor for the Internal backend.

```swift
public init()
```

--------------------------------

### Tweak Protocol Initialization

Source: https://orion.theos.dev/protocols/tweak

The `init()` method is the initializer and entry point for a Tweak. Use this to perform custom initialization before `DefaultGroup` is activated. Be cautious as this method is called at launch time and should not perform time-consuming tasks.

```APIDOC
## init()

### Description
The tweak’s initializer and entry point.
Use this method to perform any custom initialization behavior before `DefaultGroup` is activated. To perform initialization behavior after `DefaultGroup` is activated, implement `tweakDidActivate()` instead.

**Warning**: This method is called at launch time, even before `main` has been invoked. Do not synchronously perform any time-consuming tasks here, because they will make the target process launch slowly.

### Declaration
Swift
```swift
init()
```
```

--------------------------------

### Internal Backend Initialization

Source: https://orion.theos.dev/enums/backends/internal

Initializes the Internal backend. This backend uses Objective-C runtime functions ('swizzling') to apply method hooks.

```APIDOC
## init()

### Description
Initializes the Internal backend.

### Method
`init()`

### Declaration
Swift
```swift
public init()
```
```

--------------------------------

### Override UILabel setText Method

Source: https://orion.theos.dev/getting-started

Implement a custom setText function within a ClassHook to modify the text. Use `orig.setText` to call the original implementation with modified arguments. The example transforms text to uppercase and replaces spaces with an emoji.

```swift
// 1
func setText(_ text: String) {
    // 2
    orig.setText(
        // 3
        text.uppercased().replacingOccurrences(of: " ", with: "👏")
    )
}

```

--------------------------------

### Fishhook Backend Initialization

Source: https://orion.theos.dev/enums/backends/fishhook

Initializes the Fishhook backend with a specified underlying backend.

```APIDOC
## init(underlyingBackend:)

### Description
Initializes the Fishhook backend with the provided underlying backend.

### Parameters
- `_underlyingBackend_` - The backend to fall back to for non-function hooking.
```

--------------------------------

### Initializer: init(target:)

Source: https://orion.theos.dev/protocols/classhookprotocol

Initializes the type with the provided target instance. This initializer should not be overridden.

```APIDOC
## Initializer: init(target:)

### Declaration

```swift
init(target: Target)
```

**Description:**
Initializes the type with the provided target instance. Do not override this.
```

--------------------------------

### apply(descriptors:)

Source: https://orion.theos.dev/enums/backends/substrate

Applies a list of hook descriptors using the Substrate backend.

```APIDOC
## apply(descriptors:)

### Description
Applies a list of hook descriptors using the Substrate backend.

### Declaration
Swift
```swift
public func apply(descriptors: [HookDescriptor])
```
```

--------------------------------

### Initialize Fishhook Backend

Source: https://orion.theos.dev/enums/backends/fishhook

Initializes the Fishhook backend with a specified underlying backend. This underlying backend handles requests that are not function hooks.

```swift
public init(underlyingBackend: UnderlyingBackend)
```

--------------------------------

### Hooking NSObject init

Source: https://orion.theos.dev/typealiases/classhook

Demonstrates how to hook the `init` method of `NSObject` using backticks to escape the keyword. The initializer is called on `supr` or `orig`.

```swift
func `init`() -> Target.
```

--------------------------------

### Default Initialization (Conditional)

Source: https://orion.theos.dev/enums/backends/fishhook

Initializes the Fishhook backend with default settings, available when the underlying backend conforms to DefaultBackend.

```APIDOC
## init()

### Description
Initializes the Fishhook backend with default settings. This initializer is available when `UnderlyingBackend` conforms to `DefaultBackend`.
```

--------------------------------

### Initializer init(target:) Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

Initializes the type with the provided target instance. Do not override this.

```swift
init(target: Target)
```

--------------------------------

### Function.symbol (String image)

Source: https://orion.theos.dev/enums/function

An initializer for creating a Function case using a symbol name and an image path string. This is an equivalent to `.symbol(name, image: URL(fileURLWithPath: image))` but requires a non-nil image path.

```APIDOC
## Function.symbol(_:image:)

### Description
Equivalent to `.symbol(name, image: URL(fileURLWithPath: image))`. This initializer deliberately requires a non-nil `image` parameter, because allowing `nil` would cause ambiguity between this method and the enum case when passed `nil` as the second parameter. To use a `nil` image, invoke `symbol(_:String image:URL?)` instead, passing `URL?.none`.

### Declaration
Swift
```swift
public static func symbol(_ name: String, image: String) -> Function
```

### Parameters
` _name_ ` |  The name of the symbol.
` _image_ ` |  The path to the image in which the symbol is located.

### Return Value
The described `Function`.
```

--------------------------------

### Call Private Initializer

Source: https://orion.theos.dev/structs/dynamic

Use `alloc(interface:)` on a `Dynamic` instance of the class to obtain an object, then call the initializer method on it.

```swift
let obj = Dynamic.MyClass
    .alloc(interface: MyInterfaceC.self)
    .initWithString("hello")
```

--------------------------------

### Substrate Backend Declaration

Source: https://orion.theos.dev/enums/backends/substrate

Declares the Substrate backend struct, which conforms to the DefaultBackend protocol.

```swift
public struct Substrate : DefaultBackend
```

--------------------------------

### Syntactic Sugar for Instance Method Calls

Source: https://orion.theos.dev/structs/dynamic

If the class conforms to `NSObject`, use `as(interface:)` for a more concise way to call undeclared instance methods.

```swift
MyClass().as(interface: MyInterfaceA.self).someInstanceMethod()
```

--------------------------------

### Syntactic Sugar for Initializer Calls

Source: https://orion.theos.dev/structs/dynamic

If the class conforms to `NSObject`, you can use `MyClass` directly instead of `Dynamic.MyClass` for a more concise way to call private initializers.

```swift
MyClass.alloc(interface: MyInterfaceC.self).initWithString("hello")
```

--------------------------------

### Instance Method: deinitializer()

Source: https://orion.theos.dev/protocols/classhookprotocol

A function that is run before a `target` is deallocated. Use this to perform any cleanup before the target is deallocated. The default implementation returns `DeinitPolicy.callOrig`.

```APIDOC
## Instance Method: deinitializer()

### Declaration

```swift
func deinitializer() -> DeinitPolicy
```

**Description:**
A function which is run before a `target` is deallocated. Use this to perform any cleanup before the target is deallocated. The default implementation is equivalent to simply returning `DeinitPolicy.callOrig`.

**Important:** You **must not** call `orig.deinitializer()` or `supr.deinitializer()` in this method. Instead, return the appropriate deinit policy.

### Return Value
A `DeinitPolicy` representing the action to perform next.
```

--------------------------------

### apply(descriptors:)

Source: https://orion.theos.dev/protocols/backend

Hooks the provided functions and methods with the given descriptors.

```APIDOC
## apply(descriptors:)

### Description
Hooks the provided functions and methods.

### Declaration
Swift
```swift
func apply(descriptors: [HookDescriptor])
```

### Parameters
- `descriptors` ([HookDescriptor]): The descriptors for the hooks to be applied.
```

--------------------------------

### Extension Method: orig (Instance)

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the original instance methods of the hooked class.

```APIDOC
## Extension Method: orig (Instance)

### Declaration

```swift
public var orig: Self { get }
```

**Description:**
A proxy to access the original instance methods of the hooked class.
```

--------------------------------

### Accessing Objective-C Instance Variables with Ivars

Source: https://orion.theos.dev/structs/ivars

Demonstrates basic usage of the Ivars struct for reading and writing Objective-C instance variables using dynamic member lookup. Ensure the ivar exists to avoid crashes.

```swift
let object = MyObject(foo: 5)
Ivars<Int>(object)._foo // 5
Ivars(object)._foo = 7
print(object.foo) // 7
```

--------------------------------

### Initialize Dynamic with String Name

Source: https://orion.theos.dev/structs/dynamic

An instance of `Dynamic` can be obtained by passing the type name as a string, providing an alternative to dynamic member lookup.

```swift
Dynamic("Foo.Bar")
```

--------------------------------

### as(interface:protocol:)

Source: https://orion.theos.dev/structs/dynamic

Returns the class referred to by the callee as if it conformed to a given interface. Instance methods on the interface should be declared as instance methods.

```APIDOC
## as(interface:protocol:)

### Description
Returns the class referred to by the callee as if it conformed to the given interface. Methods on the interface should be declared as **instance** methods.

### Method
func `as`<I>(interface: I.Type, protocol: Protocol? = nil) -> I

### Parameters
- **interface** (I.Type) - The interface to which the class should be cast.
- **protocol** (Protocol?) - If the interface is a private protocol or is otherwise invisible to Objective-C via `NSClassFromString`, you may need to pass the protocol a second time as this parameter. For example, `Dynamic.MyClass.as(interface: MyInterface.self, protocol: MyInterface.self)`.

### Return Value
The class, “cast” to the interface.
```

--------------------------------

### Initialize Dynamic with Class Type

Source: https://orion.theos.dev/structs/dynamic

You can initialize `Dynamic` by passing an existing Objective-C class directly, which is useful when the class is already known in Swift.

```swift
Dynamic(NSString.self)
```

--------------------------------

### Tweak Did Activate Method

Source: https://orion.theos.dev/protocols/tweak

Called after all of the tweak’s hooks that are in DefaultGroup have been activated. The default implementation does nothing.

```swift
func tweakDidActivate()
```

--------------------------------

### Static Property: protocols

Source: https://orion.theos.dev/protocols/classhookprotocol

An array of protocols that should be added to the target class. The default value is an empty array.

```APIDOC
## Static Property: protocols

### Declaration

```swift
static var protocols: [Protocol] { get }
```

**Description:**
An array of protocols which should be added to the target class. The default value is an empty array.

**Warning:** Do not attempt to access `target` in the getter for this property, as that will lead to infinite recursion.
```

--------------------------------

### Extension Method: supr (Instance)

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the hooked class’ superclass instance methods.

```APIDOC
## Extension Method: supr (Instance)

### Declaration

```swift
public var supr: Self { get }
```

**Description:**
A proxy to access the hooked class’ superclass instance methods.
```

--------------------------------

### Backend Property Declaration

Source: https://orion.theos.dev/protocols/tweakwithbackend

Declares the static property 'backend' which provides the custom Backend instance.

```swift
static var backend: BackendType { get }
```

--------------------------------

### Orion Tweak Project File Structure

Source: https://orion.theos.dev/getting-started

Overview of the files generated by Theos for an Orion tweak project. Each file serves a specific purpose in building and packaging the tweak.

```text
- Makefile
- MyTweak.plist
- control
- Package.swift
- Sources
  - MyTweak
    - Tweak.x.swift
  - MyTweakC
    - [...]

```

--------------------------------

### description Property

Source: https://orion.theos.dev/enums/orionhookerror

Provides a string representation of the error.

```swift
public var description: String { get }
```

--------------------------------

### TweakWithBackend Protocol Declaration

Source: https://orion.theos.dev/protocols/tweakwithbackend

Defines the TweakWithBackend protocol, which inherits from the Tweak protocol.

```swift
public protocol TweakWithBackend : Tweak
```

--------------------------------

### Declaring and Activating Hook Groups

Source: https://orion.theos.dev/protocols/hookgroup

Defines custom hook groups and demonstrates their activation within a tweak's initialization. Hooks are assigned to groups using a typealias for `AnyHook.Group`. Custom groups are activated by creating an instance and calling `activate()`, potentially passing arguments.

```swift
struct iOS14Stuff: HookGroup {
    let hasNotch: Bool
}

struct iOS13Stuff: HookGroup {}

class CallBarHook: ClassHook<UIView> {
    typealias Group = iOS14Stuff
    static let targetName = "SBCallBarView"
    // ...
}

class AppLibraryHook: ClassHook<UIView> {
    typealias Group = iOS14Stuff
    static let targetName =
        group.hasNotch ? "SBModernAppLibraryView" : "SBAppLibraryView"
    // ...
}

class CallScreenHook: ClassHook<UIView> {
    typealias Group = iOS13Stuff
    static let targetName = "SBCallScreenView"
    // ...
}

struct MyTweak: Tweak {
    init() {
        if #available(iOS 14, *) {
            let hasNotch = // ...
            iOS14Stuff(hasNotch: hasNotch).activate()
        } else {
            iOS13Stuff().activate()
        }
    }
}
```

--------------------------------

### activate()

Source: https://orion.theos.dev/protocols/hookgroup

Activates the hook group, enabling all hooks assigned to it. The instance on which this method is called will be saved and accessible via `AnyHook.group`.

```APIDOC
## activate()

### Description
Activates the group, enabling all hooks assigned to it. The instance on which this method is called will be saved and can henceforth be retrieved via the `AnyHook.group` property on any hook assigned to this group.

### Warning
For any particular group type, this method can be called at most once.

### Declaration
Swift
```swift
public func activate()
```
```

--------------------------------

### Apply Hook Descriptors

Source: https://orion.theos.dev/protocols/backend

Hooks the provided functions and methods using a list of `HookDescriptor` objects. This method is part of the `Backend` protocol.

```swift
func apply(descriptors: [HookDescriptor])
```

--------------------------------

### DefaultTweak Initializer

Source: https://orion.theos.dev/structs/defaulttweak

The DefaultTweak struct has a public initializer that takes no arguments.

```APIDOC
## init()

### Description
Initializes a new instance of `DefaultTweak`.

### Method
`init()`

### Parameters
This initializer does not take any parameters.

### Response
An instance of `DefaultTweak`.
```

--------------------------------

### Initializing Ivars

Source: https://orion.theos.dev/structs/ivars

Constructs a new instance of Ivars for accessing Objective-C instance variables on a given object.

```swift
public init(_ object: AnyObject)
```

--------------------------------

### HookDescriptor.method

Source: https://orion.theos.dev/enums/hookdescriptor

Describes a method hook. The `replacement` parameter is an Objective-C method `IMP` that should be a `@convention(c)` function. The `completion` closure receives the original method implementation or an error.

```APIDOC
## HookDescriptor.method

### Description
Describes a method hook. The `replacement` parameter is an Objective-C method `IMP` that should be a `@convention(c)` function. The `completion` closure receives the original method implementation or an error.

### Declaration
Swift
```swift
case method(cls: AnyClass, sel: Selector, replacement: UnsafeMutableRawPointer, completion: Completion)
```

### Parameters
- **cls** (AnyClass) - The class to hook. If hooking a class method, `cls` should be the metaclass.
- **sel** (Selector) - The selector of the method to hook.
- **replacement** (UnsafeMutableRawPointer) - A pointer to the replacement method implementation (`IMP`). It must be a `@convention(c)` function with the correct signature.
- **completion** (Completion) - A closure that will be called with the original method implementation or an error.
```

--------------------------------

### Syntactic Sugar for Class Method Calls

Source: https://orion.theos.dev/structs/dynamic

If the class is accessible and conforms to `NSObject`, use `as(interface:)` directly on the class for a concise way to call undeclared class methods.

```swift
MyClass.as(interface: MyInterfaceB.self).someClassMethod()
```

--------------------------------

### AnyHook Protocol Declaration

Source: https://orion.theos.dev/protocols/anyhook

The base protocol for hooks. Do not use this directly; refer to specific implementations.

```swift
public protocol AnyHook
```

--------------------------------

### Handle Error Method

Source: https://orion.theos.dev/protocols/tweak

Handles errors that occur during hooking. The default implementation simply forwards to handleErrorDefault(_:), which logs and terminates the process. This method may be called even before Tweak.init() is called.

```swift
static func handleError(_ error: OrionHookError)
```

--------------------------------

### Extension Method supr (Instance) Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the hooked class’ superclass instance methods.

```swift
public var supr: Self { get }
```

--------------------------------

### Apply Hook Descriptors

Source: https://orion.theos.dev/enums/backends/internal

Applies a list of hook descriptors to the system using the Internal backend's method hooking capabilities.

```APIDOC
## apply(descriptors:)

### Description
Applies a list of hook descriptors using the Internal backend.

### Method
`apply(descriptors:)`

### Parameters
#### Path Parameters
- **descriptors** ([HookDescriptor]) - Required - A list of HookDescriptor objects to apply.

### Declaration
Swift
```swift
public func apply(descriptors: [HookDescriptor])
```
```

--------------------------------

### Default Tweak Error Handling

Source: https://orion.theos.dev/protocols/tweak

The `handleErrorDefault(_:)` method is the default implementation for `handleError(_:)`. It forwards to `orionError(_:file:line:)`, logging the error and terminating the app. Custom `handleError(_:)` implementations may call this method.

```APIDOC
## handleErrorDefault(_:)

### Description
The default implementation of `handleError(_:)`.
This method forwards to `orionError(_:file:line:)`, thereby logging the error and terminating the app with `fatalError`.
If you implement `handleError(_:)` yourself, you may call this method at the end of your implementation.

See `handleError(_:)`

### Declaration
Swift
```swift
public static func handleErrorDefault(_ error: OrionHookError) -> Never
```

### Parameters
#### Path Parameters
- **error** (OrionHookError) - The error that occurred.
```

--------------------------------

### Tweak Error Handling

Source: https://orion.theos.dev/protocols/tweak

The `handleError(_:)` method handles errors that occur during hooking. The default implementation logs and terminates the process. Implementing this method allows for custom error handling without necessarily terminating the process. This method may be called even before `Tweak.init()`.

```APIDOC
## handleError(_:)

### Description
Handles errors that occur during hooking.
The default implementation simply forwards to `handleErrorDefault(_:)`, which logs and terminates the process. If you implement this method yourself, however, you can choose to **not** terminate the process.

This method may be called even before `Tweak.init()` is called.

### Default Implementation

### Declaration
Swift
```swift
static func handleError(_ error: OrionHookError)
```

### Parameters
#### Path Parameters
- **error** (OrionHookError) - The error that occurred.
```

--------------------------------

### activate Method

Source: https://orion.theos.dev/protocols/hookgroup

Activates a hook group, enabling all associated hooks. The instance used for activation is stored and accessible via `AnyHook.group`. This method can only be called once per group type.

```swift
public func activate()
```

--------------------------------

### Function deinitializer() Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

A function which is run before a `target` is deallocated. Use this to perform any cleanup before the target is deallocated. You must not call `orig.deinitializer()` or `supr.deinitializer()` in this method. Instead, return the appropriate deinit policy.

```swift
func deinitializer() -> DeinitPolicy
```

--------------------------------

### AnyHook Protocol Requirements

Source: https://orion.theos.dev/protocols/anyhook

This section details the requirements and associated methods of the AnyHook protocol. It includes properties for group association and methods for managing hook activation.

```APIDOC
## AnyHook Protocol

### Description
Base protocol requirements for hooks. Do not use this directly. See `ClassHook`, and `FunctionHook`.

### Associated Types
#### `Group`
The `HookGroup` to which this hook is assigned. Defaults to `DefaultGroup`.

##### Declaration
Swift
```swift
associatedtype Group : HookGroup = DefaultGroup
```

### Static Properties
#### `group`
The `HookGroup` associated with this hook type. Do not attempt to implement this yourself; use the default implementation.

##### Declaration
Swift
```swift
static var group: Group { get }
```

### Static Methods
#### `hookWillActivate()`
Called before the hook is activated.

##### Declaration
Swift
```swift
static func hookWillActivate() -> Bool
```

##### Return Value
`true` to continue activation, `false` to skip. The default implementation simply returns `true`.

#### `hookDidActivate()`
Called after the hook is activated. The default implementation does nothing.

##### Declaration
Swift
```swift
static func hookDidActivate()
```
```

--------------------------------

### Initializing Ivars for Weak Instance Variables

Source: https://orion.theos.dev/structs/ivars

Constructs an Ivars instance for accessing weak Objective-C instance variables. Requires IvarType to be an optional object type.

```swift
public init(_ object: AnyObject, _ storage: WeakStorage)
```

--------------------------------

### SubclassMode None Case

Source: https://orion.theos.dev/enums/subclassmode

Use this case when no subclass should be created for the hook.

```swift
case none
```

--------------------------------

### Apply Hook Descriptors

Source: https://orion.theos.dev/enums/backends/fishhook

Applies a list of hook descriptors to the Fishhook backend.

```APIDOC
## apply(descriptors:)

### Description
Applies a list of hook descriptors.

### Parameters
- `descriptors` - An array of `HookDescriptor` to apply.
```

--------------------------------

### Backend Protocol Declaration

Source: https://orion.theos.dev/protocols/backend

Declares the `Backend` protocol, which is responsible for hooking methods and functions. Use pre-defined backends from `Backends` unless custom requirements exist.

```swift
public protocol Backend
```

--------------------------------

### Define a Basic Class Hook in Swift

Source: https://orion.theos.dev/getting-started

Declare a hook for a target class like UILabel. This sets up the structure for overriding its methods. Ensure Orion and UIKit are imported.

```swift
// 1
import Orion
import UIKit

// 2
class LabelHook: ClassHook<UILabel> {
}

```

--------------------------------

### Target Function Declaration

Source: https://orion.theos.dev/protocols/functionhookprotocol

Represents the function which is to be hooked. This is a static property.

```swift
static var target: Function { get }
```

--------------------------------

### Handle Error Default Method

Source: https://orion.theos.dev/protocols/tweak

The default implementation of handleError(_:). This method forwards to orionError(_:file:line:), thereby logging the error and terminating the app with fatalError. If you implement handleError(_:) yourself, you may call this method at the end of your implementation.

```swift
public static func handleErrorDefault(_ error: OrionHookError) -> Never
```

--------------------------------

### OrionHookError Cases

Source: https://orion.theos.dev/enums/orionhookerror

This section details the different error cases that can be encountered during Orion hooking operations.

```APIDOC
## OrionHookError Enum Cases

### functionHookFailed
Indicates that function hooking failed.

#### Declaration
Swift
```swift
case functionHookFailed(target: Function, underlying: Error)
```

### targetClassNotAvailable
Indicates that a `ClassHook` could not compute its target class.

#### Declaration
Swift
```swift
case targetClassNotAvailable(hookName: String, underlying: Error)
```

### methodHookFailed
Indicates that method hooking failed.

#### Declaration
Swift
```swift
case methodHookFailed(cls: AnyClass, sel: Selector, isClassMethod: Bool, underlying: Error)
```

### methodAdditionFailed
Indicates that method addition (`orion:new`) failed. This may occur if, for example, a method with the provided selector already exists on the class.

#### Declaration
Swift
```swift
case methodAdditionFailed(cls: AnyClass, sel: Selector, isClassMethod: Bool, underlying: Error)
```
```

--------------------------------

### Static Property: targetName

Source: https://orion.theos.dev/protocols/classhookprotocol

The name of the target class. If an empty string is provided, `Target.self` will be used. The class must be `Target` or a subclass of `Target`. Defaults to an empty string.

```APIDOC
## Static Property: targetName

### Declaration

```swift
static var targetName: String { get }
```

**Description:**
The name of the target class, or the empty string to use `Target.self`. This class must be `Target` or a subclass of `Target`. Defaults to an empty string.

**Warning:** Do not attempt to access `target` in the getter for this property, as that will lead to infinite recursion.
```

--------------------------------

### as(interface:protocol:)

Source: https://orion.theos.dev/extensions/nsobject

Returns the class referred to by the receiver as if it conformed to the given interface. This is useful for private or Objective-C invisible protocols.

```APIDOC
## as(interface:protocol:)

### Description
Returns the class referred to by the receiver as if it conformed to the given interface. Methods on the interface should be declared as **instance** methods. For more information, see the documentation for the `Dynamic` struct.

### Declaration
Swift
```swift
public static func `as`<I>(interface: I.Type, protocol: Protocol? = nil) -> I
```

### Parameters
- `interface` (Type) - The interface to which the class should be cast.
- `protocol` (Protocol?) - If the interface is a private protocol or is otherwise invisible to Objective-C via `NSClassFromString`, you may need to pass the protocol a second time as this parameter. For example, `MyClass.as(interface: MyInterface.self, protocol: MyInterface.self)`.

### Return Value
The class, “cast” to the interface.
```

--------------------------------

### Extension Method: orig (Class)

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the original class methods of the hooked class.

```APIDOC
## Extension Method: orig (Class)

### Declaration

```swift
public static var orig: Self.Type { get }
```

**Description:**
A proxy to access the original class methods of the hooked class.
```

--------------------------------

### errorDescription Property

Source: https://orion.theos.dev/enums/orionhookerror

Provides a localized description of the error.

```swift
public var errorDescription: String? { get }
```

--------------------------------

### alloc(interface:)

Source: https://orion.theos.dev/extensions/nsobject

Allocates an object corresponding to the callee’s class and casts it to the type of the passed interface.

```APIDOC
## alloc(interface:)

### Description
Allocates an object corresponding to the callee’s class and casts it to the type of the passed interface.

### Declaration
Swift
```swift
public static func alloc<I>(interface: I.Type) -> I
```

### Parameters
- `interface` (Type) - The interface which the allocated type should be cast to. You usually want this to have an initializer method which should be chained to this call.

### Return Value
The allocated instance of the class, as the `interface` type.
```

--------------------------------

### Ivars Initializer

Source: https://orion.theos.dev/structs/ivars

Construct a new instance of Ivars for accessing Objective-C instance variables on a given object.

```APIDOC
## init(_:)

### Description
Construct a new instance of `Ivars` for accessing Objective-C instance variables on `object`.

### Method
`init(_ object: AnyObject)`

### Parameters
- `_ object`: The object on which ivars are to be accessed.
```

--------------------------------

### Tweak Protocol Declaration

Source: https://orion.theos.dev/protocols/tweak

Defines the Tweak protocol for Orion. A module should contain zero or one types conforming to this protocol. If there are zero, Orion will use DefaultTweak.

```swift
public protocol Tweak
```

--------------------------------

### Apply Hook Descriptors

Source: https://orion.theos.dev/enums/backends/internal

Applies a list of hook descriptors to the Internal backend. This method is used to configure the method hooks.

```swift
public func apply(descriptors: [HookDescriptor])
```

--------------------------------

### Address Case for Function

Source: https://orion.theos.dev/enums/function

Represents a function referred to by its memory address. Use this when the exact memory location is known.

```swift
case address(UnsafeMutableRawPointer)
```

--------------------------------

### Symbol Factory Method

Source: https://orion.theos.dev/enums/function

Creates a Function case using a symbol name and an image path string. This method requires a non-nil image parameter to avoid ambiguity with the enum case.

```swift
public static func symbol(_ name: String, image: String) -> Function
```

--------------------------------

### Tweak Activation Handling

Source: https://orion.theos.dev/protocols/tweak

The `tweakDidActivate()` method is called after all of the tweak’s hooks in `DefaultGroup` have been activated. The default implementation does nothing.

```APIDOC
## tweakDidActivate()

### Description
Called after all of the tweak’s hooks that are in `DefaultGroup` have been activated. The default implementation does nothing.

### Default Implementation

### Declaration
Swift
```swift
func tweakDidActivate()
```
```

--------------------------------

### Instance Property: target

Source: https://orion.theos.dev/protocols/classhookprotocol

The current instance of the hooked class, upon which a hooked method has been called.

```APIDOC
## Instance Property: target

### Declaration

```swift
var target: Target { get }
```

**Description:**
The current instance of the hooked class, upon which a hooked method has been called.

**Warning:** Do not attempt to implement this yourself; use the default implementation.
```

--------------------------------

### isActive

Source: https://orion.theos.dev/protocols/hookgroup

A static property that indicates whether or not the hook group has been activated.

```APIDOC
## isActive

### Description
Whether or not the group has been activated (by calling `activate()` on an instance of it) yet.

### Declaration
Swift
```swift
public static var isActive: Bool { get }
```
```

--------------------------------

### Extension Method: supr (Class)

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the hooked class’ superclass class methods.

```APIDOC
## Extension Method: supr (Class)

### Declaration

```swift
public static var supr: Self.Type { get }
```

**Description:**
A proxy to access the hooked class’ superclass class methods.
```

--------------------------------

### SubclassMode CreateSubclassNamed Case

Source: https://orion.theos.dev/enums/subclassmode

Use this case to create a subclass with a specific name provided as a string argument.

```swift
case createSubclassNamed(String)
```

--------------------------------

### Declare Objective-C Interface for Instance Methods

Source: https://orion.theos.dev/structs/dynamic

Declare an Objective-C protocol to define the interface for undeclared instance methods. This is the first step before casting and calling these methods.

```swift
@objc protocol MyInterfaceA {
    func someInstanceMethod()
}
```

--------------------------------

### Complete LabelHook Implementation

Source: https://orion.theos.dev/getting-started

This is the complete code for a UILabel hook that modifies the setText method. It imports necessary frameworks and defines the swizzled function.

```swift
import Orion
import UIKit

class LabelHook: ClassHook<UILabel> {
    func setText(_ text: String) {
        orig.setText(
            text.uppercased().replacingOccurrences(of: " ", with: "👏")
        )
    }
}

```

--------------------------------

### convert(_:to:)

Source: https://orion.theos.dev/structs/dynamic

Casts a given object to a specified interface type. This is a static method for type conversion.

```APIDOC
## convert(_:to:)

### Description
Casts the object to the given interface type.

### Method
static func convert<I>(_ object: AnyObject, to interface: I.Type) -> I

### Parameters
- **object** (AnyObject) - The object to cast.
- **interface** (I.Type) - The interface to which the object should be converted.

### Return Value
The object as if it conformed to the given interface.
```

--------------------------------

### FunctionHookProtocol

Source: https://orion.theos.dev/protocols/functionhookprotocol

The protocol to which function hooks conform. Users should not conform to this directly; instead, use the `FunctionHook` type.

```APIDOC
## Protocol: FunctionHookProtocol

### Description
The protocol to which function hooks conform. Do not conform to this directly; use `FunctionHook`.

### Properties

#### `target`

*   **Description**: The function which is to be hooked.
*   **Declaration**: `static var target: Function { get }`

#### `init()`

*   **Description**: Initialize the function hook type. Do not invoke or override this; use `AnyHook.hookWillActivate()` or `AnyHook.hookDidActivate()` for lifecycle events.
*   **Declaration**: `init()`

#### `orig`

*   **Description**: A proxy which allows invoking the original function. Use `orig.function` to access the original implementation of the hooked function.
*   **Declaration**: `public var orig: Self { get }`
```

--------------------------------

### FunctionHookProtocol Declaration

Source: https://orion.theos.dev/protocols/functionhookprotocol

The protocol to which function hooks conform. Do not conform to this directly; use `FunctionHook`.

```swift
public protocol FunctionHookProtocol : AnyObject, AnyHook
```

--------------------------------

### Extension Method supr (Class) Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the hooked class’ superclass class methods.

```swift
public static var supr: Self.Type { get }
```

--------------------------------

### Extension Method orig (Class) Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

A proxy to access the original class methods of the hooked class.

```swift
public static var orig: Self.Type { get }
```

--------------------------------

### HookDescriptor.function

Source: https://orion.theos.dev/enums/hookdescriptor

Describes a function hook. The `replacement` parameter should be a `@convention(c)` function with the same signature as the function being hooked. The `completion` closure receives the original function implementation or an error.

```APIDOC
## HookDescriptor.function

### Description
Describes a function hook. The `replacement` parameter should be a `@convention(c)` function with the same signature as the function being hooked. The `completion` closure receives the original function implementation or an error.

### Declaration
Swift
```swift
case function(function: Function, replacement: UnsafeMutableRawPointer, completion: Completion)
```

### Parameters
- **function** (Function) - The function to hook.
- **replacement** (UnsafeMutableRawPointer) - A pointer to the replacement function implementation. It must be a `@convention(c)` function with the same signature as the hooked function.
- **completion** (Completion) - A closure that will be called with the original function implementation or an error.
```

--------------------------------

### SubclassMode

Source: https://orion.theos.dev/enums/subclassmode

An enumeration describing a `ClassHook`‘s subclassing behavior.

```APIDOC
## Enum: SubclassMode

### Description
An enumeration describing a `ClassHook`‘s subclassing behavior.

### Cases

*   **none**
    Do not create a subclass for this hook.
    #### Declaration
    ```swift
    case none
    ```

*   **createSubclass**
    Create a subclass with a name derived from the hook name.
    #### Declaration
    ```swift
    case createSubclass
    ```

*   **createSubclassNamed(_:)**
    Create a subclass with the provided name.
    #### Declaration
    ```swift
    case createSubclassNamed(String)
    ```
```

--------------------------------

### ClassHookProtocol Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

The base protocol for class hooks. Do not conform to this directly; use `ClassHook`.

```swift
public protocol ClassHookProtocol : AnyObject, AnyHook
```

--------------------------------

### Method Hook Descriptor

Source: https://orion.theos.dev/enums/hookdescriptor

Use this case to describe a hook for an Objective-C method. Ensure the `replacement` is a `@convention(c)` function matching the method signature and `cls` is the metaclass for class methods.

```swift
case method(cls: AnyClass, sel: Selector, replacement: UnsafeMutableRawPointer, completion: Completion)
```

--------------------------------

### hookWillActivate() Method Declaration

Source: https://orion.theos.dev/protocols/anyhook

Called before the hook is activated. Returning false skips activation. The default implementation returns true.

```swift
static func hookWillActivate() -> Bool
```

--------------------------------

### Function Hook Descriptor

Source: https://orion.theos.dev/enums/hookdescriptor

Use this case to describe a hook for a C function. The `replacement` must be a `@convention(c)` function with the exact signature of the function being hooked.

```swift
case function(function: Function, replacement: UnsafeMutableRawPointer, completion: Completion)
```

--------------------------------

### Original Function Invocation

Source: https://orion.theos.dev/protocols/functionhookprotocol

A proxy which allows invoking the original function. Use `orig.function` to access the original implementation of the hooked function.

```swift
public var orig: Self { get }
```

--------------------------------

### Fishhook DefaultBackend Conformance

Source: https://orion.theos.dev/enums/backends/fishhook

Conditional conformance to DefaultBackend for Fishhook, dependent on the UnderlyingBackend also conforming to DefaultBackend.

```swift
extension Backends.Fishhook: DefaultBackend where UnderlyingBackend: DefaultBackend
```

--------------------------------

### Instance Property target Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

The current instance of the hooked class, upon which a hooked method has been called. Do not attempt to implement this yourself; use the default implementation.

```swift
var target: Target { get }
```

--------------------------------

### Access Ivar with `subscript(dynamicMember:)`

Source: https://orion.theos.dev/structs/ivars

Access an Objective-C instance variable on the object using dynamic member lookup. This subscript will crash if the ivar does not exist. Use `Ivars.subscript(safelyAccessing:)` or `Ivars.withIvar(_:_:)` for graceful failure.

```APIDOC
## subscript(dynamicMember:)

### Description
Access an Objective-C instance variable on the object. The ivar `ivarName` **must** be present on the object. If an ivar with the given name is not present, using this subscript will result in a crash. To fail gracefully, use `Ivars.subscript(safelyAccessing:)` or `Ivars.withIvar(_:_:)`.

### Method
`subscript(dynamicMember ivarName: String) -> IvarType { get nonmutating set }`

### Parameters
- `ivarName` (String): The name of the instance variable to access.
```

--------------------------------

### Declare Interface for Initializer

Source: https://orion.theos.dev/structs/dynamic

Declare an Objective-C protocol with the initializer method to call a private initializer. Use backticks to escape `init` if necessary.

```swift
@objc protocol MyInterfaceC {
    func initWithString(_ string: String)
}
```

--------------------------------

### as(type:)

Source: https://orion.theos.dev/structs/dynamic

Returns the class referred to by the callee, cast to a provided type. This method is used for type casting.

```APIDOC
## as(type:)

### Description
Returns the class referred to by the callee, cast to the provided type.

### Method
func `as`<T>(type: T.Type) -> T.Type where T : AnyObject

### Parameters
- **type** (T.Type) - The type to which the class should be cast.

### Return Value
The cast class.
```

--------------------------------

### Extension Method: target (Class)

Source: https://orion.theos.dev/protocols/classhookprotocol

The concrete type of the hooked target (or its subclass depending on `subclassMode`).

```APIDOC
## Extension Method: target (Class)

### Declaration

```swift
public static var target: Target.Type { get }
```

**Description:**
The concrete type of the hooked target (or its subclass depending on `subclassMode`).
```

--------------------------------

### Safely Access Ivar with `subscript(safelyAccessing:)`

Source: https://orion.theos.dev/structs/ivars

Access an Objective-C instance variable on the object, failing gracefully if the instance variable does not exist. Returns the value of the instance variable or `nil` if it does not exist. The setter does nothing if `nil` is passed.

```APIDOC
## subscript(safelyAccessing:)

### Description
Access an Objective-C instance variable on the object, failing gracefully if the instance variable does not exist. If the setter is passed a value of `nil`, it will do nothing.

### Method
`subscript(safelyAccessing ivarName: String) -> IvarType? { get nonmutating set }`

### Parameters
- `ivarName` (String): The name of the instance variable to access.

### Return Value
The value of the instance variable, or `nil` if there is no ivar with the given name.
```

--------------------------------

### Internal Backend Declaration

Source: https://orion.theos.dev/enums/backends/internal

Declares the Internal struct, which conforms to the DefaultBackend protocol. This backend is suitable for Objective-C runtime-based method hooking.

```swift
public struct Internal : DefaultBackend
```

--------------------------------

### Symbol Case for Function

Source: https://orion.theos.dev/enums/function

Represents a function referred to by its symbol name and optionally the image URL it belongs to. If the image is nil, the symbol can be in any image.

```swift
case symbol(_: String, image: URL?)
```

--------------------------------

### methodAdditionFailed Case

Source: https://orion.theos.dev/enums/orionhookerror

Indicates that adding a new method failed, possibly because a method with the same selector already exists. It includes the class, selector, method type, and underlying error.

```swift
case methodAdditionFailed(cls: AnyClass, sel: Selector, isClassMethod: Bool, underlying: Error)
```

--------------------------------

### HookGroup Protocol Declaration

Source: https://orion.theos.dev/protocols/hookgroup

The base protocol for creating hook groups. Conforming types can be used to group and manage the lifecycle of related hooks.

```swift
public protocol HookGroup
```

--------------------------------

### HookGroup Protocol

Source: https://orion.theos.dev/protocols/hookgroup

Defines a marker type for grouping hooks and deferring their initialization. Conforming types can have properties used as activation arguments.

```APIDOC
## HookGroup Protocol

### Description
A marker type which allows grouping and deferring the initialization of hooks. Hooks are assigned to groups by setting the `AnyHook.Group` associatedtype to the desired group.

### Conformance
To create a group, declare a type (usually a `struct`) which conforms to `HookGroup`.

### Activation
Groups can be activated by creating an instance of the group's type and calling `activate()` on it. This enables all hooks assigned to that group. The instance used for activation is saved and accessible via `AnyHook.group`.
```

--------------------------------

### Static Property protocols Declaration

Source: https://orion.theos.dev/protocols/classhookprotocol

An array of protocols which should be added to the target class. The default value is an empty array. Do not attempt to access `target` in the getter for this property, as that will lead to infinite recursion.

```swift
static var protocols: [Protocol] { get }
```

--------------------------------

### SubclassMode CreateSubclass Case

Source: https://orion.theos.dev/enums/subclassmode

Use this case to automatically create a subclass with a name derived from the hook name.

```swift
case createSubclass
```

--------------------------------

### Function.description

Source: https://orion.theos.dev/enums/function

A computed property that returns a string representation of the Function.

```APIDOC
## Function.description

### Declaration
Swift
```swift
public var description: String { get }
```
```

--------------------------------

### appending(component:)

Source: https://orion.theos.dev/structs/dynamic

Appends a component to the type name, delimited by a period. This is useful for building type names dynamically.

```APIDOC
## appending(component:)

### Description
Appends the provided component onto the name of the type, delimited by a period.

### Method
func appending(component: String) -> Dynamic

### Parameters
- **component** (String) - The component to append.

### Return Value
A modified copy of the callee with `component` appended to the name after a period.

### Example
```swift
Dynamic("Foo").appending(component: "Bar") == Dynamic("Foo.Bar")
```
```

--------------------------------

### Safely Accessing Objective-C Instance Variables

Source: https://orion.theos.dev/structs/ivars

Provides a subscript for safely accessing an Objective-C instance variable. Returns nil if the ivar does not exist. The setter does nothing if passed a nil value.

```swift
public subscript(safelyAccessing ivarName: String) -> IvarType? { get nonmutating set }
```

--------------------------------

### Allocate and Cast Object to Interface

Source: https://orion.theos.dev/structs/dynamic

Allocates an object corresponding to the callee's class and casts it to the type of the passed interface. This is typically used when you need to create an instance of a class and immediately treat it as a specific interface type.

```swift
public func alloc<I>(interface: I.Type) -> I
```
Tokens:
Raw