Update to the async wait api and add new get scientist api

ezefranca · Jul 25, 2024 · b88b9cc · b88b9cc
1 parent 283e051
commit b88b9cc
Show file tree

Hide file tree

Showing 14 changed files with 512 additions and 387 deletions.
diff --git a/Package.swift b/Package.swift
@@ -5,14 +5,16 @@ import PackageDescription
 
 let package = Package(
     name: "GoogleScholarSwift",
+    platforms: [
+        .iOS(.v13),
+        .macOS(.v12),
+        .tvOS(.v13),
+        .watchOS(.v6)
+    ],
     products: [
         .library(
             name: "GoogleScholarSwift",
             targets: ["GoogleScholarSwift"]),
-        .executable(
-            name: "GoogleScholarSwiftCLI",
-            targets: ["GoogleScholarSwiftCLI"]
-        )
     ],
     dependencies: [
         .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.7.2"),
@@ -22,12 +24,8 @@ let package = Package(
         .target(
             name: "GoogleScholarSwift",
             dependencies: ["SwiftSoup"]),
-        .executableTarget(
-            name: "GoogleScholarSwiftCLI",
-            dependencies: ["GoogleScholarSwift"]
-        ),
         .testTarget(
             name: "GoogleScholarSwiftTests",
-            dependencies: ["GoogleScholarSwift"]),
+            dependencies: ["GoogleScholarSwift"])
     ]
 )
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ To integrate `GoogleScholarSwift` into your Xcode project using Swift Package Ma
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/ezefranca/GoogleScholarSwift.git", from: "1.0.1")
+    .package(url: "https://github.com/ezefranca/GoogleScholarSwift.git", from: "1.3.0")
 ]
 ```
 
@@ -33,139 +33,143 @@ Fetches all publications for a given author from Google Scholar.
 
 ```swift
 public func fetchAllPublications(
-    authorID: String,
-    maxPublications: Int? = nil,
-    sortBy: String = "cited",
-    completion: @escaping ([Publication]?, Error?) -> Void)
+    authorID: GoogleScholarID,
+    fetchQuantity: FetchQuantity = .all,
+    sortBy: SortBy = .cited
+) async throws -> [Publication]
 ```
 
 #### Parameters
 
 - `authorID`: The Google Scholar author ID.
-- `maxPublications`: The maximum number of publications to fetch. If `nil`, fetches all available publications.
+- `fetchQuantity`: The quantity of publications to fetch. Can be `.all` or `.specific(Int)`. Default is `.all`.
 - `sortBy`: The sorting criterion for publications. Can be `.cited` or `.pubdate`. Default is `.cited`.
-- `completion`: A completion handler called with the fetched publications or an error.
+
+#### Returns
+
+- An array of `Publication` objects.
+
+#### Throws
+
+- An error if fetching or parsing fails.
 
 #### Example Usage
 
 ```swift
 let fetcher = GoogleScholarFetcher()
 
 // Fetch all publications for a given author ID
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ") { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-    }
-}
+let publications = try await fetcher.fetchAllPublications(authorID: GoogleScholarID("RefX_60AAAAJ"))
+print(publications)
 
 // Fetch a specific number of publications for a given author ID
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ", maxPublications: 10) { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-    }
-}
+let limitedPublications = try await fetcher.fetchAllPublications(authorID: GoogleScholarID("RefX_60AAAAJ"), fetchQuantity: .specific(10))
+print(limitedPublications)
 
 // Fetch all publications for a given author ID and sort by pubdate
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ", sortBy: "pubdate") { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-    }
-}
+let sortedPublications = try await fetcher.fetchAllPublications(authorID: GoogleScholarID("RefX_60AAAAJ"), sortBy: .pubdate)
+print(sortedPublications)
 ```
 
-### `fetchArticleDetails`
+### `fetchArticle`
 
 Fetches the detailed information for a specific article.
 
 ```swift
-public func fetchArticleDetails(
-    articleDetails: ArticleDetails,
-    completion: @escaping (Article?, Error?) -> Void)
+public func fetchArticle(articleLink: ArticleLink) async throws -> Article
 ```
 
 #### Parameters
 
-- `articleDetails`: An `ArticleDetails` object containing the link to the article.
-- `completion`: A completion handler called with the fetched article details or an error.
+- `articleLink`: An `ArticleLink` object containing the link to the article.
+
+#### Returns
+
+- An `Article` object.
+
+#### Throws
+
+- An error if fetching or parsing fails.
 
 #### Example Usage
 
 ```swift
 let fetcher = GoogleScholarFetcher()
 
-let articleDetails = ArticleDetails(link: "https://scholar.google.com/citations?view_op=view_citation&hl=en&user=6nOPl94AAAAJ&citation_for_view=6nOPl94AAAAJ:UebtZRa9Y70C")
-fetcher.fetchArticleDetails(articleDetails: articleDetails) { article, error in
-    if let error = error {
-        print("Error fetching article details: \(error)")
-    } else if let article = article {
-        print(article)
-    }
-}
+let articleLink = ArticleLink(link: "https://scholar.google.com/citations?view_op=view_citation&hl=en&user=RefX_60AAAAJ&citation_for_view=RefX_60AAAAJ:9yKSN-GCB0IC")
+let article = try await fetcher.fetchArticle(articleLink: articleLink)
+print(article)
+```
+
+### `fetchScientistDetails`
+
+Fetches the scientist's details such as name, affiliation, and picture URL from Google Scholar.
+
+```swift
+public func fetchScientistDetails(scholarID: GoogleScholarID) async throws -> Scientist
+```
+
+#### Parameters
+
+- `scholarID`: The Google Scholar author ID.
+
+#### Returns
+
+- A `Scientist` object containing the scientist's details.
+
+#### Throws
+
+- An error if fetching or parsing fails.
+
+#### Example Usage
+
+```swift
+let fetcher = GoogleScholarFetcher()
+
+let scientistDetails = try await fetcher.fetchScientistDetails(scholarID: GoogleScholarID("6nOPl94AAAAJ"))
+print(scientistDetails)
 ```
 
 ### Complete Example
 
 ```swift
-import GoogleScholarFetcher
+import GoogleScholarSwift
 
 let fetcher = GoogleScholarFetcher()
+let authorID = GoogleScholarID("RefX_60AAAAJ")
 
 // Fetch all publications for a given author ID
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ") { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-
-        // Assuming we want to fetch details of the first publication
-        if let firstPublication = publications.first {
-            let articleDetails = ArticleDetails(link: firstPublication.link)
-            fetcher.fetchArticleDetails(articleDetails: articleDetails) { article, error in
-                if let error = error {
-                    print("Error fetching article details: \(error)")
-                } else if let article = article {
-                    print(article)
-                }
-            }
-        }
-    }
-}
+let publications = try await fetcher.fetchAllPublications(authorID: authorID)
+print("All Publications:", publications)
 
 // Fetch a specific number of publications for a given author ID
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ", maxPublications: 10) { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-    }
-}
+let limitedPublications = try await fetcher.fetchAllPublications(authorID: authorID, fetchQuantity: .specific(10))
+print("Limited Publications:", limitedPublications)
 
 // Fetch all publications for a given author ID and sort by pubdate
-fetcher.fetchAllPublications(authorID: "6nOPl94AAAAJ", sortBy: "pubdate") { publications, error in
-    if let error = error {
-        print("Error fetching publications: \(error)")
-    } else if let publications = publications {
-        print(publications)
-    }
+let sortedPublications = try await fetcher.fetchAllPublications(authorID: authorID, sortBy: .pubdate)
+print("Sorted Publications:", sortedPublications)
+
+// Fetch article details for the first publication
+if let firstPublication = publications.first {
+    let articleLink = ArticleLink(link: firstPublication.link)
+    let article = try await fetcher.fetchArticle(articleLink: articleLink)
+    print("Article Details:", article)
 }
-```
 
+// Fetch scientist details
+let scientistDetails = try await fetcher.fetchScientistDetails(scholarID: authorID)
+print("Scientist Details:", scientistDetails)
+```
 
 ## Contributing
 
 We welcome contributions to `GoogleScholarSwift`! If you have suggestions for improvements, please open an issue or a pull request.
 
-## Similar projects
+## Disclaimer
 
-A python module that does the same: https://github.com/ezefranca/scholarly_publications
+This project is not affiliated with Google and is intended for educational purposes only. The responsibility for the use and interpretation of the data obtained through this project lies solely with the user. The developers and contributors of this project are not liable for any misuse or legal implications arising from the utilization of the data provided. Users are advised to ensure compliance with applicable laws and regulations when using this project.
 
 ## License
 
-`GoogleScholarFetcher` is released under the MIT License. See the LICENSE file for more details.
-
+`GoogleScholarSwift` is released under the MIT License. See the LICENSE file for more details.
diff --git a/Sources/GoogleScholarSwift/Enums/FetchQuantity.swift b/Sources/GoogleScholarSwift/Enums/FetchQuantity.swift
@@ -0,0 +1,9 @@
+import Foundation
+
+/// An enumeration representing the maximum number of publications to fetch.
+public enum FetchQuantity {
+    /// Fetch all available publications.
+    case all
+    /// Fetch a specific number of publications.
+    case specific(Int)
+}
diff --git a/Sources/GoogleScholarSwift/Enums/SortBy.swift b/Sources/GoogleScholarSwift/Enums/SortBy.swift
@@ -0,0 +1,13 @@
+import Foundation
+
+/// Sorting criteria for publications.
+public enum SortBy: String, Codable, Hashable, Equatable, CaseIterable, CustomStringConvertible {
+    /// Sort by number of citations.
+    case cited = "cited"
+    /// Sort by publication date.
+    case pubdate = "pubdate"
+
+    public var description: String {
+        return self.rawValue
+    }
+}