search

prof18 / RSS-Parser

A Kotlin Multiplatform library to parse a RSS Feed
Apache License 2.0
516 stars 128 forks source link
android android-library rss-feed rss-parser

readme

RSS Parser

Maven Central License API

RSS Parser is a Kotlin Multiplatform library for parsing RSS and Atom feeds. It supports Android, iOS, and the JVM.

With RSS Parser, you can fetch plenty of useful information from any RSS channel, be it a blog, magazine, or even a podcast feed.

Table of Contents

Installation

RSS Parser is currently published to Maven Central, so add it to your project's repositories.

repositories {
    mavenCentral()
    // ...
}

Then, add the dependency to your common source set's dependencies.

commonMain {
    dependencies {
        // ...
        implementation("com.prof18.rssparser:rssparser:<latest-version>")
    }
}

If you are in an Android-only project, simply add the dependency:

dependencies {
    // ...
    implementation("com.prof18.rssparser:rssparser:<latest-version>")
}

Important Notices

Artifact change

Since February 2022, the library artifacts have been moved to MavenCentral. The group ID changed from com.prof.rssparser to com.prof18.rssparser. Be sure to add the gradle dependency to your root build.gradle file.

allprojects {
    repositories {
        mavenCentral()
    }
}

Breaking changes

From version 6.0, RSSParser has become Multiplatform. This update brought some breaking changes:

Here you can find the README for version 5 of RSSParser.

Available data

The RssChannel result object provides the following data:

Items support the following attributes:

Usage

RssParser uses Coroutines for all the asynchronous work.

Creating an RssParser instance

An RssParser instance is the entry point of the library.

It's possible to create an instance of RssParser directly in the common code, without having to pass any platform-specific dependencies. 

val rssParser: RssParser = RssParser()

Builder

An RssParser instance can also be built with a platform-specific RssParserBuilder. Some custom and optional fields can be provided to the builder.

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.

val builder = RssParserBuilder(
    callFactory = OkHttpClient(),
    charset = Charsets.UTF_8,
)
val rssParser = builder.build()

On iOS, a custom NSURLSession instance can be provided. If an NSURLSession instance is not provided, the library will use the shared NSURLSession. 

val builder = RssParserBuilder(
    nsUrlSession = NSURLSession(),
)
val rssParser = builder.build()

RSS Parsing from URL

To parse an RSS feed from a URL, the suspending getRssChannel function can be used.

val rssChannel: RssChannel = rssParser.getRssChannel("https://www.rssfeed.com")

RSS Parsing from string

To parse an RSS feed from an XML string, the suspending parse function can be used

val xmlString: String = "xml-string"
val rssChannel: RssChannel = rssParser.parse(xmlString)

Using the library in a Java project

The support for Java with the OnTaskCompleted and onError callbacks has been dropped. However, you can still use the library in a Java project, but you will need to write some Kotlin code to handle Coroutines.

You can transform a Coroutine into a CompletableFuture using the future extension function from the kotlinx-coroutines-core library. 

fun parseFeed(parser: RssParser, url: String): CompletableFuture<RssChannel> = GlobalScope.future {
    parser.getRssChannel(url)
}

then, in your Java code, you can use the CompletableFuture API to handle the result.

RssParser parser = new RssParserBuilder().build();
try {
    RssChannel channel = parseFeed(parser, urlString).get();
    setChannel(channel);
} catch (Exception e) {
    e.printStackTrace();
    snackbar.postValue("An error has occurred. Please try again");
}

An implementation of these code snippets is available in the Java sample, in CoroutineBridge.kt and MainViewModel.java.

N.B. To use CompletableFuture, you need to have a minimum API level of 24.

If you prefer Guava's ListenableFuture, you can use the listenableFuture extension function from the kotlinx-coroutines-guava library. More info in the official documentation here.

Sample projects

The repository contains three samples projects: a multiplatform, an Android and an Android with Java project to showcase the usage in a multiplatform app and an Android one.

Migration from version 5

Version 6 of the library introduced the following breaking changes:

Changelog

From version 1.4.4 and above, the changelog is available in the release section.

License

Copyright 2016-2023 Marco Gomiero

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Apps using RSS Parser

If you are using RSS Parser in your app and would like to be listed here, please open a pull request!

List of Apps using RSS Parser * [FeedFlow](https://www.feedflow.dev) * [ReLabs](https://github.com/theimpulson/ReLabs) * [CapyReader](https://capyreader.com/)