Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mwaterfall/MWFeedParser

An Objective-C RSS / Atom Feed Parser for iOS
https://github.com/mwaterfall/MWFeedParser

Last synced: 3 months ago
JSON representation

An Objective-C RSS / Atom Feed Parser for iOS

Awesome Lists containing this project

README 

        
# 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

- Author name

- 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)

- Enclosures (i.e. podcasts, mp3, pdf, etc)

- Identifier (an item's guid/id)



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:@"http://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` and `MWFeedItem` contains properties (title, link, summary, etc.) that will hold the parsed data. View `MWFeedInfo.h` and `MWFeedItem.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.



## Available data



Here is a list of the available properties for feed info and item objects:



#### MWFeedInfo

- `info.title` (`NSString`)

- `info.link` (`NSString`)

- `info.summary` (`NSString`)



#### MWFeedItem



- `item.title` (`NSString`)

- `item.link` (`NSString`)

- `item.author` (`NSString`)

- `item.date` (`NSDate`)

- `item.updated` (`NSDate`)

- `item.summary` (`NSString`)

- `item.content` (`NSString`)

- `item.enclosures` (`NSArray` of `NSDictionary` with keys `url`, `type` and `length`)

- `item.identifier` (`NSString`)



## Using the data



All properties of `MWFeedInfo` and `MWFeedItem` return the raw data as provided by the feed. This content may or may not include HTML and encoded entities. If the content does include HTML, you could display the data within a UIWebView, or you could use the provided `NSString` category (`NSString+HTML`) which will allow you to manipulate this HTML content. The methods available for your convenience are:



    // Convert HTML to Plain Text

    //  - Strips HTML tags & comments, removes extra whitespace and decodes HTML character entities.

    - (NSString *)stringByConvertingHTMLToPlainText;



    // Decode all HTML entities using GTM.

    - (NSString *)stringByDecodingHTMLEntities;



    // Encode all HTML entities using GTM.

    - (NSString *)stringByEncodingHTMLEntities;



    // Minimal unicode encoding will only cover characters from table

    // A.2.2 of http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_Special_characters

    // which is what you want for a unicode encoded webpage.

    - (NSString *)stringByEncodingHTMLEntities:(BOOL)isUnicode;



    // Replace newlines with 
 tags.

    - (NSString *)stringWithNewLinesAsBRs;



    // Remove newlines and white space from string.

    - (NSString *)stringByRemovingNewLinesAndWhitespace;



    // Wrap plain URLs in ...

    //  - Ignores URLs inside tags (any URL beginning with =")

    //  - HTTP & HTTPS schemes only

    //  - Only works in iOS 4+ as we use NSRegularExpression (returns self if not supported so be careful with NSMutableStrings)

    //  - Expression: (?