Merge pull request #7 from OutSystems/development

RMET-3028 ::: Prepare v1.0.0 Release

Author: OS-ricardomoreirasilva

.github/workflows/github_actions.yml

@@ -11,10 +11,14 @@ jobs:
   test:
     name: Unit-Tests
     runs-on: macos-latest
-
     steps:
     - name: Checkout
-      uses: actions/checkout@v1
+      uses: actions/checkout@v4
+    - name: Setup Java 17
+      uses: actions/setup-java@v3
+      with:
+        distribution: 'zulu'
+        java-version: '17'
     - name: Bundle Install
       run: bundle install
     - name: Unit tests
@@ -26,7 +30,7 @@ jobs:
     - name: Lint
       run: bundle exec fastlane lint
     - name: Setup sonarqube
-      uses: warchant/setup-sonar-scanner@v3      
+      uses: warchant/setup-sonar-scanner@v7
     - name: Send to Sonarcloud
       run: bundle exec fastlane sonarqube
       env: 

.gitignore

@@ -88,3 +88,4 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+.swiftlint.yml

OSBarcodeLib.xcodeproj/project.pbxproj

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "1330"
+   LastUpgradeVersion = "1500"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"

OSBarcodeLib.xcodeproj/xcshareddata/xcschemes/OSBarcodeLib.xcscheme

@@ -0,0 +1,11 @@
+/// Base class implemented by all classes that require UI interaction (push and dismiss operations).
+class OSBARCCoordinatable {
+    /// Object responsible for managing the user interface screens and respective flow.
+    private(set) var coordinator: OSBARCCoordinatorProtocol
+    
+    /// Constructor.
+    /// - Parameter coordinator: Object responsible for managing the user interface screens and respective flow.
+    init(coordinator: OSBARCCoordinatorProtocol) {
+        self.coordinator = coordinator
+    }
+}

OSBarcodeLib/Coordinator/OSBARCCoordinatable.swift

@@ -0,0 +1,24 @@
+import UIKit
+
+/// Object responsible for managing the screen flow, in response to the user's interaction.
+struct OSBARCCoordinator {
+    /// Root view controller, from whom every view gets pushed on top of.
+    private let rootViewController: UIViewController
+    
+    /// Construtor.
+    /// - Parameter rootViewController: Root view controller, from whom every view gets pushed on top of.
+    init(rootViewController: UIViewController) {
+        self.rootViewController = rootViewController
+    }
+}
+
+/// Implements the `OSBARCCoordinatorProtocol` methods
+extension OSBARCCoordinator: OSBARCCoordinatorProtocol {
+    func present(_ viewController: UIViewController) {
+        self.rootViewController.present(viewController, animated: true)
+    }
+    
+    func dismiss() {
+        self.rootViewController.dismiss(animated: true)
+    }
+}

OSBarcodeLib/Coordinator/OSBARCCoordinator.swift

@@ -0,0 +1,11 @@
+import UIKit
+
+/// Protocol that allows pushing and poping views on top of the root view controller.
+protocol OSBARCCoordinatorProtocol {
+    /// Presents the passed view controller, adding it to the currently presented view controller array.
+    /// - Parameter viewController: New view controller to present.
+    func present(_ viewController: UIViewController)
+    
+    /// Dismisses the currently presented view controllers. In case of a multiple step screen, all are dismissed.
+    func dismiss()
+}

OSBarcodeLib/Coordinator/OSBARCCoordinatorProtocol.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// All errors related with the `OSBARCManager` structure.
+public enum OSBARCManagerError: Error {
+    case cameraAccessDenied
+    case scanningCancelled
+}
+
+/// Structure responsible for managing all barcode scanning flow.
+struct OSBARCManager {
+    /// Responsible for verifying the device's authorisation to its camera. It also handles the required flow to enable this authorisation.
+    private let permissionsBehaviour: OSBARCPermissionsProtocol
+    /// Responsible for triggering the barcode scanner view.
+    private let scannerBehaviour: OSBARCScannerProtocol
+    
+    /// Constructor.
+    /// - Parameters:
+    ///   - permissionsBehaviour: Responsible for verifying the device's authorisation to its camera. It also handles the required flow to enable this authorisation.
+    ///   - scannerBehaviour: Responsible for triggering the barcode scanner view.
+    init(permissionsBehaviour: OSBARCPermissionsProtocol, scannerBehaviour: OSBARCScannerProtocol) {
+        self.permissionsBehaviour = permissionsBehaviour
+        self.scannerBehaviour = scannerBehaviour
+    }
+    
+    /// Convenience constructor
+    /// - Parameter coordinator: Object responsible for managing the screen flow, in response to the user's interaction.
+    init(coordinator: OSBARCCoordinatorProtocol) {
+        let permissionsBehaviour = OSBARCPermissionsBehaviour(coordinator: coordinator)
+        let scannerBehaviour = OSBARCScannerBehaviour(coordinator: coordinator)
+        self.init(permissionsBehaviour: permissionsBehaviour, scannerBehaviour: scannerBehaviour)
+    }
+}
+
+/// Implementation of the `OSBARCManagerProtocol` methods.
+extension OSBARCManager: OSBARCManagerProtocol {
+    func scanBarcode(with instructionsText: String, _ buttonText: String?, _ cameraModel: OSBARCCameraModel, and orientationModel: OSBARCOrientationModel) async throws -> String {
+        // validates if the user has access to the device's camera.
+        let hasCameraAccess = await self.permissionsBehaviour.hasCameraAccess()
+        if !hasCameraAccess { throw OSBARCManagerError.cameraAccessDenied }
+        // requests the scanner to start, treating its result value.
+        return try await withCheckedThrowingContinuation {
+            self.startScanning(with: instructionsText, buttonText, cameraModel, and: orientationModel, continuation: $0)
+        }
+    }
+    
+    /// Triggers the scanner view.
+    /// - Parameters:
+    ///   - instructionsText: Text to be displayed on the scanner view.
+    ///   - buttonText: Text to be displayed for the scan button, if this is configured. `Nil` value means that the button will not be shown.
+    ///   - cameraModel: Camera to use for input gathering.
+    ///   - orientationModel: Scanner view's orientation.
+    ///   - continuation: Object responsible for returning the method's result to its caller.
+    private func startScanning(
+        with instructionsText: String,
+        _ buttonText: String?,
+        _ cameraModel: OSBARCCameraModel,
+        and orientationModel: OSBARCOrientationModel,
+        continuation: CheckedContinuation<String, any Error>
+    ) {
+        DispatchQueue.main.async {
+            self.scannerBehaviour.startScanning(with: instructionsText, buttonText, cameraModel, and: orientationModel) { scannedCode in
+                if !scannedCode.isEmpty {
+                    continuation.resume(returning: scannedCode)
+                } else {
+                    continuation.resume(throwing: OSBARCManagerError.scanningCancelled)
+                }
+            }
+        }
+    }
+}

OSBarcodeLib/Manager/OSBARCManager.swift

@@ -0,0 +1,13 @@
+import UIKit
+
+/// Structure responsible for creating the scanner flow manager..
+public struct OSBARCManagerFactory {
+    /// Creates the scanner flow manager.
+    /// - Parameter rootViewController: Root view controller, from whom every view gets pushed on top of.
+    /// - Returns: The resulting scanner flow manager.
+    public static func createManager(with rootViewController: UIViewController) -> OSBARCManagerProtocol {
+        let coordinator = OSBARCCoordinator(rootViewController: rootViewController)
+        // it calls the `OSBARCManager`'s convenience constructor.
+        return OSBARCManager(coordinator: coordinator)
+    }
+}

OSBarcodeLib/Manager/OSBARCManagerFactory.swift

@@ -0,0 +1,14 @@
+/// Protocol that contains the main features of the library.
+public protocol OSBARCManagerProtocol {
+    /// Triggers the barcode scanner, returning, if possible, the scanned value.
+    /// It can throw:
+    ///     `cameraAccessDenied`: If camera access has not been given.
+    ///     `scanningCancelled`: If scanning has been cancelled.
+    /// - Parameters:
+    ///   - instructionsText: Text to be displayed on the scanner view.
+    ///   - buttonText: Text to be displayed for the scan button, if this is configured. `Nil` value means that the button will not be shown.
+    ///   - cameraModel: Camera to use for input gathering.
+    ///   - orientationModel: Scanner view's orientation.
+    /// - Returns: When successful, it returns the text associated with the scanned barcode.
+    func scanBarcode(with instructionsText: String, _ buttonText: String?, _ cameraModel: OSBARCCameraModel, and orientationModel: OSBARCOrientationModel) async throws -> String
+}