GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing github.com — JavaScriptKit/Sources/JavaScriptKit/Macros.swift at main · wfltaylor/JavaScriptKit Expand file tree/ Copy pathMacros.swiftMore file actions 275 lines (267 loc) · 11.1 KB / Copy pathMacros.swiftFile metadata and controls275 lines (267 loc) · 11.1 KB 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 /// Controls how Swift enums annotated with `@JS` are emitted to TypeScript. /// - `const`: Emit the current BridgeJS style: a `const` object with literal members plus a type alias. /// - `tsEnum`: Emit a TypeScript `enum` declaration (only valid for simple enums and raw-value enums with String or numeric raw types). public enum JSEnumStyle: String { case const case tsEnum } /// Controls where BridgeJS reads imported JS values from. /// /// - `global`: Read from `globalThis`. /// - `snippet`: Read from a JavaScript file shipped inside the Swift target. /// - `module`: Read from an external ECMAScript module. public enum JSImportFrom { case global /// Read from a JavaScript file that ships with the Swift target. /// /// The path is rooted at the Swift target directory and must begin with `/` /// and end in `.js` or `.mjs`, e.g. `.snippet("/Modules/utils.mjs")`. The /// leading `/` denotes the target root, not the filesystem root, and the file /// must exist inside that target. BridgeJS copies referenced files into the /// generated package. case snippet(String) /// Read from an external ECMAScript module, resolved by the JavaScript host. /// /// The value is passed to the module resolver verbatim, which covers Node /// built-in modules and installed packages, e.g. `.module("node:path")`, /// `.module("lodash/fp")`, or `.module("@scope/package")`. Nothing is copied /// for these, and making them resolvable at load time is up to you. /// /// To reference a file in your own target, use ``JSImportFrom/snippet(_:)``. case module(String) } /// Names the JavaScript member that an imported declaration refers to. /// /// A string literal is accepted directly, so `jsName: "basename"` means /// ``JSName/name(_:)`` with that value. public enum JSName: ExpressibleByStringLiteral { /// A member looked up by name. case name(String) /// The default export of an ECMAScript module. /// /// Only valid on a top-level `@JSFunction`, `@JSGetter`, or `@JSClass` /// that also specifies `from: .module(...)` or `from: .snippet(...)`. case `default` public init(stringLiteral value: String) { self = .name(value) } } /// A macro that exposes Swift declarations to JavaScript and TypeScript. /// /// Apply this macro to Swift declarations that you want to make callable from JavaScript: /// /// ```swift /// // Export a function to JavaScript /// @JS public func greet(name: String) -> String { /// return "Hello, \(name)!" /// } /// /// // Export a class and its members /// @JS class Counter { /// private var count = 0 /// /// @JS init() {} /// /// @JS func increment() { /// count += 1 /// } /// /// @JS func getValue() -> Int { /// return count /// } /// } /// ``` /// /// If you prefer to access through namespace-based syntax, you can use `namespace` parameter /// /// Example: /// /// ```swift /// // Export a function to JavaScript with a custom namespace /// @JS(namespace: "__Swift.Foundation.UUID") public func create() -> String { /// UUID().uuidString /// } /// /// // Export a class with a custom namespace (note that only top level macro needs to specify the namespace) /// @JS(namespace: "Utils.Greeters") class Greeter { /// var name: String /// /// @JS init(name: String) { /// self.name = name /// } /// /// @JS func greet() -> String { /// return "Hello, " + self.name + "!" /// } /// /// @JS func changeName(name: String) { /// self.name = name /// } /// } /// ``` /// And the corresponding TypeScript declaration will be generated as: /// ```javascript /// declare global { /// namespace Utils { /// namespace Greeters { /// class Greeter { /// constructor(name: string); /// greet(): string; /// changeName(name: string): void; /// } /// } /// } /// namespace __Swift { /// namespace Foundation { /// namespace UUID { /// function create(): string; /// } /// } /// } /// } /// ``` /// The above Swift class will be accessible in JavaScript as: /// ```javascript /// const greeter = new globalThis.Utils.Greeters.Greeter("World"); /// console.log(greeter.greet()); // "Hello, World!" /// greeter.changeName("JavaScript"); /// console.log(greeter.greet()); // "Hello, JavaScript!" /// /// const uuid = new globalThis.__Swift.Foundation.UUID.create(); // "1A83F0E0-F7F2-4FD1-8873-01A68CF79AF4" /// ``` /// /// When you build your project with the BridgeJS plugin, these declarations will be /// accessible from JavaScript, and TypeScript declaration files (`.d.ts`) will be /// automatically generated to provide type safety. /// /// Use the first argument to choose a JavaScript and TypeScript name without changing /// the Swift identifier: `@JS("Counter") class InternalCounter`. This also works on /// structs, enums, and protocols. Generated type references use the chosen name, /// including references in optional, array, and callback signatures. Nested exported /// declarations inherit their enclosing types' exported names in their namespace paths. /// For const-style enums, the chosen name is the stem of the generated `Values`, `Tag`, /// and `Object` names. /// /// A renamed class constructor is still accessed through the WASM instance's exports /// object, such as `exports.Counter`, not as a named JavaScript module export. /// Renaming does not change bridging or memory-management semantics. In contrast, /// `@JS(as: Other.self)` changes the JavaScript representation using conversion methods. /// Combining a custom name with `as:` on the same declaration is not supported. /// /// For detailed usage information, see the article <doc:Exporting-Swift-to-JavaScript>. /// /// - Parameter name: A different JavaScript and TypeScript name for the exported declaration. /// Does not rename the Swift declaration or change its representation. /// - Parameter aliasOf: A different JavaScript representation, supplied as `as: Other.self`. /// Requires `bridgeToJS()` and `bridgeFromJS(_:)` conversions and cannot be combined with `name`. /// - Parameter namespace: A dot-separated string that defines the namespace hierarchy in JavaScript. /// Each segment becomes a nested object in the resulting JavaScript structure. /// - Parameter enumStyle: Controls how enums are emitted to TypeScript for this declaration: /// use `.const` (default) to emit a const object + type alias, /// or `.tsEnum` to emit a TypeScript `enum`. /// `.tsEnum` is supported for case enums and raw-value enums with String or numeric raw types. /// Bool raw-value enums are not supported with `.tsEnum` and will produce an error. /// /// - Important: This feature is still experimental. No API stability is guaranteed, and the API may change in future releases. @attached(peer) public macro JS( _ name: String? = nil, as aliasOf: Any.Type? = nil, namespace: String? = nil, enumStyle: JSEnumStyle = .const, identityMode: Bool = false ) = Builtin.ExternalMacro /// A macro that generates a Swift getter that reads a value from JavaScript. /// /// This macro is used by BridgeJS-generated Swift declarations. /// /// - Parameter jsName: An optional string that specifies the name of the JavaScript property to read from. /// If not provided, the Swift property name is used. /// /// Example: /// /// ```swift /// import JavaScriptKit /// /// @JSGetter var count: Int /// /// struct Greeter { /// @JSGetter var name: String /// } /// ``` /// /// - Parameter from: Selects where the property is read from. /// Use `.global` to read from `globalThis` (e.g. `console`, `document`). /// Use `.snippet("/path/to/module.js")` to read a named export from a file rooted at the Swift target, /// or `.module("node:os")` to read a named export from an external module. /// Pass `jsName: .default` to read the module's default export. @attached(accessor) public macro JSGetter(jsName: JSName? = nil, from: JSImportFrom? = nil) = #externalMacro(module: "BridgeJSMacros", type: "JSGetterMacro") /// A macro that generates a Swift function body that writes a value to JavaScript. /// /// This macro is used by BridgeJS-generated Swift declarations. /// /// - Parameter jsName: An optional string that specifies the name of the JavaScript property to write to. /// If not provided, automatically derived from the Swift property name. (e.g. "setName" -> "name") /// /// Example: /// /// ```swift /// import JavaScriptKit /// /// @JSSetter func setName(_ value: String) throws (JSException) /// ``` @attached(body) public macro JSSetter(jsName: JSName? = nil, from: JSImportFrom? = nil) = #externalMacro(module: "BridgeJSMacros", type: "JSSetterMacro") /// A macro that generates a Swift function body that calls a JavaScript function. /// /// This macro is used by BridgeJS-generated Swift declarations. /// /// Example: /// /// ```swift /// import JavaScriptKit /// /// @JSFunction func greet() throws (JSException) -> String /// @JSFunction init(_ name: String) throws (JSException) /// ``` /// /// - Parameter jsName: An optional string that specifies the name of the JavaScript function or method to call. /// If not provided, the Swift function name is used. /// - Parameter from: Selects where the function is looked up from. /// Use `.global` to call a function on `globalThis` (e.g. `setTimeout`). /// Use `.snippet("/path/to/module.js")` to call a named export from a file rooted at the Swift target, /// or `.module("node:path")` to call a named export from an external module. /// Pass `jsName: .default` to call the module's default export. @attached(body) public macro JSFunction(jsName: JSName? = nil, from: JSImportFrom? = nil) = #externalMacro(module: "BridgeJSMacros", type: "JSFunctionMacro") /// A macro that adds bridging members for a Swift type that represents a JavaScript class. /// /// This macro is used by BridgeJS-generated Swift declarations. /// /// Example: /// /// ```swift /// import JavaScriptKit /// /// @JSClass /// struct JsGreeter { /// @JSGetter var name: String /// @JSSetter func setName(_ value: String) throws (JSException) /// @JSFunction init(_ name: String) throws (JSException) /// @JSFunction func greet() throws (JSException) -> String /// } /// ``` /// /// - Parameter from: Selects where the constructor is looked up from. /// Use `.global` to construct globals like `WebSocket` via `globalThis`. /// Use `.snippet("/path/to/module.js")` to construct a named class export from a file rooted at the Swift target, /// or `.module("@scope/package")` to construct a named class export from an external module. /// Pass `jsName: .default` to construct the module's default export. @attached(member, names: named(jsObject), named(init(unsafelyWrapping:))) @attached(extension, conformances: _JSBridgedClass) public macro JSClass(jsName: JSName? = nil, from: JSImportFrom? = nil) = #externalMacro(module: "BridgeJSMacros", type: "JSClassMacro") |
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |