//
//  XCSourceEditorCommand.h
//  Xcode
//
//  Copyright © 2016-2022 Apple Inc. All rights reserved.
//

#import <XcodeKit/XcodeKitDefines.h>


@class XCSourceTextBuffer;


NS_ASSUME_NONNULL_BEGIN

/// An object that identifies the command issued to your extension and provides the contents of the active source editor.
@interface XCSourceEditorCommandInvocation : NSObject

/** An XCSourceEditorCommandInvocation is not directly instantiable. */
- (instancetype)init NS_UNAVAILABLE;

/// The identifier of the command that the user invoked.
@property (readonly, copy) NSString *commandIdentifier;

/// The buffer of source text upon which the command can operate.
@property (readonly, strong) XCSourceTextBuffer *buffer;

/// A handler to be invoked by Xcode to indicate that the invocation has been canceled by the user.
///
/// There are no guarantees about the thread or queue on which the cancellation handler is invoked. After receiving a cancellation, the command’s `completionHandler` is invoked and no changes are applied.
@property (copy) void (^cancellationHandler)(void);

@end


/// The protocol you implement to handle command invocations in a source editor extension.
///
/// A one-to-one mapping between command classes and commands is not required—multiple commands can be handled by a single class, by checking their invocation’s `commandIdentifier` at runtime.
@protocol XCSourceEditorCommand <NSObject>

@required

/// Performs the action associated with the command using the information in an invocation.
///
/// Xcode passes the code a completion handler that it must invoke to finish  performing the command, passing `nil` on success or an error on failure. A canceled command must still call the completion handler, passing `nil`.
///
/// There are no guarantees about the thread or queue on which this method is invoked.
///
/// - Parameters:
///   - invocation: The invocation of the command to be invoked.
///
///   - completionHandler: A block to be executed when the command finishes.

- (void)performCommandWithInvocation:(XCSourceEditorCommandInvocation *)invocation completionHandler:(void (^)(NSError * _Nullable nilOrError))completionHandler;

@end


NS_ASSUME_NONNULL_END