ANSIEscapeHelper.h

//
//  ANSIEscapeHelper.h
//  AnsiColorsTest
//
//  Created by Ali Rantakari on 18.3.09.
//
//  Version 0.9.4
// 
/*
The MIT License

Copyright (c) 2008-2009 Ali Rantakari

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/

#import <Cocoa/Cocoa.h>


// the CSI (Control Sequence Initiator) -- i.e. "escape sequence prefix".
// (add your own CSI:Miami joke here)
#define kANSIEscapeCSI			@"\033["

// the end byte of an SGR (Select Graphic Rendition)
// ANSI Escape Sequence
#define kANSIEscapeSGREnd		@"m"


// color definition helper macros
#define kBrightColorBrightness	1.0
#define kBrightColorSaturation	0.4
#define kBrightColorAlpha		1.0
#define kBrightColorWithHue(h)	[NSColor colorWithCalibratedHue:(h) saturation:kBrightColorSaturation brightness:kBrightColorBrightness alpha:kBrightColorAlpha]

// default colors
#define kDefaultANSIColorFgBlack	[NSColor blackColor]
#define kDefaultANSIColorFgRed		[NSColor redColor]
#define kDefaultANSIColorFgGreen	[NSColor greenColor]
#define kDefaultANSIColorFgYellow	[NSColor yellowColor]
#define kDefaultANSIColorFgBlue		[NSColor blueColor]
#define kDefaultANSIColorFgMagenta	[NSColor magentaColor]
#define kDefaultANSIColorFgCyan		[NSColor cyanColor]
#define kDefaultANSIColorFgWhite	[NSColor whiteColor]

#define kDefaultANSIColorFgBrightBlack		[NSColor colorWithCalibratedWhite:0.337 alpha:1.0]
#define kDefaultANSIColorFgBrightRed		kBrightColorWithHue(1.0)
#define kDefaultANSIColorFgBrightGreen		kBrightColorWithHue(1.0/3.0)
#define kDefaultANSIColorFgBrightYellow		kBrightColorWithHue(1.0/6.0)
#define kDefaultANSIColorFgBrightBlue		kBrightColorWithHue(2.0/3.0)
#define kDefaultANSIColorFgBrightMagenta	kBrightColorWithHue(5.0/6.0)
#define kDefaultANSIColorFgBrightCyan		kBrightColorWithHue(0.5)
#define kDefaultANSIColorFgBrightWhite		[NSColor whiteColor]

#define kDefaultANSIColorBgBlack	[NSColor blackColor]
#define kDefaultANSIColorBgRed		[NSColor redColor]
#define kDefaultANSIColorBgGreen	[NSColor greenColor]
#define kDefaultANSIColorBgYellow	[NSColor yellowColor]
#define kDefaultANSIColorBgBlue		[NSColor blueColor]
#define kDefaultANSIColorBgMagenta	[NSColor magentaColor]
#define kDefaultANSIColorBgCyan		[NSColor cyanColor]
#define kDefaultANSIColorBgWhite	[NSColor whiteColor]

#define kDefaultANSIColorBgBrightBlack		kDefaultANSIColorFgBrightBlack
#define kDefaultANSIColorBgBrightRed		kDefaultANSIColorFgBrightRed
#define kDefaultANSIColorBgBrightGreen		kDefaultANSIColorFgBrightGreen
#define kDefaultANSIColorBgBrightYellow		kDefaultANSIColorFgBrightYellow
#define kDefaultANSIColorBgBrightBlue		kDefaultANSIColorFgBrightBlue
#define kDefaultANSIColorBgBrightMagenta	kDefaultANSIColorFgBrightMagenta
#define kDefaultANSIColorBgBrightCyan		kDefaultANSIColorFgBrightCyan
#define kDefaultANSIColorBgBrightWhite		kDefaultANSIColorFgBrightWhite

// dictionary keys for the SGR code dictionaries that the array
// escapeCodesForString:cleanString: returns contains
#define kCodeDictKey_code			@"code"
#define kCodeDictKey_location		@"location"

// dictionary keys for the string formatting attribute
// dictionaries that the array attributesForString:cleanString:
// returns contains
#define kAttrDictKey_range			@"range"
#define kAttrDictKey_attrName		@"attributeName"
#define kAttrDictKey_attrValue		@"attributeValue"

// minimum weight for an NSFont for it to be considered bold
#define kBoldFontMinWeight			9




/*!
 @enum			sgrCode
 
 @abstract		SGR (Select Graphic Rendition) ANSI control codes.
 */
enum sgrCode
{
	SGRCodeNoneOrInvalid =		-1,
	
	SGRCodeAllReset =			0,
	
	SGRCodeIntensityBold =		1,
	SGRCodeIntensityFaint =		2,
	SGRCodeIntensityNormal =	22,
	
	SGRCodeItalicOn =			3,
	
	SGRCodeUnderlineSingle =	4,
	SGRCodeUnderlineDouble =	21,
	SGRCodeUnderlineNone =		24,
	
	SGRCodeFgBlack =			30,
	SGRCodeFgRed =				31,
	SGRCodeFgGreen =			32,
	SGRCodeFgYellow =			33,
	SGRCodeFgBlue =				34,
	SGRCodeFgMagenta =			35,
	SGRCodeFgCyan =				36,
	SGRCodeFgWhite =			37,
	SGRCodeFgReset =			39,
	
	SGRCodeBgBlack =			40,
	SGRCodeBgRed =				41,
	SGRCodeBgGreen =			42,
	SGRCodeBgYellow =			43,
	SGRCodeBgBlue =				44,
	SGRCodeBgMagenta =			45,
	SGRCodeBgCyan =				46,
	SGRCodeBgWhite =			47,
	SGRCodeBgReset =			49,
	
	SGRCodeFgBrightBlack =		90,
	SGRCodeFgBrightRed =		91,
	SGRCodeFgBrightGreen =		92,
	SGRCodeFgBrightYellow =		93,
	SGRCodeFgBrightBlue =		94,
	SGRCodeFgBrightMagenta =	95,
	SGRCodeFgBrightCyan =		96,
	SGRCodeFgBrightWhite =		97,
	
	SGRCodeBgBrightBlack =		100,
	SGRCodeBgBrightRed =		101,
	SGRCodeBgBrightGreen =		102,
	SGRCodeBgBrightYellow =		103,
	SGRCodeBgBrightBlue =		104,
	SGRCodeBgBrightMagenta =	105,
	SGRCodeBgBrightCyan =		106,
	SGRCodeBgBrightWhite =		107
};






/*!
 @class		ANSIEscapeHelper
 
 @abstract	Contains helper methods for dealing with strings
			that contain ANSI escape sequences for formatting (colors,
			underlining, bold etc.)
 */
@interface ANSIEscapeHelper : NSObject
{
	NSFont *font;
	NSMutableDictionary *ansiColors;
    NSColor *defaultStringColor;
}

/*!
 @property		defaultStringColor
 
 @abstract		The default color used when creating an attributed string (default is black).
 */
@property(copy) NSColor *defaultStringColor;


/*!
 @property		font
 
 @abstract		The font to use when creating string formatting attribute values.
 */
@property(copy) NSFont *font;

/*!
 @property		ansiColors
 
 @abstract		The colors to use for displaying ANSI colors.
 
 @discussion	Keys in this dictionary should be NSNumber objects containing SGR code
				values from the sgrCode enum. The corresponding values for these keys
				should be NSColor objects. If this property is nil or if it doesn't
				contain a key for a specific SGR code, the default color will be used
				instead.
 */
@property(retain) NSMutableDictionary *ansiColors;


/*!
 @method		attributedStringWithANSIEscapedString:
 
 @abstract		Returns an attributed string that corresponds both in contents
				and formatting to a given string that contains ANSI escape
				sequences.
 
 @param aString			A String containing ANSI escape sequences
 
 @result		An attributed string that mimics as closely as possible
				the formatting of the given ANSI-escaped string.
 */
- (NSAttributedString*) attributedStringWithANSIEscapedString:(NSString*)aString;


/*!
 @method		ansiEscapedStringWithAttributedString:
 
 @abstract		Returns a string containing ANSI escape sequences that corresponds
				both in contents and formatting to a given attributed string.
 
 @param aAttributedString		An attributed string
 
 @result		A string that mimics as closely as possible
				the formatting of the given attributed string with
				ANSI escape sequences.
 */
- (NSString*) ansiEscapedStringWithAttributedString:(NSAttributedString*)aAttributedString;


/*!
 @method		escapeCodesForString:cleanString:
 
 @abstract		Returns an array of SGR codes and their locations from a
				string containing ANSI escape sequences as well as a "clean"
				version of the string (i.e. one without the ANSI escape
				sequences.)
 
 @param aString			A String containing ANSI escape sequences
 @param aCleanString	Upon return, contains a "clean" version of aString (i.e. aString
						without the ANSI escape sequences)
 
 @result		An array of NSDictionary objects, each of which has
				an NSNumber value for the key "code" (specifying an SGR code) and
				another NSNumber value for the key "location" (specifying the
				location of the code within aCleanString.)
 */
- (NSArray*) escapeCodesForString:(NSString*)aString cleanString:(NSString**)aCleanString;


/*!
 @method		ansiEscapedStringWithCodesAndLocations:cleanString:
 
 @abstract		Returns a string containing ANSI escape codes for formatting based
				on a string and an array of SGR codes and their locations within
				the given string.
 
 @param aCodesArray		An array of NSDictionary objects, each of which should have
						an NSNumber value for the key "code" (specifying an SGR
						code) and another NSNumber value for the key "location"
						(specifying the location of this SGR code in aCleanString.)
 @param aCleanString	The string to which to insert the ANSI escape codes
						described in aCodesArray.
 
 @result		A string containing ANSI escape sequences.
 */
- (NSString*) ansiEscapedStringWithCodesAndLocations:(NSArray*)aCodesArray cleanString:(NSString*)aCleanString;


/*!
 @method		attributesForString:cleanString:
 
 @abstract		Convert ANSI escape sequences in a string to string formatting attributes.
 
 @discussion	Given a string with some ANSI escape sequences in it, this method returns
				attributes for formatting the specified string according to those ANSI
				escape sequences as well as a "clean" (i.e. free of the escape sequences)
				version of this string.
 
 @param aString			A String containing ANSI escape sequences
 @param aCleanString	Upon return, contains a "clean" version of aString (i.e. aString
						without the ANSI escape sequences.) Pass in NULL if you're not
						interested in this.
 
 @result		An array containing NSDictionary objects, each of which has keys "range"
				(an NSValue containing an NSRange, specifying the range for the
				attribute within the "clean" version of aString), "attributeName" (an
				NSString) and "attributeValue" (an NSObject). You may use these as
				arguments for NSMutableAttributedString's methods for setting the
				visual formatting.
 */
- (NSArray*) attributesForString:(NSString*)aString cleanString:(NSString**)aCleanString;


/*!
 @method		sgrCode:endsFormattingIntroducedByCode:
 
 @abstract		Whether the occurrence of a given SGR code would end the formatting run
				introduced by another SGR code.
 
 @discussion	For example, SGRCodeFgReset, SGRCodeAllReset or any SGR code
				specifying a foreground color would end the formatting run
				introduced by a foreground color -specifying SGR code.
 
 @param endCode		The SGR code to test as a candidate for ending the formatting run
					introduced by startCode
 @param startCode	The SGR code that has introduced a formatting run
 
 @result		YES if the occurrence of endCode would end the formatting run
				introduced by startCode, NO otherwise.
 */
- (BOOL) sgrCode:(enum sgrCode)endCode endsFormattingIntroducedByCode:(enum sgrCode)startCode;


/*!
 @method		colorForSGRCode:
 
 @abstract		Returns the color to use for displaying a specific ANSI color.
 
 @discussion	This method first considers the values set in the ansiColors
				property and only then the standard basic colors (NSColor's
				redColor, blueColor etc.)
 
 @param code	An SGR code that specifies an ANSI color.
 
 @result		The color to use for displaying the ANSI color specified by code.
 */
- (NSColor*) colorForSGRCode:(enum sgrCode)code;


/*!
 @method		sgrCodeForColor:isForegroundColor:
 
 @abstract		Returns a color SGR code that corresponds to a given color.
 
 @discussion	This method matches colors to their equivalent SGR codes
				by going through the colors specified in the ansiColors
				dictionary, and if ansiColors is null or if a match is
				not found there, by comparing the given color to the
				standard basic colors (NSColor's redColor, blueColor
				etc.) The comparison is done simply by checking for
				equality.
 
 @param aColor			The color to get a corresponding SGR code for
 @param aForeground		Whether you want a foreground or background color code
 
 @result		SGR code that corresponds with aColor.
 */
- (enum sgrCode) sgrCodeForColor:(NSColor*)aColor isForegroundColor:(BOOL)aForeground;


/*!
 @method		closestSGRCodeForColor:isForegroundColor:
 
 @abstract		Returns a color SGR code that represents the closest ANSI
 				color to a given color.
 
 @discussion	This method attempts to find the closest ANSI color to
 				aColor and return its SGR code.
 
 @param aColor			The color to get a closest color SGR code match for
 @param aForeground		Whether you want a foreground or background color code
 
 @result		SGR code for the ANSI color that is closest to aColor.
 */
- (enum sgrCode) closestSGRCodeForColor:(NSColor *)color isForegroundColor:(BOOL)foreground;



@end