mysqlclient 8.0.31: Major update of the library (#38)

.github/workflows/documentation.yml

@@ -0,0 +1,32 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ master ]
+
+env:
+  DEVELOPER_DIR: /Applications/Xcode_14.0.1.app/Contents/Developer
+
+jobs:
+  Generate:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Generate archive
+      run: |
+        xcodebuild docbuild \
+          -scheme 'OHMySQL' \
+          -derivedDataPath ./build \
+          -destination 'platform=iOS Simulator,OS=latest,name=iPhone 13'
+    - name: Generate pages
+      run: |
+        $(xcrun --find docc) process-archive transform-for-static-hosting \
+          $(find ./build -type d -name '*.doccarchive') \
+          --hosting-base-path OHMySQL \
+          --output-path ./docs
+    - name: Deploy documentation to Github Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs
+        keep_files: true

.github/workflows/ohmysql.yml

@@ -1,19 +1,30 @@
-name: MySQL iOS
+name: Validation and Tests
 
 on:
   push:
-    branches: [ develop ]
+    branches: 
+      - master
+  pull_request:
+    branches:
+      - master
 
 jobs:
+  CocoaPodsValidation:
+    runs-on: macos-11
+    steps:
+    - uses: actions/checkout@v2
+    - name: Cocoapods
+      run: pod lib lint --allow-warnings
   UnitTests:
     runs-on: macos-11
     steps:
-    - uses: ankane/setup-mysql@v1
+    - name: Setup MySQL
+      uses: ankane/setup-mysql@v1
       with:
         mysql-version: 8.0
         database: tests
     - uses: actions/checkout@v2
-    - name: Install deps
+    - name: Install dependencies
       run: |
         pod install --project-directory=SampleProject
     - name: Run tests 
@@ -24,9 +35,3 @@ jobs:
         DB_HOST='localhost' \
         DB_PORT='3306' \
         DB_SOCKET='/tmp/mysql.sock' | xcpretty
-  # PackageValidation:
-  #   runs-on: macos-11
-  #   steps:
-  #   - uses: actions/checkout@v2
-  #   - name: Cocoapods
-  #     run: pod lib lint

OHMySQL.docc/GettingStarted.md

@@ -0,0 +1,95 @@
+# Getting Started
+
+Set up the classes that manage and persist your data. 
+
+## Overview
+
+* An instance of ``OHMySQLConfiguration`` represents your connection preferences. 
+* An instance of ``OHMySQLStoreCoordinator`` manages a connection to the database.
+* An instance of ``OHMySQLQueryContext`` saves and fetches data from storage, executes the queries.
+
+### Initialize a Store Coordinator
+
+Typically, you need to keep only one instance of ``OHMySQLStoreCoordinator`` in your code. One instance is a one connection. 
+
+1. Create configuration preference instance:
+    ```swift
+    let configuration = MySQLConfiguration(userName: "root", password: "root", serverName: "localhost", dbName: "db_name", port: 3306, socket: "/mysql/mysql.sock")
+    ```
+    If your connection is configured for SSL, you can specify this at creation:
+    ```swift
+    let sslConfig = MySQLSSLConfig(key: "client-key.pem", certPath: "client-cert.pem", certAuthPath: "ca.pem", certAuthPEMPath: "", cipher: nil)
+    let configuration = MySQLConfiguration(userName: "root", password: "root", sslConfig: sslConfig, serverName: "localhost", dbName: "db_name", port: 3306, socket: "/mysql/mysql.sock")
+    ```
+
+2. Create a store coordinator.
+    ```swift
+    let coordinator = MySQLStoreCoordinator(user: configuration)
+    ```
+
+    If required, you can set up the encoding and protocol type.
+    ```swift
+    coordinator.encoding = .UTF8MB4
+    coordinator.protocol = .TCP
+    ```
+
+3. Connect to the database. The method ``OHMySQLStoreCoordinator/connect`` returns a boolean value indicating if a connection is set up. 
+    ```swift
+    if coordinator.connect() {
+       print("Connected successfully.")
+    }
+    ```
+
+### Configure Query Context
+
+The instance of ``OHMySQLQueryContext`` is responsible for executing queries, saving/updating/deleting model objects. It is a key object in the application.
+
+1. There must be only one **main** context in the application.
+    ```swift
+    let context = MySQLQueryContext()
+    ```
+
+2. The context must keep a reference to store coordinator. 
+    ```swift
+    context.storeCoordinator = coordinator
+    ```
+
+3. For your convenience, set a context into singleton of ``OHMySQLContainer``. 
+    ```swift
+    MySQLContainer.shared.mainQueryContext = context
+    ```
+
+    You can always access the main context in any place of your code:
+    ```swift
+    MySQLContainer.shared.mainQueryContext?.lastInsertID()
+    ```
+
+### Execute Query
+
+Every query is represented by a string. An instance of ``OHMySQLQueryRequest`` initialized with a string and provides timeline information after execution.
+
+Typically, there are two types of queries.
+The first type doesn't return any result. It executes the query and you can catch the error if any appears.
+
+```swift
+let queryString = "DROP TABLE `mytable`"
+let queryRequest = MySQLQueryRequest(queryString: dropQueryString)
+
+do {
+    try MySQLContainer.shared.mainQueryContext?.execute(dropQueryRequest)
+} catch {
+    print("Cannot execute the query.")
+}
+```
+
+The second type does return a result. The result is an array of dictionaries.
+```swift
+let queryString = "SELECT * FROM `mytable`"
+let queryRequest = MySQLQueryRequest(queryString: queryString)
+do {
+    let result = try MySQLContainer.shared.mainQueryContext?.executeQueryRequestAndFetchResult(query) ?? []
+    print("\(result)")
+} catch {
+    print("Cannot execute the query.")
+}
+```

OHMySQL.docc/Installation.md

@@ -0,0 +1,53 @@
+# Installation
+
+Learn the ways to integrate the framework in your application.
+
+## Overview
+
+The framework can be installed in different ways.
+
+### CocoaPods
+
+Open `Podfile` and declare the dependency:
+```bash
+pod 'OHMySQL'
+```
+
+Then open Terminal, navigate to project folder and install the dependencies:
+```
+pod install --repo-update
+```
+
+> Tip: Learn how to use [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
+
+### Carthage
+
+Add the following to your `Cartfile`:
+```bash
+github "oleghnidets/OHMySQL"
+```
+
+Run the command for updating Carthage dependencies. 
+```
+carthage update --use-xcframeworks OHMySQL
+```
+
+In addition to manually adding xcframework of OHMySQL from `Carthage/Build` folder you will need to add manually `MySQL.xcframework`. `MySQL.xcframework` is a part of this repo, see `OHMySQL/lib/MySQL.xcframework`.
+
+> Tip: Learn how to use [Carthage](https://github.com/Carthage/Carthage#quick-start).
+
+### Manually
+
+Open up Terminal and clone the repo.
+```
+git clone https://github.com/oleghnidets/OHMySQL
+```
+
+Open cloned repo folder and copy the folder `OHMySQL`. Paste the folder into your project folder.
+
+Open up your project (xcodeproj) and drag the folder `OHMySQL` into the Project Navigator of your application's Xcode project.
+
+Navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar. In the tab bar at the top of that window, open the "General" panel. Make sure there is the framework `MySQL.xcframework` under the "Frameworks & Libraries" section. If not, click on the `+` button and add the framework. Also, you will need to add the library `libc++`. 
+
+
+

OHMySQL.docc/OHMySQL.md

@@ -0,0 +1,35 @@
+# ``OHMySQL``
+
+The framework allows to establish a connection with MySQL database. The framework supports Objective-C and Swift, iOS, macOS, Catalyst, tvOS, watchOS. 
+
+## Overview
+
+OHMySQL can connect to remote or local MySQL database and execute CRUD operations. The framework is built upon MySQL C API, but you don't need to dive into low-level.
+The following diagram represents a general architecture. Logic (saving, editing, removing etc.) is aggregated in the app. The database is just a shared storage.
+
+![Simple Diagram](diagram.png)
+
+## Topics
+
+### Essentials
+
+- <doc:Installation>
+- <doc:GettingStarted>
+
+### Setup connection
+
+- ``OHMySQLConfiguration``
+- ``OHSSLConfig``
+- ``OHMySQLStoreCoordinator``
+- ``OHMySQLContainer``
+- ``OHMySQLQueryContext``
+
+### Execute Query
+
+- ``OHMySQLQueryRequest``
+- ``OHMySQLQueryRequestFactory``
+
+### Object Mapping
+
+- ``OHMySQLMappingProtocol``
+

OHMySQL.podspec

@@ -3,21 +3,23 @@
 
 Pod::Spec.new do |spec|
   spec.name             = 'OHMySQL'
-  spec.version          = '3.1.1'
+  spec.version          = '3.2.0'
 
   spec.summary          = 'The Objective-C wrapper for mysqlclient (MySQL C API)'
   spec.description      = <<-DESC
 You can connect to your remote MySQL database using OHMySQL API. It allows you doing queries in easy and object-oriented way. Common queries such as SELECT, INSERT, DELETE, JOIN are wrapped by Objective-C code and you don't need to dive into MySQL C API.
                        DESC
 
-  spec.documentation_url = 'http://oleghnidets.github.io/OHMySQL/'
+  spec.documentation_url = 'https://oleghnidets.github.io/OHMySQL/documentation/ohmysql/'
   spec.homepage          = 'https://github.com/oleghnidets/OHMySQL'
   spec.license           = 'MIT'
   spec.authors           = { 'Oleg Hnidets' => 'oleg.oleksan@gmail.com' }
 
   spec.source           = { :git => 'https://github.com/oleghnidets/OHMySQL.git', :tag => spec.version.to_s }
   spec.ios.deployment_target = '14.0'
   spec.osx.deployment_target = '11.0'
+  spec.watchos.deployment_target = '8.0'
+  spec.tvos.deployment_target = '15.0'
   spec.requires_arc     = true 
   spec.source_files     = 'OHMySQL/Sources/**/*.{h,m}'
   spec.frameworks       = 'Foundation'