Skip to content

dkonst/MWFeedParser

BranchesTags
 
 

Repository files navigation

MWFeedParser — An RSS and Atom web feed parser for iOS

MWFeedParser is an Objective-C framework for downloading and parsing RSS (1.* and 2.*) and Atom web feeds. It is a very simple and clean implementation that reads the following information from a web feed:

Feed Information

  • Title
  • Link
  • Summary

Feed Items

  • Title
  • Link
  • Date (the date the item was published)
  • Updated date (the date the item was updated, if available)
  • Summary (brief description of item)
  • Content (detailed item content, if available)
  • Identifier (an item's guid/id)

Enclosures

  • URL
  • Filetype
  • Size

If you use MWFeedParser on your iPhone/iPad app then please do let me know, I'd love to check it out :)

Important: This free software is provided under the MIT licence (X11 license) with the addition of the following condition:

This Software cannot be used to archive or collect data such as (but not limited to) that of events, news, experiences and activities, for the purpose of any concept relating to diary/journal keeping.

The full licence can be found at the end of this document.

Demo / Example App

There is an example iPhone application within the project which demonstrates how to use the parser to display the title of a feed, list all of the feed items, and display an item in more detail when tapped.

Setting up the parser

Create parser:

// Create feed parser and pass the URL of the feed
NSURL *feedURL = [NSURL URLWithString:@"https://images.apple.com/main/rss/hotnews/hotnews.rss"];
feedParser = [[MWFeedParser alloc] initWithFeedURL:feedURL];

Set delegate:

// Delegate must conform to `MWFeedParserDelegate`
feedParser.delegate = self;

Set the parsing type. Options are ParseTypeFull, ParseTypeInfoOnly, ParseTypeItemsOnly. Info refers to the information about the feed, such as it's title and description. Items are the individual items or stories.

// Parse the feeds info (title, link) and all feed items
feedParser.feedParseType = ParseTypeFull;

Set whether the parser should connect and download the feed data synchronously or asynchronously. Note, this only affects the download of the feed data, not the parsing operation itself.

// Connection type
feedParser.connectionType = ConnectionTypeSynchronously;

Initiate parsing:

// Begin parsing
[feedParser parse];

The parser will then download and parse the feed. If at any time you wish to stop the parsing, you can call:

// Stop feed download / parsing
[feedParser stopParsing];

The stopParsing method will stop the downloading and parsing of the feed immediately.

Reading the feed data

Once parsing has been initiated, the delegate will receive the feed data as it is parsed.

- (void)feedParserDidStart:(MWFeedParser *)parser; // Called when data has downloaded and parsing has begun
- (void)feedParser:(MWFeedParser *)parser didParseFeedInfo:(MWFeedInfo *)info; // Provides info about the feed
- (void)feedParser:(MWFeedParser *)parser didParseFeedItem:(MWFeedItem *)item; // Provides info about a feed item
- (void)feedParserDidFinish:(MWFeedParser *)parser; // Parsing complete or stopped at any time by `stopParsing`
- (void)feedParser:(MWFeedParser *)parser didFailWithError:(NSError *)error; // Parsing failed

MWFeedInfo, MWFeedItem and MWFeedItemEnclosure contains properties (title, link, summary, etc.) that will hold the parsed data. View MWFeedInfo.h, MWFeedItem.h and MWFeedItemEnclosure.h for more information.

Important: There are some occasions where feeds do not contain some information, such as titles, links or summaries. Before using any data, you should check to see if that data exists:

NSString *title = item.title ? item.title : @"[No Title]";
NSString *link = item.link ? item.link : @"[No Link]";
NSString *summary = item.summary ? item.summary : @"[No Summary]";

The method feedParserDidFinish: will only be called when the feed has successfully parsed, or has been stopped by a call to stopParsing. To determine whether the parsing completed successfully, or was stopped, you can call isStopped.

For a usage example, please see RootViewController.m in the demo project.

Alternative block based API

You can also use blocks to define callbacks, on platforms that support them instead of using the traditional delegate based approach.

Create parser:

// Create feed parser and pass the URL of the feed
NSURL *feedURL = [NSURL URLWithString:@"https://images.apple.com/main/rss/hotnews/hotnews.rss"];
__block MWFeedParser *feedParser = [[MWFeedParser alloc] initWithFeedURL:feedURL];
feedParser.connectionType = ConnectionTypeAsynchronously;

Set callback block(s):

// Callback blocks
parser.startedBlock = ^{
	NSLog(@"Started parsing URL: %@", feedURL);
};

feedParser.feedInfoBlock = ^(MWFeedInfo *feedInfo){
  NSLog(@"Feed: %@", feedInfo.title);
};

feedParser.feedItemBlock = ^(MWFeedItem *item){
	NSLog(@"Item: %@", item.title);
};

parser.failureBlock = ^(NSError *error){
	NSLog(@"Failed parsing with error: %@", error);
};

parser.completionBlock = ^{
	NSLog(@"Completed parsing URL: %@", feedURL);
};

Initiate parsing:

// Begin parsing
[feedParser parse];

Note the use of the __block qualifier when declaring the parser. This tells the block not to retain the request, preventing a