Discussion

This function can be used to ensure that some or all of an expression is left untouched by the expression evaluator.

This is required, for example, to preserve space characters at the beginning or end of a text literal. (Normally, the expression evaluator ignores whitespace at the beginning or end of text literals.)

This Mockingbird function accepts one parameter, the string to be quoted.

Expression usage

^q(   -- Please leave spaces intact --   )

The Mockingbird expression above quotes the string so that the spaces at the beginning and end of the string are preserved. The return value is: “   -- Please leave spaces intact --   ”.

^q(Ke$ha)

The expression above would return the string “Ke$ha”.

Normally, the expression evaluator interprets a dollar sign ($) as the beginning of a variable reference. By itself, the string “Ke$ha” would be recognized as: the text literal “Ke” followed by a reference to the Mockingbird variable “ha”. Assuming there is no value for “$ha”, without quoting, the expression “Ke$ha” would actually result in the string “Ke”, which is probably not the desired result.

Quoting the string ensures that it is left intact and not misinterpreted as containing a variable reference.

Discussion

This Mockingbird function accepts a single parameter, a string containing the expression to be evaluated.

Expression usage

Assume the variable $user has a value:

^eval(^q($)user)

The expression above would return the object referenced by the variable $user.

Discussion

This Mockingbird function accepts a single parameter, a string containing the expression to be evaluated.

Expression usage

^evalBool(T)

The expression above returns an NSNumber instance containing the boolean value YES.

Discussion

This Mockingbird function accepts a single parameter, an expression representing the string to be trimmed.

Expression usage

^trimSpaces(  Hi, how are you? )

The expression above would result in the value “Hi, how are you?”.

Discussion

Note that this removes only space characters, not all whitespace.

This Mockingbird function accepts a single parameter, an expression representing the string to be stripped.

Expression usage

^stripSpaces(  Hi, how are you? )

The expression above would result in the value “Hi,howareyou?”.

Discussion

This Mockingbird function accepts a single parameter, a string expression yielding the URL string from which the query string should be removed.

Expression usage

^stripQueryString(http://www.gilt.com/?utm_campaign=claris)

The expression above would return the string “http://www.gilt.com/”.

Discussion

This Mockingbird function accepts a single input parameter: an expression that will be evaluated as a string.

Expression usage

^indentLines($emailBody)

The expression above will interpret the emailBody Mockingbird variable as a string, and will then prefix each line of the result with a tab character.

The implementation attempts to be platform-agnostic with respect to the exact sequence of characters that signal line endings.

Discussion

This Mockingbird function accepts two pipe-separated input parameters:

• The string to indent, a string expression representing the string whose inidividual lines will be indented

• The number of tabs, a numeric expression indicating the number of tabs that should be used to indent string to indent

Expression usage

^indentLinesToDepth($emailBody|2)

The expression above will interpret the emailBody Mockingbird variable as a string, and will then prefix each line of the result with two tab characters.

The implementation attempts to be platform-agnostic with respect to the exact sequence of characters that signal line endings.

Discussion

This Mockingbird function accepts two pipe-separated input parameters:

• The string to indent, a string expression representing the string being indented

• The number of tabs, a numeric expression indicating the number of tabs that should be used to indent string to indent

Expression usage

^prefixLinesWith($emailBody|> )

The expression above will interpret the emailBody Mockingbird variable as a string, and will then prefix each line of the result with the text “> ”.

The implementation attempts to be platform-agnostic with respect to the exact sequence of characters that signal line endings.

Discussion

Pluralization allows multiple variants of a term to be supplied, and based on a count, the grammatically-correct form of term will be returned.

For example, if you are displaying a message to a user and you want to reference a number of discounts accrued by the user, you might want to construct a slightly different message based on the number of discounts:

• “You have no discounts” if there are 0 discounts
• “You have one discount” if there is 1 discount
• “You have number discounts” if there is more than 1 discount (where number represents the exact value of count)

Sometimes, you might not need a zero-count form:

• “Welcome to our application!” if the user has launched your app only once
• “We're glad to have you back!” if the user has launched your app more than once

When used with the zero-count form, this Mockingbird function accepts four pipe-separated input parameters:

• The count, a numeric expression indicating the number of items involved in the pluralization
• The zero-count term, a string expression representing the value to be returned if count is 0
• The one-count term, a string expression representing the value to be returned if count is 1
• The multiple-count term, a string expression representing the value to be returned if count is greater than 1

The zero-count form can also be omitted, in which case this function accepts three pipe-separated input parameters:

• The count, a numeric expression indicating the number of items involved in the pluralization
• The one-count term, a string expression representing the value to be returned if count is 1
• The not-one-count term, a string expression representing the value to be returned if count is 0 or greater than 1

Expression usage

Here’s an example of pluralization involving a zero-count form:

^pluralize($user.discounts.count
    |You have no discounts
    |You have one discount
    |You have $user.discounts.count discounts)

If $user.discounts.count == 2, the expression above would yield the string “You have 2 discounts”.

Pluralization without a zero-count form looks like:

^pluralize($launchCount
    |Welcome to our application!
    |We're glad to have you back!)

When $launchCount is 1, the expression above yields “Welcome to our application!” For any other value, “We're glad to have you back!” is returned.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string whose case is to be changed.

Expression usage

^lowercase(STOP SHOUTING! start whispering.)

The expression above returns the string “stop shouting! start whispering.”.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string whose case is to be changed.

Expression usage

^uppercase(stop whispering. START SHOUTING!)

The expression above returns the string “STOP WHISPERING. START SHOUTING!”.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string whose case is to be changed.

Expression usage

^titleCase(e. e. cummings)

The expression above returns the string “E. E. Cummings”.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string whose case is to be changed.

Expression usage

^titleCaseIfAllCaps(e. e. cummings)

The expression above returns the string “e. e. cummings”.

^titleCaseIfAllCaps(E. E. CUMMINGS)

The expression above returns the string “E. E. Cummings”.

Discussion

Each field is comprised of two components: a field label and a field value.

For each field with a non-nil value, the field label is added to the string, followed by the field value. If multiple fields are provided, the field separator is included between each field label/field value pair.

This Mockingbird function accepts two or more pipe-separated input parameters:

• An optional field separator, a string expression specifying the separator to be used between each label/value pair added to the output string. If the field separator parameter is not explicitly specified, the separator string “;” (a semicolon followed by a space) is used.

• A field label, a string expression

• A field value, a string expression

• An optional set of additional label/value pairs.

Note that if the field separator parameter is specified, the function will always expect an odd number of parameters, whereas if the field separator is omitted, the function will always expect an even number of parameters.

Expression usage

Assume that $item.size yields the string “42R” and $item.color yields “navy blue”

^concatenateFields(Size: |$item.size|Color: |^titleCase($item.size))

The expression above would return the string “Size: 42R; Color: Navy Blue”.

Discussion

This Mockingbird function accepts an arbitrary list of pipe-separated parameters, where each parameter is an expression that will be evaluated in the string context.

The function will return the value of the first expression that yields a non-empty string. If there are no such values, nil is returned.

Expression usage

Assume $firstName is “Lon” and $nickname has no value:

^firstNonemptyString($nickname|$firstName|Valued Customer)

The expression above would yield the string “Lon”.

If $firstName were undefined, the return value would be “Valued Customer”.

Discussion

This Mockingbird function accepts an arbitrary list of pipe-separated parameters, where each parameter is an expression that will be evaluated in the string context.

The function will return the value of the first expression that yields a non-empty string after whitespace trimming. If there are no such values, nil is returned.

Expression usage

Assume that the expression $user.salutation yields nil:

^firstNonemptyTrimmedString($user.salutation|Dear )

The expression above would yield the string “Dear” (with no trailing space) even though the second parameter consists of a string (“Dear ”) containing a trailing space.

Discussion

This Mockingbird function accepts 2 or 3 pipe-separated input parameters:

• The truncation length, a numeric expression. If input string’s length is greater than truncation length, input string will be shortened to exactly truncation length, and then the truncation marker will be appended.

• An optional truncation marker, a string expression representing the string to append to the end of input string after truncation occurs. If this parameter is omitted, the ellipses character (…) will be used as the truncation string.

• The input string, an expression yielding the string to be truncated.

Note that the truncation marker is appended after the input string is truncated. As a result, the string returned by this function may be as long as truncation length plus the length of truncation marker.

Expression usage

^truncate(10|This is your chance!)

The expression above yields the string “This is yo…”.

^truncate(5|!|Hello, Newman.)

The expression above results in “Hello!”.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string to be parsed as a number.

Expression usage

Assume the variable $foo contains the string “5” and the variable $bar contains the string “25”, the following expression:

^parseNumber(${foo}.${bar})

returns an NSNumber containing the floating-point value 5.25.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string to be parsed as an integer.

Expression usage

Assume the variable $foo contains the string “5” and the variable $bar contains the string “25”, the following expression:

^parseInteger(-${foo}.${bar})

returns an NSNumber containing the value -5.

Discussion

This Mockingbird function accepts a single input parameter: an expression yielding the string to be parsed as a double.

Expression usage

Assume the variable $foo contains the string “5” and the variable $bar contains the string “25”, the following expression:

^parseDouble(-${foo}.${bar})

returns an NSNumber containing the value -5.25.

Discussion

This Mockingbird function accepts a single input parameter: a numeric expression yielding the number to format as an integer string.

Expression usage

^formatInteger(11 / 2)

The expression above yields an NSString containing the value “5”.

Discussion

This Mockingbird function accepts two parameters:

• The string to test, a string expression that will be tested to see if it has the given prefix.

• The prefix, a string expression yielding the prefix to test against string to test.

Expression usage

^hasPrefix($name|Coop)

The expression above evaluates to true if string value of the expression $name begins with “Coop”.

Discussion

This Mockingbird function accepts two input parameters:

• The string to test, a string expression that will be tested to see if it has the given suffix.

• The suffix, a string expression yielding the suffix to test against string to test.

Expression usage

^hasSuffix($dayOfWeek|day)

The expression above evaluates to true if string value of the expression $dayOfWeek ends with “day”.

Discussion

This Mockingbird function accepts two input parameters:

• The string to test, a string expression that will be tested to see if it contains the substring.

• The substring, a string expression yielding the substring to be found within string to test.

Expression usage

^containsString($dayOfWeek|ues)

The Mockingbird expression above returns YES if the string value of the expression $dayOfWeek contains the string “ues”.

If $dayOfWeek yields the string “Tuesday”, the expression will return YES. For any other day of the week, the expression returns NO.

Discussion

This Mockingbird function accepts two input parameters:

• The string to test, a string expression that will be tested to see if it contains the substring.

• The substring, a string expression yielding the substring to be found within string to test.

The function returns a two-element array containing NSNumbers holding the members of the NSRange specifying the location of substring within string to test.

The first element of the returned array will contain the value of the NSRange’s location member. The location indicates the index of the first character of substring found within string to test. If substring is not found, the first element will contain a value equivalent to NSNotFound.

The second element of the returned array contains the length of the NSRange. If substring is found within string to test, this will be the same as the length of substring. If substring is not found, this value will be 0.

Expression usage

^rangeOfString(Today is not your day.|not)

The expression above would return the array [9, 3].