ClarityActivator

The client application main bundle.

This is the bundle property used by ClarityActivator to access the client application ClarityJSON directory. It is set by the client application calling the custom ClarityActivator initialiser that acts as the framework activator.

A constant that stores the bundle that ClarityActivator uses to access the ClarityJSON directory.

The constant is assigned the variable externalBundle when embedded in a client as the active scheme or assigned the Clarity framework bundle when Clarity framework is running unit tests as the active scheme.

A constant that stores the result of a closure that computes whether the client application is in DEBUG mode. The functionality of this constant will only work as intended if Clarity is installed as an embedded framework.

See Docc extensions folder for details.

A Bool that signifies whether the ClarityActivator initialiser parameter inPrintMode: is set manually to true rather than via the closure constant isClientInDebugMode.

If the value of the parameter inPrintMode: is set to true Clarity will print messages to the console when a client application is in RELEASE build mode overriding the usual behaviour of disabling Clarity print statements.

A Bool that signifies whether the ClarityActivator initialiser parameter inPrintMode: is set manually to false rather than via the closure constant isClientInDebugMode.

If the value of the parameter inPrintMode: is set to false Clarity will disable Clarity print statements when a client application is in DEBUG build mode overriding the usual behaviour of printing messages to the console.

A static variable that lazily stores the result of a closure that returns an array of EntityLogService instances decoded from JSON files in the ClarityJSON folder.

The closure returns the result of calling decoderServicesFromBundle<T: Decodable>(_: inSubDirectory:excludingFiles:) -> [T].

In the event that a client application contains Clarity print statements but the referenced EntityLogService JSON files are missing from the ClarityJSON folder (orphaned print numbers) MessageCollator will hand an empty dictionary of messages to the print logic. The print logic will then simply ignore any Clarity print calls rather than crash.

The referenced EntityLogService JSON files can then be restored to the ClarityJSON folder and any print statements contained in a client application will print logs to the console as before. An alert will be printed to the console for every orphaned print number if the setting alertOrphanedPrintNumbersDetected is true.

This behaviour means that Clarity print statements with their index arguments can remain in place without defaulting to Swift.print() for as long as the Clarity framework remains embedded and referenced with an import statement.

The closure is also the point where internal print setting warning checks are made if Clarity printing is active in the client application. Internal printing is for Clarity framework development print logs and is included because it would be inadvisable to use a compiled version of Clarity itself to print logs to the console. This alert is a reminder to reset internal printing to false so that unnecessary logs are not printed in a client application.

A static variable that lazily stores the result of a closure that returns an optional SettingsManagerService instance decoded from the JSON file named Settings.json in the ClarityJSON folder.

The closure returns the result of calling decoderServiceFromBundle<T: Decodable>(_: inSubdirectory:forResourceName:) -> T?.

A static variable that lazily stores the result of a closure that returns an optional FormattingManagerService instance decoded from the JSON file named Formatting.json in the ClarityJSON folder.

The closure returns the result of calling decoderServiceFromBundle<T: Decodable>(_: inSubdirectory:forResourceName:) -> T?.

If the variable is set to nil the JSONAccess protocol extension method printAlertForCorruptJSON(for: ) or the method verifyClarityJSONDirectory(forBundle:)-> Bool will present an alert and take action depending on the circumstance.

A custom failable initialiser for ClarityActivator that is used by client applications to activate Clarity with the given specifications.

An enum for storing the state of the missing item status of the ClarityJSON directory.

An enum for storing the state of a successful file copy procedure.

This enum is used by ClarityActivator to pass the outcome of a successful file copy procedure to the printAlertForMissingFile(_: forDirectoryState:withResult:) -> String method for printing an alert to the console.

If the copy procedure involved renaming an existing file or folder it passes the new name as an associated value to the replaceCopy case.

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.

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).

A helper method used by verifyClarityJSONDirectory(forBundle:) to set the state of the directoryState ClarityJSONDirectoryState enum.

This method sets the directoryState enum according to the client application required ClarityJSON directory JSON missing file status.

An intermediary method called by copyReplacementJSONToDesktop(forDirectoryState:) that is necessary to print the correct combination of messages to the console in the event of a file copy error.

The method first calls printAlertForMissingFile(_:forDirectoryState:withResult:) passing on its parameter arguments before evaluating the error.

If the error is the unauthorised permission error code 513 it will then call printManualTemplateCopyInstructionsScript().

A method used by copyReplacementJSONToDesktop(forDirectoryState:) to select and call the correct helper method to use to remove default files that are not required for replacing missing files from the default ClarityJSON directory copied to the desktop.

It calls a specific helper method depending on the value of the ClarityJSONDirectoryState enum and then calls appropriate print alert methods passing the required parameter arguments in each case.

A method that copies a default version of the ClarityJSON directory and / or any of its required JSON files to the developer desktop if they are missing from the client application.

This method takes a ClarityJSONDirectoryState enum and uses it to identify missing items. It then attempts to copy any missing JSON file from the TemplateJSON folder resource into a new folder on the desktop that it names ClarityJSON.

If any item already exists on the desktop with the same name as a missing item the existing item will be renamed.

An alert is then printed to the console that describes the action taken and the steps required to copy any missing item(s) back into the project.

If only a single preference file is missing from the client ClarityJSON directory then a default copy of that file will be made and placed on the desktop (and not placed in an enclosing folder).

There are six main task phases to the method:

1. Get the source url TemplateJSON folder (from derived data path or relative to the file location)
2. Get the destination URLs for specific files/folder to be copied on to the desktop).
3. Create backup name URL for any pre-existing ClarityJSON folder on the desktop.
4. Switch on the ClarityJSONDirectoryState and assign final source and destination URLs and components depending on what item(s|) are missing.
5. Assign a pre-existing file enquiry path: either for a missing preference file or for the ClarityJSON folder
6. Attempt to copy missing items, removing and renaming any pre existing items.

A helper method used by copyReplacementJSONToDesktop(forDirectoryState:) to remove default preference files that are not required for replacing missing files from the default ClarityJSON directory copied to the desktop.

This method reads the name of any missing preference file and then removes any non-missing preference file contained in the default directory. If the missingFileName parameter is omitted both preference files are removed.

A helper method used by copyReplacementJSONToDesktop(forDirectoryState:) to remove template and example EntityLogService JSON files from the default ClarityJSON directory copied to the desktop (when they do not require replacing). The default ClarityJSON directory will then only contain preference files that are missing and need replacing.

An implementation of the JSONAccess protocol method that prints an alert to the console if an attempt to decode a JSON file returns nil.

A method that prints copyright information about the Clarity framework to console on launch of a client application.

A method that compiles an alert and advice message that displays the active state of the Clarity framework.

The method compiles a message that outlines the reasons for the current activation state derived from the client application build configuration DEBUG status and the state of inPrintMode.

The method also provides an explanation of the steps to take to toggle the activation state.

A method that compiles an alert and advice message when either the ClarityJSON directory or any of its contained JSON files required by the Clarity framework has been detected as being missing.

This method composes and returns a single message string for all combinations of missing file or directory and file copy success or fail outcome.

A method that prints to the console the instructions for adding the ClarityJSON folder and JSON files to the client project. It also explains behaviours relating to missing files and their replacement.

A method that prints to the console the instructions for manually copying and renaming the TemplateJSON folder. This will be printed in the event that a permissions issue prevented Clarity from copying it to the developer desktop automatically.