AppleScriptObjective-C (ASOC) Routines

AppleScriptObjective-C applets, created in the AppleScript Editor via the File > New From Templates menu, have the ability to access the power of the native Cocoa libraries of OS X, from within the AppleScript code of the applet or droplet. The example sub-routines on this page can only be used in AppleScriptObjective-C (ASOC) applets.

For a detailed overview of how AppleScriptObjective-C is used to create applications, click here.

Replacing Characters in a String

This ASOC sub-routine uses methods from the NSString Cocoa class to find and replace a specified string within text.

Click to open example in the Script Editor applicationA sub-routine for replacing occurrences of a specified string in text.
 

 on findAndReplaceStringInText(sourceText, searchString, replacementString)
 -- create a Cocoa string from the passed AppleScript string
 set the sourceString to current application's NSString's stringWithString_(sourceText)
 -- call a Cocoa string replacement method on the newly created Cocoa string
 set the adjustedString to ¬
 the sourceString's stringByReplacingOccurrencesOfString_withString_(searchString, replacementString)
 -- convert from Cocoa string to AppleScript string
 return (adjustedString as string)
end findAndReplaceStringInText

Trim White Space Around String

This ASOC sub-routine uses methods from the NSString Cocoa class to trim spaces and tabs from both sides of the text passed to the routine.

Click to open example in the Script Editor applicationA sub-routine for trimming spaces and tabs from both sides of the text passed to the routine.
 

 on trimWhiteSpaceAroundString(sourceText)
 -- create Cocoa string from passed AppleScript string
 set the sourceString to current application's NSString's stringWithString_(sourceText)
 -- trim white space around Cocoa string
 set the trimmedCocoaString to ¬
 sourceString's stringByTrimmingCharactersInSet_(current application's NSCharacterSet's whitespaceCharacterSet)
 -- return result coerced to an AppleScript string
 return (trimmedCocoaString as string)
end trimWhiteSpaceAroundString

Change the Case of Text

This ASOC sub-routine uses methods from the NSString Cocoa class to change the case of the text passed to the sub-routine.

Click to open example in the Script Editor applicationA sub-routine for changing the case of the text passed to the routine. Case indicator: 0 = UPPER CASE; 1 = lower case; 2 = Capitalized Words
 

 on changeCaseOfText(sourceText, caseIndicator)
 -- create a Cocoa string from the passed text, by calling the NSString class method stringWithString:
 set the sourceString to current application's NSString's stringWithString_(sourceText)
 -- apply the indicated transformation to the Cocoa string
 if the caseIndicator is 0 then
 set the adjustedString to sourceString's uppercaseString()
 else if the caseIndicator is 1 then
 set the adjustedString to sourceString's lowercaseString()
 else
 set the adjustedString to sourceString's capitalizedString()
 end if
 -- convert from Cocoa string to AppleScript string
 return (adjustedString as string)
end changeCaseOfText

Convert a List to a String

This ASOC sub-routine uses methods from the NSArray Cocoa class to convert an AppleScript list of strings into a single AppleScript string. Optionally, the list items can be divided by a delimiter string passed to the routine.

Click to open example in the Script Editor applicationA sub-routine for converting an AppleScript list of strings into a single string.
 

 on listToStringUsingTextItemDelimiter(sourceList, textItemDelimiter)
 -- create a Cocoa array from the passed AppleScript list
 set the CocoaArray to current application's NSArray's arrayWithArray_(sourceList)
 -- create a Cocoa string from the Cocoa array using the passed delimiter string
 set the CocoaString to CocoaArray's componentsJoinedByString_(textItemDelimiter)
 -- return the Cocoa string coerced into an AppleScript string
 return (CocoaString as string)
end listToStringUsingTextItemDelimiter

Sort a List of Strings

This ASOC sub-routine uses methods from the NSArray Cocoa class to sort an AppleScript list of strings.

Click to open example in the Script Editor applicationA sub-routine for sorting an AppleScript list of strings.
 

 on sortListOfStrings(sourceList)
 -- create a Cocoa array from the passed AppleScript list
 set the CocoaArray to current application's NSArray's arrayWithArray_(sourceList)
 -- sort the Cocoa array
 set the sortedItems to CocoaArray's sortedArrayUsingSelector_("localizedStandardCompare:")
 -- return the Cocoa array coerced to an AppleScript list
 return (sortedItems as list)
end sortListOfStrings

Encode String using Percent Encoding

This ASOC sub-routine uses methods from the NSString Cocoa class to encode an AppleScript string using percent encoding.

Click to open example in the Script Editor applicationA sub-routine for encoding text using percent encoding.
 

 on encodeUsingPercentEncoding(sourceText)
 -- create a Cocoa string from the passed text, by calling the NSString class method stringWithString:
 set the sourceString to current application's NSString's stringWithString_(sourceText)
 -- apply the indicated transformation to the Cooca string
 set the adjustedString to ¬
 the sourceString's stringByAddingPercentEscapesUsingEncoding_(current application's NSUTF8StringEncoding)
 -- coerce from Cocoa string to AppleScript string
 return (adjustedString as string)
end encodeUsingPercentEncoding

Decode String using Percent Encoding

This ASOC sub-routine uses methods from the NSString Cocoa class to decode an AppleScript string using percent encoding.

Click to open example in the Script Editor applicationA sub-routine for decoding text that has been previously encoded using percent encoding.
 

 on decodePercentEncoding(sourceText)
 -- create a Cocoa string from the passed text, by calling the NSString class method stringWithString:
 set the sourceString to current application's NSString's stringWithString_(sourceText)
 -- apply the indicated transformation to the Cooca string
 set the adjustedString to ¬
 the sourceString's stringByReplacingPercentEscapesUsingEncoding_(current application's NSUTF8StringEncoding)
 -- coerce from Cocoa string to AppleScript string
 return (adjustedString as string)
end decodePercentEncoding

Convert Number to Decimal Value String

This ASOC sub-routine uses methods from the NSNumberFormatter Cocoa class to convert a number to a string by returning a comma delimited, rounded, localized decimal value, e.g.: (3.64525432506E+5 to 0 places = 364525) (3.64525432506E+5 to 3 places = 364525.433) (0.2375 to 2 places = 0.24).

Click to open example in the Script Editor applicationA sub-routine for decoding text that has been previously encoded using percent encoding.
 

 on convertNumberToDecimalValueString(thisNumber, maxDecimalPlaces)
 if maxDecimalPlaces is greater than 0 then
 set decimalIndicators to "."
 repeat maxDecimalPlaces times
 set decimalIndicators to decimalIndicators & "#"
 end repeat
 else
 set decimalIndicators to ""
 end if
 set thisFormatter to current application's NSNumberFormatter's alloc()'s init()
 tell thisFormatter to setFormat_("0" & decimalIndicators)
 set resultingText to thisFormatter's stringFromNumber_(thisNumber)
 return (resultingText as string)
end convertNumberToDecimalValueString

Convert Number to Percentage Value String

This ASOC sub-routine uses methods from the NSNumberFormatter Cocoa class to return a string of number that is a comma delimited, rounded, localized percentage value, e.g.: (0.2345 = 23%) (0.2375 = 24%).

Click to open example in the Script Editor applicationA sub-routine that returns comma delimited, rounded, localized percentage value, e.g.: (0.2345 = 23%) (0.2375 = 24%).
 

 on convertNumberToPercentageValueString(thisNumber)
 tell current application's NSNumberFormatter to set resultingText to ¬
 localizedStringFromNumber_numberStyle_(thisNumber, current application's NSNumberFormatterPercentStyle)
 return (resultingText as string)
end convertNumberToPercentageValueString

Convert Number to Currency Value String

This ASOC sub-routine uses methods from the NSNumberFormatter Cocoa class to return a string of number that is a comma delimited, rounded, localized currency value, e.g.: (9128 = $9,128.00) (9978.2485 = $9,128.25).

Click to open example in the Script Editor applicationA sub-routine that returns a string of a numeric value in words, e.g: (23 = “twenty-three”) (23.75 = “twenty-three point seven five”).
 

 on convertNumberToCurrencyValueString(thisNumber)
 tell current application's NSNumberFormatter to ¬
 set resultingText to localizedStringFromNumber_numberStyle_(thisNumber, current application's NSNumberFormatterCurrencyStyle)
 return (resultingText as string)
end convertNumberToCurrencyValueString

Convert Number to Words

This ASOC sub-routine uses methods from the NSNumberFormatter Cocoa class to return a string of a numeric value in words, e.g: (23 = “twenty-three”) (23.75 = “twenty-three point seven five”).

Click to open example in the Script Editor applicationA sub-routine that returns a string of a numeric value in words, e.g: (23 = “twenty-three”) (23.75 = “twenty-three point seven five”).
 

 on convertNumberToWords(thisNumber)
 tell current application's NSNumberFormatter to ¬
 set resultingText to localizedStringFromNumber_numberStyle_(thisNumber, current application's NSNumberFormatterSpellOutStyle)
 return (resultingText as string)
end convertNumberToWords