Add iOS example app

Author: wenbinf

.gitignore

@@ -90,3 +90,6 @@ fastlane/test_output
 iOSInjectionProject/
 
 .swiftpm/
+
+Pods/
+.DS_Store

Package.swift

@@ -14,8 +14,8 @@ let package = Package(
             name: "PodcastAPI",
             targets: ["PodcastAPI"]),
         .executable(
-            name: "Example",
-            targets: ["Example"]),
+            name: "ExampleCommandLineApp",
+            targets: ["ExampleCommandLineApp"]),
     ],
     dependencies: [
         .package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", from: "4.0.0"),
@@ -30,7 +30,7 @@ let package = Package(
             name: "PodcastAPITests",
             dependencies: ["PodcastAPI"]),
         .target(
-            name: "Example",
+            name: "ExampleCommandLineApp",
             dependencies: ["PodcastAPI"]),
     ]
 )

README.md

@@ -18,15 +18,7 @@ If you have any questions, please contact [[email protected]](hello@listenno
 [CocoaPods](https://cocoapods.org) is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate PodcastAPI into your Xcode project using CocoaPods, specify it in your `Podfile`:
 
 ```ruby
-pod 'PodcastAPI', '~> 1.0.1'
-```
-
-### Carthage
-
-[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate PodcastAPI into your Xcode project using Carthage, specify it in your `Cartfile`:
-
-```ogdl
-github "ListenNotes/PodcastAPI" ~> 1.0.1
+pod 'PodcastAPI'
 ```
 
 ### Swift Package Manager
@@ -62,7 +54,7 @@ let apiKey = ProcessInfo.processInfo.environment["LISTEN_API_KEY", default: ""]
 // the program would exit before requests return any response
 let client = PodcastAPI.Client(apiKey: apiKey, synchronousRequest: true)
 
-// By default, we do asynchronous requests.
+// By default, we do asynchronous requests, for GUI-based applications on iOS or macOS
 // let client = PodcastAPI.Client(apiKey: apiKey)
 
 // All parameters are passed via this Dictionary[String: String]
@@ -91,12 +83,60 @@ client.search(parameters: parameters) { response in
         print(response.getFreeQuota())
         print(response.getUsage())
         print(response.getNextBillingDate())
+        
+        // If you use PodcastAPI library in a GUI app (e.g., iOS/macOS),
+        // You need to update UI in the main thread
+        // DispatchQueue.main.async {
+        //    self.displayLabel.text = "some text here"
+        // }
     }
 }
 ```
 
 If `apiKey` is an empty string "", then we'll connect to a [mock server](https://www.listennotes.com/api/tutorials/#faq0) that returns fake data for testing purposes.
 
+### synchronousRequest parameter
+
+A command line executable will exit without wait for http async requests to finish. Therefore, we have to make http requests synchronous. Please set the `synchronousRequest` parameter to true when instantiating a Client object:
+
+```swift
+let client = PodcastAPI.Client(apiKey: apiKey, synchronousRequest: true)
+```
+
+In GUI Apps (e.g., iOS / macOS), you don't need to pass a `synchronousRequest` parameter. Just do this:
+
+```swift
+let client = PodcastAPI.Client(apiKey: apiKey)
+```
+
+### Update UI in the main thread
+
+In the completion closure of an API request, you need to update UI in the main thread (`DispatchQueue.main.async`) for GUI apps (e.g., iOS, macOS):
+
+```swift
+client.search(parameters: parameters) { response in
+    if let error = response.error {
+        switch (error) {
+        case PodcastApiError.apiConnectionError:
+            print("Can't connect to Listen API server")
+        case PodcastApiError.authenticationError:
+            print("wrong api key")
+        default:
+            print("unknown error")
+        }
+    } else {
+        if let json = response.toJson() {
+            print(json)
+        }
+        
+        // If you use PodcastAPI library in a GUI app (e.g., iOS/macOS),
+        // You need to update UI in the main thread
+        DispatchQueue.main.async {
+            self.displayLabel.text = "some text here"
+        }
+    }
+}
+```
 
 ### Handling errors
 
@@ -112,3 +152,22 @@ Unsuccessful requests return errors.
 | serverError  | something wrong on our end (unexpected server errors)  |
 
 All errors can be found in [this file](https://github.com/ListenNotes/podcast-api-swift/blob/main/Sources/PodcastAPI/PodcastApiError.swift).
+
+### Run example apps
+
+We provide two example apps: one is a command line app, and the other is an iOS app.
+
+#### Run the command line example app
+
+```sh
+
+# From the root directory of podcast-api-swift, where Package.swift is located:
+
+$ swift run
+```
+
+You can see the code under [Sources/ExampleCommandLineApp](https://github.com/ListenNotes/podcast-api-swift/tree/main/Sources/ExampleCommandLineApp).
+
+#### Run the iOS example app
+
+Just open ExampleIOSApp.xcworkspace with Xcode, from the directory of [Sources/ExampleIOSApp](https://github.com/ListenNotes/podcast-api-swift/tree/main/Sources/ExampleIOSApp).

Sources/.DS_Store

@@ -41,9 +41,9 @@ client.search(parameters: parameters) { response in
         }
 
         // Some account stats
-        print(response.getFreeQuota())
-        print(response.getUsage())
-        print(response.getNextBillingDate())
+        print("Your free quota this month: \(response.getFreeQuota()) requests")
+        print("Your usage this month: \(response.getUsage()) requests")
+        print("Your next billing date: \(response.getNextBillingDate())")
     }
 }