Action Macros

This document provides an overview of the macros available in the Nativeblocks Compiler for defining and managing actions. These macros simplify the creation of structured, reusable actions in Swift.

Macros Overview

1. NativeAction

Description

Defines a reusable action with metadata and associates it with a specific key and description.

Declaration

@attached(peer, names: suffixed(Action))
public macro NativeAction(
    name: String,
    keyType: String,
    description: String,
    version: Int = 1,
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Parameters

name: A String representing the display name of the action.
keyType: A String defining a unique key type identifier for the action.
description: A String providing a detailed explanation of the action's purpose.
version: An optional Int (default: 1) specifying the version of the action.
deprecated: A Bool (default: false) indicating whether the action is deprecated.
deprecatedReason: An optional String giving the reason for deprecation if applicable.

Example

@NativeAction(name: "Show Alert", keyType: "ALERT", description: "Shows an alert dialog")
public class ShowAlert {
    @NativeActionParameter
    struct Parameter {
        @NativeActionData
        var message: String
        @NativeActionProp
        var animated: Bool = false
        @NativeActionEvent(then: Then.SUCCESS)
        var completion: () -> Void
    }

    @NativeActionFunction
    func callAsFunction(param: Parameter) {
        print("Showing alert with message: \(param.message), animated: \(param.animated)")
        param.completion()
    }
}

2. NativeActionParameter

Description

Defines a struct for the input parameters of an action function. The struct encapsulates all parameters required by the action.

Declaration

@attached(peer)
public macro NativeActionParameter(description: String = "")

Example

@NativeActionParameter
struct Parameter {
    @NativeActionData
    var message: String
    @NativeActionProp
    var animated: Bool = false
    @NativeActionEvent(then: Then.SUCCESS)
    var completion: () -> Void
}

3. NativeActionFunction

Description

Defines a function within an action that encapsulates the core logic or behavior. The function must take a single NativeActionParameter struct as input.

Declaration

@attached(peer)
public macro NativeActionFunction(description: String = "")

Example

@NativeActionFunction
func callAsFunction(param: Parameter) {
    print("Executing action with message: \(param.message)")
    param.completion()
}

4. NativeActionData

Description

Defines a data-binding property for an action, typically linked to runtime data.

Declaration

@attached(peer)
public macro NativeActionData(
    description: String = "",
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Example

@NativeActionData(description: "The content of the alert")
var content: String

5. NativeActionProp

Description

Defines a configurable property for an action, such as settings or options.

Declaration

@attached(peer)
public macro NativeActionProp(
    description: String = "",
    valuePicker: NativeActionValuePicker = NativeActionValuePicker.TEXT_INPUT,
    valuePickerOptions: [NativeActionValuePickerOption] = [],
    valuePickerGroup: NativeActionValuePickerPosition = NativeActionValuePickerPosition("General"),
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Parameters

description: A String providing details about the property.
valuePicker: A NativeActionValuePicker specifying the input type for this property. Options include:
- TEXT_INPUT
- NUMBER_INPUT
- DROPDOWN
valuePickerOptions: An array of NativeActionValuePickerOption defining dropdown or combobox values.
valuePickerGroup: A NativeActionValuePickerPosition defining the section or category under which this property is grouped (default: "General").
deprecated: A Bool (default: false) indicating whether the property is deprecated.
deprecatedReason: An optional String giving the reason for deprecation if applicable.

Example

@NativeActionProp(description: "Enable animation", valuePicker: .DROPDOWN, valuePickerOptions: [NativeActionValuePickerOption("true", "Yes"), NativeActionValuePickerOption("false", "No")])
var animated: Bool = true

6. NativeActionEvent

Description

Defines an event for an action, such as a completion handler or callback.

Declaration

@attached(peer)
public macro NativeActionEvent(
    description: String = "",
    dataBinding: [String] = [],
    then: Then = Then.END,
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Parameters

description: A String providing details about the event.
dataBinding: An array of String specifying the data bindings for the event.
then: A Then enum value indicating the next step after the event (default: END).
deprecated: A Bool (default: false) indicating whether the event is deprecated.
deprecatedReason: An optional String giving the reason for deprecation if applicable.

Example

@NativeActionEvent(description: "Called when the action is complete", then: .SUCCESS)
var onComplete: () -> Void

Supporting Types

NativeActionValuePicker

Defines input methods for action properties.

enum NativeActionValuePicker {
    case TEXT_INPUT
    case NUMBER_INPUT
    case DROPDOWN
}

NativeActionValuePickerOption

Provides options for value pickers like dropdowns.

struct NativeActionValuePickerOption {
    var id: String
    var text: String
    public init(_ id: String, _ text: String) {
        self.id = id
        self.text = text
    }
}

NativeActionValuePickerPosition

Groups properties into sections.

struct NativeActionValuePickerPosition {
    var text: String
    public init(_ text: String) {
        self.text = text
    }
}

Then

Specifies the next step after an event.

enum Then {
    case SUCCESS
    case FAILURE
    case NEXT
    case END
}

Error Diagnostics

The Nativeblocks Compiler provides comprehensive error diagnostics to help developers identify and resolve issues during macro usage. Below are the supported errors:

Diagnostic Errors

1. notAClass

Message: "Only classes are supported."
Description: This error occurs when a macro is applied to a type that is not a class.

2. singleVariableLimit

Message: "Wrap a single variable only."
Description: This error ensures that only one variable is wrapped when using specific macros.

3. functionTypeError

Message: "Expected a function."
Description: This error occurs when the macro expects a function but encounters a different type.

4. eventTypeMisMachParamCount

Message: "Parameter count must match 'dataBinding'."
Description: This error indicates that the parameter count does not align with the dataBinding specification.

5. premitiveTypeSupported

Message: "Only primitive types are supported."
Description: This error enforces the use of primitive types.

6. requiredNativeActionFunction

Message: "Add one '@NativeActionFunction'."
Description: This error indicates that an action must include a function marked with @NativeActionFunction.

7. requiredNativeActionFunctionParameter

Message: "'@NativeActionFunction' needs a struct with '@NativeActionParameter'."
Description: This error enforces that the @NativeActionFunction takes a single parameter struct annotated with @NativeActionParameter.

8. eventDistinctThen

Message: "'then' in '@NativeActionEvent' must be unique."
Description: This error ensures that multiple events within the same action have distinct then values.

9. multiAttributes

Message: "Multi attribute not supported."
Description: This error occurs when multiple attributes are applied to the same element, which is not allowed.

10. actionNotsupportThrows

Message: "'@NativeActionFunction' doesn't support throws. Use '@NativeActionEvent(then: Then.FAILURE)'."
Description: This error indicates that @NativeActionFunction cannot use Swift's throws. Developers should use @NativeActionEvent with Then.FAILURE instead.

These diagnostics help ensure that developers use macros correctly, improving code reliability and maintainability.