Merge pull request #22 from vincentneo/initOptions

Init replacements & additions

Author: vincentneo

Classes/GPXParser.swift

@@ -9,44 +9,70 @@ import Foundation
 
 open class GPXParser: NSObject, XMLParserDelegate {
 
-    private var parser: XMLParser
+    private let parser: XMLParser
 
     // MARK:- Initializers
 
+    /// for parsing with `Data` type
+    ///
+    /// - Parameters:
+    ///     - data: The input must be `Data` object containing GPX markup data, and should not be `nil`
+    ///
     public init(withData data: Data) {
         self.parser = XMLParser(data: data)
         super.init()
         self.parser.delegate = self
         self.parser.parse()
     }
 
-    public init(withPath path: String) {
-        self.parser = XMLParser()
+    /// for parsing with `InputStream` type
+    ///
+    /// - Parameters:
+    ///     - stream: The input must be a input stream allowing GPX markup data to be parsed synchronously
+    ///
+    public init(withStream stream: InputStream) {
+        self.parser = XMLParser(stream: stream)
         super.init()
-        let url = URL(fileURLWithPath: path)
-        do {
-            let data = try Data(contentsOf: url)
-            self.parser = XMLParser(data: data)
-            self.parser.delegate = self
-            self.parser.parse()
-        }
-        catch {
-            print(error)
-        }
+        self.parser.delegate = self
+        self.parser.parse()
     }
 
-    public init(withURL url: URL) {
-        self.parser = XMLParser()
+    /// for parsing with `URL` type
+    ///
+    /// - Parameters:
+    ///     - url: The input must be a `URL`, which should point to a GPX file located at the URL given
+    ///
+    public init?(withURL url: URL) {
+        guard let urlParser = XMLParser(contentsOf: url) else { return nil }
+        self.parser = urlParser
         super.init()
-        do {
-            let data = try Data(contentsOf: url)
-            self.parser = XMLParser(data: data)
-            self.parser.delegate = self
-            self.parser.parse()
-        }
-        catch {
-            print(error)
+        self.parser.delegate = self
+        self.parser.parse()
+    }
+    
+    /// for parsing with a string that contains full GPX markup
+    ///
+    /// - Parameters:
+    ///     - string: The input `String` must contain full GPX markup, which is typically contained in a `.GPX` file
+    ///
+    public convenience init?(withRawString string: String?) {
+        if let string = string {
+            if let data = string.data(using: .utf8) {
+                self.init(withData: data)
+            }
+            else { return nil }
         }
+        else { return nil }
+    }
+    
+    /// for parsing with a path to a GPX file
+    ///
+    /// - Parameters:
+    ///     - path: The input path, with type `String`, must contain a path that points to a GPX file used to facilitate parsing.
+    ///
+    public convenience init?(withPath path: String) {
+        guard let url = URL(string: path) else { return nil }
+        self.init(withURL: url)
     }
 
     // MARK:- GPX Parsing

Example/GPXKit/ParseViewController.swift

@@ -32,7 +32,7 @@ class ParseViewController: UIViewController, UITableViewDelegate, UITableViewDat
 
         if input != nil {
             if let inputURL = URL(string: input!) {
-                let gpx = GPXParser(withURL: inputURL).parsedData()
+                guard let gpx = GPXParser(withURL: inputURL)?.parsedData() else { return }
                 self.tracks = gpx.tracks
                 self.waypoints = gpx.waypoints
                 self.tableView.reloadData()

Example/GPXKit/ViewController.swift

@@ -23,7 +23,7 @@ class ViewController: UIViewController {
         let url: URL = URL(string: urlString)!
 
         // GPXRoot object that contains all the data parsed from GPXParser.
-        let gpx = GPXParser(withURL: url).parsedData()
+        guard let gpx = GPXParser(withURL: url)?.parsedData() else { return }
 
         self.tracks = gpx.tracks
         self.waypoints = gpx.waypoints

README.md

@@ -20,16 +20,16 @@ It makes use of `XMLParser` for parsing GPX files, thus making it fully dependen
 ## How to parse?
 Parsing of GPX files is done by initializing `GPXParser`.
 
-There are three ways of initializing `GPXParser`:
+There are five ways of initializing `GPXParser`,  and these are three main ways of initializing:
 ### You can initialize with a `URL`:
 ```Swift
-let gpx = GPXParser(withURL: inputURL).parsedData()
+guard let gpx = GPXParser(withURL: inputURL)?.parsedData() else { return }
 ```
 ### With path:
 ```Swift
-let gpx = GPXParser(withPath: inputPath).parsedData() // String type
+guard let gpx = GPXParser(withPath: inputPath)?.parsedData() else { return } // String type
 ```
-### Or with `Data`:
+### With `Data`:
 ```Swift
 let gpx = GPXParser(withData: inputData).parsedData()
 ```
@@ -38,7 +38,7 @@ let gpx = GPXParser(withData: inputData).parsedData()
 
 ### Making use of parsed GPX data
 ```Swift
-let gpx = GPXParser(withURL: inputURL).parsedData()
+guard let gpx = GPXParser(withURL: inputURL)?.parsedData() else { return // do things here when failed }
 
 // waypoints, tracks, tracksegements, trackpoints are all stored as Array depends on the amount stored in the GPX file.
 for waypoint in gpx.waypoints {  // for loop example, every waypoint is written
@@ -54,7 +54,7 @@ for waypoint in gpx.waypoints {  // for loop example, every waypoint is written
 
 ## How to create?
 
-You will first start of with `GPXRoot`.
+You will first start off with a `GPXRoot`.
 
 ### Initializing `GPXRoot`
 ```Swift