A2uiBasicCatalogV1.Functions
interface A2uiBasicCatalogV1.Functions
The functions of the A2UI Basic Catalog V1, with one method for each function in the specification except the logical functions and, or, and not, which the catalog implements itself.
The catalog provides the definition of each function and parses the arguments of each call, so implementations only implement the behavior of the functions. Each method receives the parsed arguments and the A2uiExecutionContext of the call. Implementations can throw an A2uiException to report an error to the agent.
Implement openUrl, and override other methods to customize individual functions. Every method except openUrl has a default implementation, which an override can call with super, e.g., to add a check before it.
The A2uiBasicCatalogV1.Functions(context) factory function creates implementations of all methods, including openUrl. To customize individual functions of an existing implementation, such as the one that this factory function creates, delegate to it and override the methods of those functions, e.g., object : A2uiBasicCatalogV1.Functions by A2uiBasicCatalogV1.Functions(context) { … }. In such an object, super calls the default implementations of this interface rather than the methods of the delegate. To reuse the implementations of the delegate, call its methods instead.
Summary
Public functions |
|
|---|---|
open Boolean |
email(value: String, executionContext: A2uiExecutionContext)Implements the A2UI |
open String |
formatCurrency(Implements the A2UI |
open String |
formatDate(Implements the A2UI |
open String |
formatNumber(Implements the A2UI |
open String |
formatString(value: String, executionContext: A2uiExecutionContext)Implements the A2UI |
open Boolean |
length(Implements the A2UI |
open Boolean |
numeric(Implements the A2UI |
Unit |
openUrl(url: String, executionContext: A2uiExecutionContext)Implements the A2UI |
open String |
pluralize(Implements the A2UI |
open Boolean |
regex(Implements the A2UI |
open Boolean |
required(value: Any?, executionContext: A2uiExecutionContext)Implements the A2UI |
Public functions
open fun email(value: String, executionContext: A2uiExecutionContext): Boolean
Implements the A2UI "email" function, which checks that a string is a valid email address.
The default implementation matches values against a common email address pattern.
| Parameters | |
|---|---|
value: String |
the string to check |
executionContext: A2uiExecutionContext |
the |
formatCurrency
open fun formatCurrency(
value: Double,
currency: String,
decimals: Int?,
grouping: Boolean,
executionContext: A2uiExecutionContext
): String
Implements the A2UI "formatCurrency" function, which formats an amount of money for display.
The default implementation formats amounts with java.text.NumberFormat in the default locale.
| Parameters | |
|---|---|
value: Double |
the monetary amount to format |
currency: String |
the ISO 4217 currency code, e.g., |
decimals: Int? |
the number of decimal places to show, or |
grouping: Boolean |
whether to use locale-specific grouping separators, e.g., |
executionContext: A2uiExecutionContext |
the |
| Returns | |
|---|---|
String |
the formatted amount |
formatDate
open fun formatDate(
epochMillis: Long,
format: String,
executionContext: A2uiExecutionContext
): String
Implements the A2UI "formatDate" function, which formats a date for display.
The default implementation formats dates in UTC with java.text.SimpleDateFormat in the default locale.
| Parameters | |
|---|---|
epochMillis: Long |
the date to format, in milliseconds since the Unix epoch |
format: String |
the Unicode TR35 date pattern, e.g., |
executionContext: A2uiExecutionContext |
the |
| Returns | |
|---|---|
String |
the formatted date |
formatNumber
open fun formatNumber(
value: Double,
decimals: Int?,
grouping: Boolean,
executionContext: A2uiExecutionContext
): String
Implements the A2UI "formatNumber" function, which formats a number for display.
The default implementation formats numbers with java.text.NumberFormat in the default locale.
| Parameters | |
|---|---|
value: Double |
the number to format |
decimals: Int? |
the number of decimal places to show, or |
grouping: Boolean |
whether to use locale-specific grouping separators, e.g., |
executionContext: A2uiExecutionContext |
the |
| Returns | |
|---|---|
String |
the formatted number |
formatString
open fun formatString(value: String, executionContext: A2uiExecutionContext): String
Implements the A2UI "formatString" function, which interpolates expressions in a string.
The default implementation replaces the ${expression} placeholders in value with the results that executionContext evaluates, and handles escape sequences as the specification defines.
| Parameters | |
|---|---|
value: String |
the string to format, which can contain data model paths and function calls in |
executionContext: A2uiExecutionContext |
the |
| Returns | |
|---|---|
String |
the formatted string |
length
open fun length(
value: String,
min: Int,
max: Int,
executionContext: A2uiExecutionContext
): Boolean
Implements the A2UI "length" function, which checks the length of a string.
The default implementation measures values with String.length, including both bounds.
| Parameters | |
|---|---|
value: String |
the string to check |
min: Int |
the minimum allowed length, which is 0 if the call doesn't specify one |
max: Int |
the maximum allowed length, which is |
executionContext: A2uiExecutionContext |
the |
numeric
open fun numeric(
value: Double,
min: Double,
max: Double,
executionContext: A2uiExecutionContext
): Boolean
Implements the A2UI "numeric" function, which checks that a number is within a range.
The default implementation includes both bounds.
| Parameters | |
|---|---|
value: Double |
the number to check |
min: Double |
the minimum allowed value, which is |
max: Double |
the maximum allowed value, which is |
executionContext: A2uiExecutionContext |
the |
openUrl
fun openUrl(url: String, executionContext: A2uiExecutionContext): Unit
Implements the A2UI "openUrl" function, which opens a URL in a browser or another app.
This method has no default implementation, because how to open a URL depends on the app. The A2uiBasicCatalogV1.Functions(context) factory function creates an implementation that opens URLs with an android.content.Intent.ACTION_VIEW intent.
| Parameters | |
|---|---|
url: String |
the non-empty URL to open |
executionContext: A2uiExecutionContext |
the |
pluralize
open fun pluralize(
value: Double,
zero: String?,
one: String?,
two: String?,
few: String?,
many: String?,
other: String,
executionContext: A2uiExecutionContext
): String
Implements the A2UI "pluralize" function, which selects a string by the plural category of a number.
The default implementation selects strings with the ICU plural rules of the default locale.
| Parameters | |
|---|---|
value: Double |
the number that determines the plural category |
zero: String? |
the string for the |
one: String? |
the string for the |
two: String? |
the string for the |
few: String? |
the string for the |
many: String? |
the string for the |
other: String |
the string for all other categories |
executionContext: A2uiExecutionContext |
the |
regex
open fun regex(
value: String,
pattern: String,
executionContext: A2uiExecutionContext
): Boolean
Implements the A2UI "regex" function, which checks that a value matches a regular expression.
The default implementation matches values with kotlin.text.Regex.
| Parameters | |
|---|---|
value: String |
the string to check |
pattern: String |
the regular expression that |
executionContext: A2uiExecutionContext |
the |
required
open fun required(value: Any?, executionContext: A2uiExecutionContext): Boolean
Implements the A2UI "required" function, which checks that a value is present and not empty.
Unlike other functions, this function is called when its value argument can't be resolved, e.g., when it binds to a missing data model path. The default implementation treats null and empty strings, collections, maps, and arrays as missing.
| Parameters | |
|---|---|
value: Any? |
the value to check, or |
executionContext: A2uiExecutionContext |
the |