ClarityActivator
public class ClarityActivator : JSONAccess
A class initialised as a single instance conforming to JSONAccess
that is used by the Clarity framework to access client application Clarity JSON files.
The Clarity JSON files contain all the information required to format and print client application logs to the console.
-
A constant that stores the result of a closure that computes whether the client application is in DEBUG mode.
The closure calls
_isDebugAssertConfiguration()
– this function must be called from within the client to return the correct value for the client application.The
isClientInDebugMode
constant is lazily set when first accessed on assignment to the parameterinPrintMode
of the ClarityActivator initialiser by the client application.Note
When accessed by the Clarity framework test target the constant will return the DEBUG build mode state of the framework test target. Evaluating the build mode state of the test target is necessary for the correct operation of certain unit tests including testing the operation ofverifyClarityJSONDirectory(forBundle:)
.Declaration
Swift
public static let isClientInDebugMode: Bool
-
A custom failable initialiser for ClarityActivator that is used by client applications to activate the Clarity logging framework with the given specifications. - Parameters: - externalBundle: The client application main bundle. - inPrintMode: The print mode status: usually set in accordance with the application DEBUG status. If set to the value `true` Clarity will be made active and print messages to the console. - displayStatus: A bool that determines whether or not to display the print mode and activation status of Clarity on initialisation. This parameter defaults to `true` and its inclusion in the activation expression is optional unless setting it to `false`. The main bundle is used to access the user Clarity json files stored in the ClarityJSON folder: these files are used to calculate, format and print to the console details correlating to the index of Clarity print statements and user preferences. This initialiser is not required by the Clarity framework test target during internal testing of the functionality of the framework. The JSON data derived properties are set lazily by calling JSONAccess protocol generic decoding methods. The initialiser is set `@discardableResult` as a convenience for the client application activation API. - Note: Setting `isClientInDebugMode` as the argument to `inPrintMode` will disable Clarity print statements when the client application is in RELEASE mode. If printing Clarity logs is required in RELEASE mode simply pass `true`. Conversely if disabling Clarity print statements is required in DEBUG mode simply pass `false`. Client application DEBUG mode status must be accessed using the `ClarityActivator` computed var `isClientInDebugMode` and NOT via the `DEBUG` macro nor calling `_isDebugAssertConfiguration()` directly within the framework in order to provide the correct value for the client application. - Important: Setting `isClientInDebugMode` as the argument to `inPrintMode` functions as described only when using the Clarity project source code and the client application within the same Workspace during development. In all other cases it is currently impossible for a framework to detect the build configuration of a client and therefore necessary to set `inPrintMode` manually to either `true` or `false` as required. For maximum efficiency ensure that Clarity remains embedded and that `inPrintMode` is set manually to `false` when archiving for release. The main tasks of this initialiser are: - to check whether `inPrintMode` has been set manually to override the application DEBUG status. - to assign the client application main bundle internally so the framework can access the client JSON files. - to verify that the necessary JSON files exist in the client application main bundle. (Detecting corrupt or invalid JSON is handled by the protocol decoder methods).
Activation workflow examples
The Clarity activation initialiser should only be called once in an application.
*SwiftUI App @main workflow*
import Clarity //... @main struct ClientForBigSuriOSApp: App { init() { //Either Automatic activation ClarityActivator(withBundle: Bundle.main, inPrintMode: ClarityActivator.isClientInDebugMode, displayStatus:false) //Or Manual activation (NOT both!) ClarityActivator(withBundle: Bundle.main, inPrintMode: true, displayStatus:false) } //...
*App Delegate workflow*
import Clarity //... func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { //Either Automatic activation ClarityActivator(withBundle: Bundle.main, inPrintMode: ClarityActivator.isClientInDebugMode, displayStatus:false) //Or Manual activation (NOT both!) ClarityActivator(withBundle: Bundle.main, inPrintMode: true, displayStatus:false) //...
Framework as a client workflow
Framework applications that have a single entry point method should activate Clarity in the same way as shown above in the entry point method implementation.
Framework applications that do not have a single entry point will need to implement a class that includes a static variable that lazily stores the result of a closure containing the activation initialiser. This closure will then need to be accessed by all classes, structs or enums that use Clarity. This technique will ensure that Clarity is activated only once and that any failure to activate Clarity will not adversely affect the client framework.
- Important:
Framework applications will need to call the Bundle initialiser
init(for:)
supplying the implementing class as argument to theaClass
parameter to access the correct Bundle for the framework.Framework as a client without a single entry point workflow
// Activation import Clarity class ClarityServiceExample { static let clarityActivation: ClarityActivator? = { return ClarityActivator(withBundle: Bundle(for: ClarityServiceExample.self), inPrintMode: true) }() } // Accessing the activation import Clarity class MyClass { public init(parameterName:Type) { // All essential work here … guard let _ = ClarityService.clarityActivation else{ print("Clarity activation failed") return } // Place Clarity print statement for the initialiser here if required. } // Clarity print statements can now be placed anywhere in the class. } //...
Declaration
Swift
@discardableResult public init?(withBundle externalBundle: Bundle?, inPrintMode: Bool, displayStatus: Bool = true)
-
A method that verifies whether the client application contains the ClarityJSON directory and JSON files required by the Clarity framework.
If this method detects any required file is missing it will print an alert to the console and copy a default version of the missing item or items to the developer machine desktop. These items can then be copied back into the client project in Xcode.
This method also acts as a utility to copy the necessary JSON files to the desktop in a folder named ClarityJSON on the first run of a client application after the framework has been embedded. This folder can then be dragged into the client project as a copied folder reference.
Important
This method will only attempt to verify the ClarityJSON directory, copy missing items to the desktop and print an alert when the value of
inPrintMode
resolves to true.Note
There is no system level API that can directly identify whether a named subdirectory exists in a bundle. Therefore this method checks for the content expected in the subdirectory
ClarityJSON
to verify that the subdirectory itself exists.The actions taken as a consequence of running this method are:
- if there is no directory or it is empty: a full copy is made of the ClarityJSON template folder including template and example entity log JSON files.
- if there are no entity log JSON files: a copy is made of the ClarityJSON template folder containing template and example entity log JSON files.
- if there are no entity log JSON files and either of the user preference JSON files are missing: a copy is made of the ClarityJSON template folder containing default versions of the user preference JSON file that is missing and template and example entity log JSON files.
if either or both of the user preference JSON files are missing and there is a valid entity log JSON file: a copy is made of the ClarityJSON template folder containing default versions of the missing user preference JSON file(s).
Declaration
Swift
@discardableResult public static func verifyClarityJSONDirectory(forBundle externalBundle: Bundle) -> Bool
Parameters
externalBundle
The client application main bundle
Return Value
A Bool signifying whether the ClarityJSON has been verified successfully. The return is a
@discardableResult