Action Codable Quick Start Guide
For iOS, tvOS and macOS development with Swift and Xcode Sample AppsAction Codable
Action Codable controls provide support for several common databases and data formats such as SQLite, JSON, XML and CloudKit using Swift 4’s new Codable
, Encodable
and Decodable
protocols to move information between your data models and our portable ADRecord
and ADRecordSet
formats.
Action Codable includes the following elements:
- ADInstanceArray – Defines a passable array of values used as temporary storage when encoding or decoding an Action Data class. Useful when creating your own custom Encoders and Decoders.
- ADInstanceDictionary – Defines a passable dictionary of
ADRecord
values when encoding or decoding an Action Data class instance. Useful when creating your own custom Encoders and Decoders. - ADRecord – Defines a
ADRecord
as a dictionary of Key/Value pairs where the Key is aString
and the Value isAny
type. - ADRecordSet – Defines an array of
ADRecord
instances that can be sent to or returned from aADDataProvider
or any of the Action Codable controls. - ADSQLEncoder – Encodes a
Codable
orEncodable
class into aADRecord
that can be written into a SQLite database using aADSQLiteProvider
. - ADSQLDecoder – Decodes a
Codable
orDecodable
class from aADRecord
read from a SQLite database using aADSQLiteProvider
. - ADSPONEncoder – Encodes a
Codable
orEncodable
class into aADRecord
that can be written into a SQLite database using aADSPONiteProvider
. - ADSPONDecoder – Decodes a
Codable
orDecodable
class from aADRecord
read from a SQLite database using aADSPONiteProvider
.
ADInstanceArray
Defines a passable array of values used as temporary storage when encoding or decoding an Action Data class. ADInstanceArray
also introduces support for the new Swift Portable Object Notation (SPON) data format that allows complex data models to be encoded in a portable text string that encodes not only property keys and data, but also includes type information about the encoded data. For example:
Example:
let data = "@array[1!, 2!, 3!, 4!]"
let array = ADInstanceArray.decode(data)
The portable, human-readable string format encodes values with a single character type designator as follows:
%
– Bool!
– Int$
– String^
– Float&
– Double*
– EmbeddedNSData
orData
value
Additionally, embedded arrays will be in the @array[...]
format and embedded dictionaries in the @obj:type<...>
format.
Static Functions
escapeValue()
– Converts a given value into a format that can be safely stored in an ADInstanceArray portable, human-readable string format.unescapeValue()
– Converts a value stored in portable, human-readable string format and converts it back to its original format.decode()
– Takes aADInstanceArray
object stored in a portable, human-readable string format and converts it to an array of the original values. For example:let data = "@array[1!, 2!, 3!, 4!]" let array = ADInstanceArray.decode(data)
Properties
subTableName
– Stores the name a subADDataTable
used in a one-to-one foreign key relationship with the main table.subTablePrimaryKey
– Stores the name of the primary key for a subADDataTable
used in a one-to-one foreign key relationship with the main table.subTablePrimaryKeyType
– Stores the primary key type for a subADDataTable
used in a one-to-one foreign key relationship with the main table.storage
– An array of values encoded from the object.
Functions
encode()
– Converts theADInstanceArray
instance to a portable, human-readable string format.
ADInstanceDictionary
Defines a passable dictionary of ADRecord
values when encoding or decoding an Action Data class instance. ADInstanceDictionary
also introduces support for the new Swift Portable Object Notation (SPON) data format that allows complex data models to be encoded in a portable text string that encodes not only property keys and data, but also includes type information about the encoded data. For example:
Example:
let data = "@obj:Rectangle<left!=`0` bottom!=`0` right!=`0` top!=`0`>"
let dictionary = ADInstanceDictionary.decode(data)
The portable, human-readable string format encodes values with a single character type designator as follows:
%
– Bool!
– Int$
– String^
– Float&
– Double*
– EmbeddedNSData
orData
value
Additionally, embedded arrays will be in the @array[...]
format and embedded dictionaries in the @obj:type<...>
format.
Static Functions
escapeValue()
– Converts a given value into a format that can be safely stored in anADInstanceDictionary
portable, human-readable string format.unescapeValue()
– Converts a value stored in portable, human-readable string format and converts it back to its original format.decode()
– Takes aADInstanceDictionary
object stored in a portable, human-readable string format and converts it to a dictionary of the original values. For example:let data = "@obj:Rectangle<left!=`0` bottom!=`0` right!=`0` top!=`0`>" let dictionary = ADInstanceDictionary.decode(data)
Properties
subTableName
– Stores the name a subADDataTable
used in a one-to-one foreign key relationship with the main table.subTablePrimaryKey
– Stores the name of the primary key for a subADDataTable
used in a one-to-one foreign key relationship with the main table.subTablePrimaryKeyType
– Stores the primary key type for a sub ADDataTable used in a one-to-one foreign key relationship with the main table.storage
– A dictionary of key/value pairs from the coded object.typeName
– The name of the type of object being encoded in the dictionary. For example, this would be the name of a class.
Functions
encode()
– Converts the ADInstanceDictionary instance to a portable, human-readable string format.
ADRecord
Defines a ADRecord
as a dictionary of Key/Value pairs where the Key is a String
and the Value is Any
type. A ADRecord
can be returned from or sent to a ADDataProvider
or any of the Action Codable controls.
Example:
let provider = ADSQLiteProvider.shared
let record = try provider.query("SELECT * FROM Categories WHERE id = ?", withParameters: [1])
print(record["name"])
ADRecordSet
Defines an array of ADRecord
instances that can be sent to or returned from a ADDataProvider
or any of the Action Codable controls.
Example:
let provider = ADSQLiteProvider.shared
let records = try provider.getRows(Category.self)
for record in records {
print(record["name"])
}
ADSQLEncoder
Encodes a Codable
or Encodable
class into a ADRecord
that can be written into a SQLite database using a ADSQLiteProvider
. The result is a dictionary of key/value pairs representing the data currently stored in the class. This encoder will automatically handle URLs
and Enums
(if the Enum is value based and also marked Codable
or Encodable
).
Example:
import ActionUtilities
import ActionData
class Category: ADDataTable {
enum CategoryType: String, Codable {
case local
case web
}
static var tableName = "Categories"
static var primaryKey = "id"
static var primaryKeyType: ADDataTableKeyType = .computedInt
var id = 0
var added = Date()
var name = ""
var description = ""
var enabled = true
var highlightColor = UIColor.white.toHex()
var type: CategoryType = .local
var icon: Data = UIImage().toData()
required init() {
}
}
let encoder = ADSQLEncoder()
let category = Category()
let data = try encoder.encode(category)
Remark:
To store UIColors
in the record use the toHex()
extension method and to store UIImages
use the toData()
extension method.
Enumerations
DateEncodingStrategy
– Defines the strategy to use for encodingDate
values.DataEncodingStrategy
– Defines the strategy to use for encodingData
values.
Static Functions
iso8601Formatter
– Shared formatter used to encode a Date as an ISO-8601-formatted string (in RFC 3339 format).
Properties
codingPath
– The path to the element currently being encoded.userInfo
– User specific, additional information to be encoded in the output.dateEncodingStrategy
– The strategy used to encodeDate
properties. The default israwDate
which allow theADSQLiteProvider
to handle the date directly.dataEncodingStrategy
– The strategy used to encodeData
orNSData
properties. The default israwData
which allow theADSQLiteProvider
to handle the data directly.
Initializers
init(dateEncodingStrategy:, dataEncodingStrategy:)
– Creates a new instance of the encoder and sets the default properties.
Public Functions
encode()
– Encodes aCodable
orEncodable
class into aADRecord
that can be written into a SQLite database using aADSQLiteProvider
. The result is a dictionary of key/value pairs representing the data currently stored in the class. This encoder will automatically handle URLs andEnums
(if theEnum
is value based and also markedCodable
orEncodable
). For example:// Sample encodable enum enum SwitchState: String, Codable { case on case off } // Encode `ADRecord` based class let object = MySQLRecordClass() let encoder = ADSQLEncoder() let record = encoder.encode(object)
container(keyedBy:)
– Returns a key/value encoding container for the given key type.unKeyedContainer()
– Returns an unkeyed encoding container.singleValueContainer()
– Returns a single value encoding container.
ADSQLDecoder
Decodes a Codable
or Decodable
class from a ADRecord
read from a SQLite database using a ADSQLiteProvider
. The result is an instance of the class with the properties set from the database record. This decoder will automatically handle URLs
and Enums
(if the Enum is value based and also marked Codable
or Decodable
).
Example:
import ActionUtilities
import ActionData
class Category: ADDataTable {
enum CategoryType: String, Codable {
case local
case web
}
static var tableName = "Categories"
static var primaryKey = "id"
static var primaryKeyType: ADDataTableKeyType = .computedInt
var id = 0
var added = Date()
var name = ""
var description = ""
var enabled = true
var highlightColor = UIColor.white.toHex()
var type: CategoryType = .local
var icon: Data = UIImage().toData()
required init() {
}
}
let encoder = ADSQLEncoder()
let category = Category()
let data = try encoder.encode(category)
let decoder = ADSQLDecoder()
let category2 = try decoder.decode(Category.self, from: data)
Remark:
To retrieve UIColors
in the record use the String.uiColor
extension property and to retrieve UIImages
use the String.uiImage
extension property.
ADSPONEncoder
Encodes a Codable
or Encodable
class into a ADRecord
that can be written into a SQLite database using a ADSPONiteProvider
. The result is a dictionary of key/value pairs representing the data currently stored in the class. This encoder will automatically handle URLs
and Enums
(if the Enum is value based and also marked Codable
or Encodable
).
Example:
import ActionUtilities
import ActionData
class Category: ADDataTable {
enum CategoryType: String, Codable {
case local
case web
}
static var tableName = "Categories"
static var primaryKey = "id"
static var primaryKeyType: ADDataTableKeyType = .computedInt
var id = 0
var added = Date()
var name = ""
var description = ""
var enabled = true
var highlightColor = UIColor.white.toHex()
var type: CategoryType = .local
var icon: Data = UIImage().toData()
required init() {
}
}
let encoder = ADSPONEncoder()
let category = Category()
let data = try encoder.encode(category)
Remark:
To store UIColors
in the record use the toHex()
extension method and to store UIImages
use the toData()
extension method.
Enumerations
DateEncodingStrategy
– The strategy to use for encodingDate
values.DataEncodingStrategy
– The strategy to use for encodingData
values.
Static Functions
iso8601Formatter
– Shared formatter used to encode a Date as an ISO-8601-formatted string (in RFC 3339 format).
Properties
codingPath
– The path to the element currently being encoded.userInfo
– User specific, additional information to be encoded in the output.dateEncodingStrategy
– The strategy used to encodeDate
properties. The default israwDate
which allow theADSPONiteProvider
to handle the date directly.dataEncodingStrategy
– The strategy used to encodeData
or NSData properties. The default is rawData which allow the ADSPONiteProvider to handle the data directly.
Initializers
init(dateEncodingStrategy:dataEncodingStrategy)
– Creates a new instance of the encoder and sets its initial properties.
Public Functions
encode()
– Encodes a Codable orEncodable
class into aADRecord
that can be written into a SQLite database using aADSPONiteProvider
. The result is a dictionary of key/value pairs representing the data currently stored in the class. This encoder will automatically handle URLs andEnums
(if theEnum
is value based and also markedCodable
orEncodable
). For example:// Sample encodable enum enum SwitchState: String, Codable { case on case off } // Example of encoding a class let object = MySQLRecordClass() let encoder = ADSPONEncoder() let record = encoder.encode(object)
container(keyedBy:)
– Returns a key/value encoding container for the given key type.unkeyedContainer()
– Returns an unkeyed encoding container.singleValueContainer()
– Returns a single value encoding container.
ADSPONDecoder
Decodes a Codable
or Decodable
class from a ADRecord
read from a SQLite database using a ADSPONiteProvider
. The result is an instance of the class with the properties set from the database record. This decoder will automatically handle URLs
and Enums
(if the Enum is value based and also marked Codable
or Decodable
).
Example:
import ActionUtilities
import ActionData
class Category: ADDataTable {
enum CategoryType: String, Codable {
case local
case web
}
static var tableName = "Categories"
static var primaryKey = "id"
static var primaryKeyType: ADDataTableKeyType = .computedInt
var id = 0
var added = Date()
var name = ""
var description = ""
var enabled = true
var highlightColor = UIColor.white.toHex()
var type: CategoryType = .local
var icon: Data = UIImage().toData()
required init() {
}
}
let encoder = ADSPONEncoder()
let category = Category()
let data = try encoder.encode(category)
let decoder = ADSPONDecoder()
let category2 = try decoder.decode(Category.self, from: data)
Remark:
To retrieve UIColors
in the record use the String.uiColor
extension property and to retrieve UIImages
use the String.uiImage
extension property.
Enumerations
DateDecodingStrategy
– The strategy to use for encodingDate
values.DataDecodingStrategy
– The strategy to use for encodingData
values.
Static Functions
sqlObject()
– Checks to see if asqlObject
is stored in the given data stream and returns it if it is.iso8601Formatter
– Shared formatter used to encode aDate
as an ISO-8601-formatted string (in RFC 3339 format).
Properties
codingPath
– The path to the current value that is being decoded.userInfo
– User specific information that can be used when decoding an item.dateDecodingStrategy
– The strategy used to decodeDate
properties. The default israwDate
which allow theADSPONiteProvider
to handle the date directly.dataDecodingStrategy
– The strategy used to encodeData
orNSData
properties. The default is rawData which allow theADSPONiteProvider
to handle the data directly.
Initializers
init(dateDecodingStrategy:dataDecodingStrategy)
– Creates a new instance of the decoder.
Public Functions
decode()
– Decodes aCodable
orDecodable
class from aADRecord
read from a SQLite database using aADSPONiteProvider
. The result is an instance of the class with the properties set from the database record. This decoder will automatically handle URLs and Enums (if theEnum
is value based and also markedCodable
orDecodable
). For example:// Sample codable enum enum SwitchState: String, Codable { case on case off } // Example of decoding an object let record = ADSPONiteProvider.shared.query("SELECT * FROM TASKS WHERE ID=1") let decoder = ADSPONDecoder() let task = decoder.decode(Task, from: record)
container(keyedBy:)
– Returns the keyed decoding container for the given key type.unkeyedContainer()
– Returns an unkeyed decoding container.singleValueContainer()
– Returns a single value decoding container.