{"id":13537028,"url":"https://github.com/prof18/RSS-Parser","last_synced_at":"2025-04-02T03:31:32.357Z","repository":{"id":9261991,"uuid":"61429036","full_name":"prof18/RSS-Parser","owner":"prof18","description":"A Kotlin Multiplatform library to parse a RSS Feed","archived":false,"fork":false,"pushed_at":"2025-03-24T20:25:58.000Z","size":12997,"stargazers_count":555,"open_issues_count":7,"forks_count":129,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-30T19:01:56.797Z","etag":null,"topics":["android","android-library","rss-feed","rss-parser"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prof18.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.paypal.me/MarcoGomiero"}},"created_at":"2016-06-18T10:44:52.000Z","updated_at":"2025-03-30T13:32:32.000Z","dependencies_parsed_at":"2023-02-19T11:00:49.761Z","dependency_job_id":"98842148-7650-4ff6-985e-25e082c489f7","html_url":"https://github.com/prof18/RSS-Parser","commit_stats":{"total_commits":410,"total_committers":19,"mean_commits":21.57894736842105,"dds":"0.23170731707317072","last_synced_commit":"6e66dbea11b2e76baadd98f166f542784f085d3f"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2FRSS-Parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2FRSS-Parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2FRSS-Parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2FRSS-Parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prof18","download_url":"https://codeload.github.com/prof18/RSS-Parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246751251,"owners_count":20827857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-library","rss-feed","rss-parser"],"created_at":"2024-08-01T09:00:53.747Z","updated_at":"2025-04-02T03:31:32.351Z","avatar_url":"https://github.com/prof18.png","language":"Kotlin","readme":"# RSS Parser\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.prof18.rssparser/rssparser/badge.svg?style=plastic)](https://maven-badges.herokuapp.com/maven-central/com.prof18.rssparser/rssparser)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n![API](https://img.shields.io/badge/API-15%2B-brightgreen.svg?style=flat)\n\n**RSS Parser** is a Kotlin Multiplatform library for parsing RSS, Atom and RDF feeds. It supports Android, iOS, macOS, tvOS, watchOS and the JVM.\n\nWith **RSS Parser**, you can fetch plenty of useful information from any RSS channel, be it a blog, magazine, a YouTube channel or even a podcast feed.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Important Notices](#important-notices)\n    - [Artifact change](#artifact-change)\n    - [Breaking changes](#breaking-changes)\n- [Available data](#available-data)\n- [Usage](#usage)\n    - [Creating a RssParser instance](#creating-a-rssparser-instance)\n        - [Builder](#builder)\n    - [RSS Parsing from URL](#rss-parsing-from-url)\n    - [RSS Parsing from string](#rss-parsing-from-string)\n    - [Using the library in a Java project](#using-the-library-in-a-java-project)\n- [Migration from version 5](#migration-from-version-5)\n- [Sample project](#sample-project)\n- [Changelog](#changelog)\n- [License](#license)\n- [Apps using RSS Parser](#apps-using-rss-parser)\n\n## Installation\n\nRSS Parser is currently published to Maven Central, so add it to your project's repositories.\n\n```kotlin\nrepositories {\n    mavenCentral()\n    // ...\n}\n```\n\nThen, add the dependency to your common source set's dependencies.\n\n```kotlin\ncommonMain {\n    dependencies {\n        // ...\n        implementation(\"com.prof18.rssparser:rssparser:\u003clatest-version\u003e\")\n    }\n}\n```\n\nIf you are in an Android-only project, simply add the dependency:\n\n```kotlin\ndependencies {\n    // ...\n    implementation(\"com.prof18.rssparser:rssparser:\u003clatest-version\u003e\")\n}\n```\n\n## Important Notices\n\n### Artifact change\n\nSince February 2022, the library artifacts have been moved to MavenCentral. The group ID changed from `com.prof.rssparser` to `com.prof18.rssparser`.\nBe sure to add the gradle dependency to your root `build.gradle` file.\n```\nallprojects {\n    repositories {\n        mavenCentral()\n    }\n}\n```\n\n### Breaking changes\n\nFrom version 6.0, RSSParser has become Multiplatform. This update brought some breaking changes:\n\n- Some class names and packages have been changed. Check out the [migration guide](#migration-from-version-5) for further info.\n- Caching of feeds is not supported anymore. After some consideration, I decided that the aim of this library is not meant to provide a caching solution for RSS feeds, but just to do the parsing. The user of the library should implement any caching/storing solutions their project requires.\n- Support for Java with the `OnTaskCompleted` and `onError` callbacks has been dropped. You can still use the library in a Java project, but you will need to write some Kotlin code to handle Coroutines. More details in the [section below](#using-the-library-in-a-java-project).\n\n[Here](https://github.com/prof18/RSS-Parser/blob/version-5/README.md) you can find the README for version 5 of RSSParser.\n\n## Available data\n\nThe [`RssChannel` result object](https://github.com/prof18/RSS-Parser/blob/master/rssparser/src/commonMain/kotlin/com/prof18/rssparser/model/RssChannel.kt) provides the following data:\n\n- Title\n- Description\n- Link\n- Items\n- Image (Title, Url and Link)\n- Last build data\n- Update period\n- Itunes Data:\n  - Author\n  - Categories\n  - Duration  \n  - Explicit\n  - Image\n  - Keywords\n  - News Feed URL\n  - Owner  \n  - Subtitle\n  - Summary\n  - Type\n- Youtube Data\n  - Channel ID\n\nItems support the following attributes:\n\n- Title\n- Author\n- Description\n- Content\n- Image\n- Link\n- Publication Date\n- Categories\n- Audio\n- Source (name and URL)\n- GUID\n- Video\n- Comments URL\n- Itunes Data:\n  - Author\n  - Duration\n  - Episode\n  - Episode Type\n  - Explicit\n  - Image\n  - Keywords\n  - Subtitle\n  - Summary\n  - Season\n- Youtube Data\n  - Video ID\n  - Video Title\n  - Video URL\n  - Thumbnail URL\n  - Description\n  - Views count\n  - Likes count\n\n## Usage\n\nRssParser uses [Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) for all the asynchronous work.\n\n### Creating an RssParser instance\n\nAn `RssParser` instance is the entry point of the library. \n\nIt's possible to create an instance of `RssParser` directly in the common code, without having to pass any platform-specific dependencies. \n\n```kotlin\nval rssParser: RssParser = RssParser()\n```\n\n#### Builder\n\nAn `RssParser` instance can also be built with a platform-specific `RssParserBuilder`. Some custom and optional fields can be provided to the builder.\n\n**On Android and the JVM**, a custom `OkHttpClient` instance and a custom `Charset` can be provided. If an `OkHttpClient` instance is not provided, the library will create one. If no `Charset` is provided, it will automatically be inferred from the feed XML.\n\n```kotlin\nval builder = RssParserBuilder(\n    callFactory = OkHttpClient(),\n    charset = Charsets.UTF_8,\n)\nval rssParser = builder.build() \n```\n\n**On iOS**, a custom `NSURLSession` instance can be provided. If an `NSURLSession` instance is not provided, the library will use the shared `NSURLSession`. \n\n```kotlin\nval builder = RssParserBuilder(\n    nsUrlSession = NSURLSession(),\n)\nval rssParser = builder.build() \n```\n\n### RSS Parsing from URL\nTo parse an RSS feed from a URL, the suspending `getRssChannel` function can be used.\n\n```kotlin\nval rssChannel: RssChannel = rssParser.getRssChannel(\"https://www.rssfeed.com\")\n```\n\n### RSS Parsing from string\n\nTo parse an RSS feed from an XML string, the suspending `parse` function can be used\n\n```kotlin\nval xmlString: String = \"xml-string\"\nval rssChannel: RssChannel = rssParser.parse(xmlString)\n```\n\n### Using the library in a Java project\n\nThe support for Java with the `OnTaskCompleted` and `onError` callbacks has been dropped.\nHowever, you can still use the library in a Java project, but you will need to write some Kotlin code to handle Coroutines. \n\nYou can transform a Coroutine into a `CompletableFuture` using the `future` extension function from\nthe `kotlinx-coroutines-core` library. \n\n```kotlin\nfun parseFeed(parser: RssParser, url: String): CompletableFuture\u003cRssChannel\u003e = GlobalScope.future {\n    parser.getRssChannel(url)\n}\n```\n\nthen, in your Java code, you can use the `CompletableFuture` API to handle the result.\n\n```java\nRssParser parser = new RssParserBuilder().build();\ntry {\n    RssChannel channel = parseFeed(parser, urlString).get();\n    setChannel(channel);\n} catch (Exception e) {\n    e.printStackTrace();\n    snackbar.postValue(\"An error has occurred. Please try again\");\n}\n```\nAn implementation of these code snippets is available in the [Java sample](samples/java/src/main/java/com/prof/rssparser/sample/java/), in `CoroutineBridge.kt` and `MainViewModel.java`.\n\nN.B. To use CompletableFuture, you need to have a minimum API level of 24.\n\nIf you prefer Guava's `ListenableFuture`, you can use the `listenableFuture` extension function \nfrom the `kotlinx-coroutines-guava` library. \nMore info in the official documentation [here](https://github.com/Kotlin/kotlinx.coroutines/blob/master/integration/kotlinx-coroutines-guava/README.md).\n\n## Sample projects\n\nThe repository contains three samples projects: a [multiplatform](/samples/multiplatform), \nan [Android](/samples/android) and an [Android with Java](samples/java) project to showcase the\nusage in a multiplatform app and an Android one.\n\n## Migration from version 5\n\nVersion 6 of the library introduced the following breaking changes:\n\n- The main package name has been changed from `com.prof.rssparser` to `com.prof18.rssparser`;\n- `com.prof.rssparser.Parser` has been moved and renamed to `com.prof18.rssparser.RssParser`;\n- `com.prof.rssparser.Parser.Builder` has been moved and renamed to `com.prof18.rssparser.RssParserBuilder`;\n- `com.prof.rssparser.Channel` has been moved and renamed to `com.prof18.rssparser.model.RssChannel`;\n- `com.prof.rssparser.Article` has been moved and renamed to `com.prof18.rssparser.model.RssItem`;\n- `com.prof.rssparser.HTTPException` has been moved and renamed to `com.prof18.rssparser.exception.HttpException`;\n- `com.prof.rssparser.Image` has been moved and renamed to `com.prof18.rssparser.RssImage`;\n- `com.prof.rssparser.ItunesOwner` has been moved to `com.prof18.rssparser.model.ItunesOwner`;\n- `com.prof.rssparser.ItunesArticleData` has been moved and renamed to `com.prof18.rssparser.model.ItunesItemData`;\n- `com.prof.rssparser.ItunesChannelData` has been moved to `com.prof18.rssparser.model.ItunesChannelData`;\n- `getChannel()` has been renamed to `getRssChannel()`;\n- `cancel()` is not available anymore, the cancellation can be handled by the caller.\n\n## Changelog\n\nFrom version 1.4.4 and above, the changelog is available in the [release section.](https://github.com/prof18/RSS-Parser/releases)\n\n- 14 December 2017 - Little fixes on Error Management - Version 1.3.1\n- 13 December 2017 - Improved Error Management - Version 1.3\n- 10 December 2017 - Added support for the categories - Version 1.2\n- 12 August 2017 - Fixed the Library Manifest and updated the dependencies - Version 1.1\n- 18 June 2016 - First release  - Version 1.0\n\n## License\n\n```\nCopyright 2016-2023 Marco Gomiero\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## Apps using RSS Parser\nIf you are using RSS Parser in your app and would like to be listed here, please open a pull request!\n\n\u003cdetails\u003e\n  \u003csummary\u003eList of Apps using RSS Parser\u003c/summary\u003e\n\n* [FeedFlow](https://www.feedflow.dev)\n* [ReLabs](https://github.com/theimpulson/ReLabs)\n* [CapyReader](https://capyreader.com/)\n\n\u003c/details\u003e\n\n","funding_links":["https://www.paypal.me/MarcoGomiero"],"categories":["Libraries","Kotlin"],"sub_categories":["Utility","🔧 Utils"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof18%2FRSS-Parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprof18%2FRSS-Parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof18%2FRSS-Parser/lists"}