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

#import <XcodeKit/XcodeKitDefines.h>


@class XCSourceTextRange;


NS_ASSUME_NONNULL_BEGIN


/// A buffer you use to access and modify the text contents and text selections in a source editor.
///
/// Mutations to the buffer are tracked and committed when a command completes successfully and has not been canceled by the user.
@interface XCSourceTextBuffer : NSObject

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

/// The Uniform Type Identifier (UTI) of the content in the buffer.
@property (readonly, copy) NSString *contentUTI;

/// The number of space characters represented by a tab character in the buffer.
@property (readonly) NSInteger tabWidth;

/// The number of space characters used for indentation of the text in the buffer.
@property (readonly) NSInteger indentationWidth;

/// A Boolean value that indicates whether tabs are used for indentation.
///
/// The `usesTabsForIndentation` property determines whether tab characters are used to indent text instead of space characters when possible. When the indentation width isn’t a multiple of the tab width, space characters are used to pad the indentation to the appropriate width.
///
/// For example, consider an `XCSourceTextBuffer` instance that has a tab width of eight, an indentation width of four, and the `usesTabsForIndentation` property set to `true`. The first indentation level is represented by four space characters, the second by a tab character, the third by a tab followed by four space characters, the fourth by two tab characters, and so on.
///
/// ![A diagram showing four lines of source code, with each line indented once more than the last.](2097276-usestabsforindentation-1)
@property (readonly) BOOL usesTabsForIndentation;

/// The lines of text in the buffer, including line endings.
///
/// Line breaks within a single buffer should be consistent. Adding a line  containing additional line breaks modifies the array such that each line added is a separate element. Changes to the `completeBuffer` property are immediately reflected in this property, and vice versa.
@property (readonly, strong) NSMutableArray <NSString *> *lines;

/// The text selections in the buffer.
///
/// An empty range represents an insertion point. Modifying the lines of text in the buffer automatically updates the selections to match.
@property (readonly, strong) NSMutableArray <XCSourceTextRange *> *selections;

/// The complete buffer’s string representation.
///
/// Changes to the `lines` property are immediately reflected in this property, and vice versa.
@property (copy) NSString *completeBuffer;

@end


NS_ASSUME_NONNULL_END