Scanner Tutorial for macOS
Use NSScanner to analyze strings from natural form to computer languages. In this NSScanner tutorial, you’ll learn how to extract information from emails.
Version
- Other, Other, Other

Update 9/25/16: This tutorial has been updated for Xcode 8 and Swift 3.
Update note: This tutorial has been updated to Swift by Hai Nguyen. The original tutorial was written by Vincent Ngo.
In these days of big data, data is stored in a multitude of formats, which poses a challenge to anyone trying to consolidate and make sense of it. If you’re lucky, the data will be in an organized, hierarchical format such as JSON, XML, or CSV. Otherwise, you might have to struggle with endless if/else cases. Either way, manually extracting data is no fun.
Thankfully, Apple provides a set of tools that you can use to analyze string data in any form, from natural to computer languages, such as NSRegularExpression
, NSDataDetector
or Scanner
. Each of them has its own advantages, but Scanner
is by far the easiest to use yet powerful and flexible. In this tutorial, you’ll learn how to extract information from email messages with its methods, in order to build a macOS application that works like Apple Mail’s interface as shown.
Although you’ll be building an app for Mac, Scanner
is also available on iOS. By the end of this tutorial, you will be ready to parse text on either platform.
Before getting things started, let’s first see what Scanner
is capable of!
Scanner Overview
Scanner
‘s main functionality is to retrieve and interpret substring and numeric values.
For example, Scanner
can analyze a phone number and break it down into components like this:
// 1.
let hyphen = CharacterSet(charactersIn: "-")
// 2.
let scanner = Scanner(string: "123-456-7890")
scanner.charactersToBeSkipped = hyphen
// 3.
var areaCode, firstThreeDigits, lastFourDigits: NSString?
scanner.scanUpToCharacters(from: hyphen, into: &areaCode) // A
scanner.scanUpToCharacters(from: hyphen, into: &firstThreeDigits) // B
scanner.scanUpToCharacters(from: hyphen, into: &lastFourDigits) // C
print(areaCode!, firstThreeDigits!, lastFourDigits!)// 123 - area code
// 456 - first three digits
// 7890 - last four digits
Here’s what this code does:
- Creates an instance of
CharacterSet
namedhyphen
. This will be used as the separator between string components. - Initializes a
Scanner
object and changes itscharactersToBeSkipped
default value (whitespace and linefeed) tohyphen
, so the returning strings will NOT include any hyphens. -
areaCode
,firstThreeDigits
andlastFourDigits
will store parsed values that you get back from the scanner. Since you cannot port Swift nativeString
directly toAutoreleasingUnsafeMutablePointer
, you have to declare these variables as optionalNSString
objects in order to pass them into the scanner’s method.- Scans up to the first – character and assigns the values in front of the hyphen character into
areaCode
. - Continues scanning to the second – and grabs the next three digits into
firstThreeDigits
. Before you invokescanUpToCharactersFromSet(from:into:)
, the scanner’s reading cursor was at the position of the first found-
. With the hyphen ignored, you get the phone number’s second component. - Finds the next
-
. The scanner finishes the rest of the string and returns a successful status. With no hyphen left, it simply puts the remaining substring intolastFourDigits
.
- Scans up to the first – character and assigns the values in front of the hyphen character into
That’s all Scanner
does. It’s that easy! Now, it’s time to get your application started!
Getting Started
Download the starter project and extract the the contents of the ZIP file. Open EmailParser.xcodeproj in Xcode.
You’ll find the following:
- DataSource.swift contains a pre-made structure that sets up the data source/delegate to populate a table view.
- PostCell.swift contains all the properties that you need to display each individual data item.
- Support/Main.storyboard contains a TableView with a custom cell on the left hand-side and a TextView on the other.
You’ll be parsing the data of 49 sample files in comp.sys.mac.hardware folder. Take a minute to browse though to see how it’s structured. You’ll be collecting items like Name, Email, and so on into a table so that they are easy to see at a glance.
Build and run the project to see it in action.
The table view currently displays placeholder labels with [Field]Value prefix. By the end of the tutorial, those will be replaced with parsed data.
Understanding the Structure of Raw Samples
Before diving straight into parsing, it’s important to understand what you’re trying to achieve. Below is one of the sample files, with the data items you’ll be retrieving highlighted.
In summary, these data items are:
- From field: this consists of the sender’s name and email. Parsing it can be tricky since the name may come before the email or vice versa; it might even contain one piece but not the other.
- Subject, Date, Organization and Lines fields: these have values separated by colons.
- Message segment: this can contain cost information and some of these following keywords: apple, macs, software, keyboard, printer, video, monitor, laser, scanner, disks, cost, price, floppy, card, and phone.
Scanner
is awesome; however, working with it can feel a bit cumbersome and far less “Swifty”, so you’ll convert the built-in methods like the one in the phone number example above to ones that return optionals.
Navigate to File\New\File… (or simply press Command+N). Select macOS > Source > Swift File and click Next. Set the file’s name to Scanner+.swift, then click Create.
Open Scanner+.swift and add the following extension:
extension Scanner {
func scanUpToCharactersFrom(_ set: CharacterSet) -> String? {
var result: NSString? // 1.
return scanUpToCharacters(from: set, into: &result) ? (result as? String) : nil // 2.
}
func scanUpTo(_ string: String) -> String? {
var result: NSString?
return self.scanUpTo(string, into: &result) ? (result as? String) : nil
}
func scanDouble() -> Double? {
var double: Double = 0
return scanDouble(&double) ? double : nil
}
}
These helper methods encapsulate some of the Scanner
methods you’ll use in this tutorial so that they return an optional String
. These three methods share the same structure:
- Defines a
result
variable to hold the value returned by the scanner. - Uses a ternary operator to check whether the scan is successful. If it is, converts
result
toString
and returns it; otherwise simply returnsnil
.
Scanner
methods like you did above and save them to your arsenals:
- scanDecimal(_:)
- scanFloat(_:)
- scanHexDouble(_:)
- scanHexFloat(_:)
- scanHexInt32(_:)
- scanHexInt64(_:)
- scanInt(_:)
- scanInt32(_:)
- scanInt64(_:)
Simple, right? Now go back to the main project and start parsing!
Creating the Data Structure
Navigate to File\New\File… (or simply press Command+N). Select macOS > Source > Swift File and click Next. Set the file’s name to HardwarePost.swift, then click Create.
Open HardwarePost.swift and add the following structure:
struct HardwarePost {
// MARK: Properties
// the fields' values once extracted placed in the properties
let email: String
let sender: String
let subject: String
let date: String
let organization: String
let numberOfLines: Int
let message: String
let costs: [Double] // cost related information
let keywords: Set<String> // set of distinct keywords
}
This code defines HardwarePost
structure that stores the parsed data. By default, Swift provides you a default constructor based on its properties, but you’ll come back to this later to implement your own custom initializer.
Are you ready for parsing in action with Scanner
? Let’s do this.
Creating the Data Parser
Navigate to File\New\File… (or simply press Command+N), select macOS > Source > Swift File and click Next. Set the file’s name to ParserEngine.swift, then click Create.
Open ParserEngine.swift and create ParserEngine
class by adding the following code:
final class ParserEngine {
}
Extracting Metadata Fields
Consider the following sample metadata segment:
Here’s where Scanner
comes in and separates the fields and their values. The image below gives you a general visual representation of this structure.
Open ParserEngine.swift and implement this code inside ParserEngine
class:
// 1.
typealias Fields = (sender: String, email: String, subject: String, date: String, organization: String, lines: Int)
/// Returns a collection of predefined fields' extracted values
func fieldsByExtractingFrom(_ string: String) -> Fields {
// 2.
var (sender, email, subject, date, organization, lines) = ("", "", "", "", "", 0)
// 3.
let scanner = Scanner(string: string)
scanner.charactersToBeSkipped = CharacterSet(charactersIn: " :\n")
// 4.
while !scanner.isAtEnd { // A
let field = scanner.scanUpTo(":") ?? "" // B
let info = scanner.scanUpTo("\n") ?? "" // C
// D
switch field {
case "From": (email, sender) = fromInfoByExtractingFrom(info) // E
case "Subject": subject = info
case "Date": date = info
case "Organization": organization = info
case "Lines": lines = Int(info) ?? 0
default: break
}
}
return (sender, email, subject, date, organization, lines)
}
Don’t panic! The Xcode error of an unresolved identifier will go away right in the next section.
Here’s what the above code does:
- Defines a
Fields
type alias for the tuple of parsed fields. - Creates variables that will hold the returning values.
- Initializes a
Scanner
instance and changes itscharactersToBeSkipped
property to also include a colon beside the default values – whitespace and linefeed. - Obtains values of all the wanted fields by repeating the process below:
- Uses
while
to loop throughstring
‘s content until it reaches the end. - Invokes one of the helper functions you created earlier to get
field
‘s title before:
. - Continues scanning up to the end of the line where the linefeed character
\n
is located and assigns the result toinfo
. - Uses
switch
to find the matching field and stores itsinfo
property value into the proper variable. - Analyzes From field by calling
fromInfoByExtractingFrom(_:)
. You’ll implement the method after this section.
- Uses
Remember the tricky part of From field? Hang tight because you’re going to need help from regular expression to overcome this challenge.
At the end of ParserEngine.swift, add the following String
extension:
private extension String {
func isMatched(_ pattern: String) -> Bool {
return NSPredicate(format: "SELF MATCHES %@", pattern).evaluate(with: self)
}
}
This extension defines a private helper method to find whether the string matches a given pattern using regular expressions.
It creates a NSPredicate
object with a MATCHES
operator using the regular expression pattern. Then it invokes evaluate(with:)
to check if the string matches the conditions of the pattern.
NSPredicate
in the official Apple documentation.Now add the following method inside the ParserEngine
implementation, just after fieldsByExtractingFrom(_:)
method:
fileprivate func fromInfoByExtractingFrom(_ string: String) -> (email: String, sender: String) {
let scanner = Scanner(string: string)
// 1.
/*
* ROGOSCHP@MAX.CC.Uregina.CA (Are we having Fun yet ???)
* oelt0002@student.tc.umn.edu (Bret Oeltjen)
* (iisi owner)
* mbuntan@staff.tc.umn.edu ()
* barry.davis@hal9k.ann-arbor.mi.us (Barry Davis)
*/
if string.isMatched(".*[\\s]*\\({1}(.*)") { // A
scanner.charactersToBeSkipped = CharacterSet(charactersIn: "() ") // B
let email = scanner.scanUpTo("(") // C
let sender = scanner.scanUpTo(")") // D
return (email ?? "", sender ?? "")
}
// 2.
/*
* "Jonathan L. Hutchison" <jh6r+@andrew.cmu.edu>
* <BR4416A@auvm.american.edu>
* Thomas Kephart <kephart@snowhite.eeap.cwru.edu>
* Alexander Samuel McDiarmid <am2o+@andrew.cmu.edu>
*/
if string.isMatched(".*[\\s]*<{1}(.*)") {
scanner.charactersToBeSkipped = CharacterSet(charactersIn: "<> ")
let sender = scanner.scanUpTo("<")
let email = scanner.scanUpTo(">")
return (email ?? "", sender ?? "")
}
// 3.
return ("unknown", string)
}
After examining the 49 data sets, you end up with three cases to consider:
- email (name)
- name <email>
- email with no name
Here’s what the code does:
- Matches
string
with the first pattern – email (name). If not, continues to the next case.- Looks for zero or more occurrences of any character –
.*
, followed by zero or more occurrence of a space –[\\s]*
, followed by one open parenthesis –\\({1}
and finally zero or more occurrences of a string –(.*)
. - Sets the
Scanner
object’scharactersToBeSkipped
to include: “(“, “)” and whitespace. - Scans up to
(
to get theemail
value. - Scans up to
)
, which gives you thesender
name. This extracts everything before(
and after)
.
- Looks for zero or more occurrences of any character –
- Checks whether the given string matches the pattern – name <email>. The if body is practically the same as the first scenario, except that you deal with angle brackets.
- Finally, if neither of the two patterns is matched, this is the case where you only have an email. You’ll simply return the string for the email and “unknown” for sender.
At this point, you can build the project. The previous compile error is gone.
NSDataDetector
would be a better solution for known-data types like phone number, address, and email. You can check out this blog about email validation with NSDataDetector
.You’ve been working with Scanner
to analyze and retrieve information from a patterned string. In the next two sections, you’ll learn how to parse unstructured data.
Extracting Cost-Related Information
A good example of parsing unstructured data is to determine whether the email’s body contains cost-related information. To do this, you’ll use Scanner
to search for an occurrence of a dollar character: $.
Still working on ParserEngine.swift, add the following implementation inside ParserEngine
class:
func costInfoByExtractingFrom(_ string: String) -> [Double] {
// 1.
var results = [Double]()
// 2.
let dollar = CharacterSet(charactersIn: "$")
// 3.
let scanner = Scanner(string: string)
scanner.charactersToBeSkipped = dollar
// 4.
while !scanner.isAtEnd && scanner.scanUpToCharacters(from: dollar, into: nil) {
results += [scanner.scanDouble()].flatMap { $0 }
}
return results
}
The code is fairly straightforward:
- Defines an empty array to store the cost values.
- Creates a
CharacterSet
object with a$
character. - Initializes a
Scanner
instance and configures it to ignore the $ character. - Loops through
string
‘s content and when a$
is found, grabs the number after$
with your helper method and appends it toresults
array.
Parsing the Message
Another example of parsing unstructured data is finding keywords in a given body of text. Your search strategy is to look at every word and check it against a set of keywords to see if it matches. You’ll use the whitespace and newline characters to take the words in the message as scanning.
Add the following code at the end of ParserEngine
class:
// 1.
let keywords: Set<String> = ["apple", "macs", "software", "keyboard",
"printers", "printer", "video", "monitor",
"laser", "scanner", "disks", "cost", "price",
"floppy", "card", "phone"]
/// Return a set of keywords extracted from
func keywordsByExtractingFrom(_ string: String) -> Set<String> {
// 2.
var results: Set<String> = []
// 3.
let scanner = Scanner(string: string)
// 4.
while !scanner.isAtEnd, let word = scanner.scanUpTo(" ")?.lowercased() {
if keywords.contains(word) {
results.insert(word)
}
}
return results
}
Here’s what this code does:
- Defines the keywords set that you’ll match against.
- Creates a
Set
ofString
to store the found keywords. - Initializes a
Scanner
instance. You’ll use the defaultcharactersToBeSkipped
, which are the whitespace and newline characters. - For every word found, checks whether it’s one of the predefined
keywords
. If it is, appends it intoresults
.
There — you have all of the necessary methods to acquire the desired information. Time to put them to good use and create HardwarePost
instances for the 49 data files.
Connecting the Parser With Data Samples
Open HardwarePost.swift and add this initializer into HardWarePost
structure:
init(fromData data: Data) {
// 1.
let parser = ParserEngine()
// 2.
let string = String(data: data, encoding: String.Encoding.utf8) ?? ""
// 3.
let scanner = Scanner(string: string)
// 4.
let metadata = scanner.scanUpTo("\n\n") ?? ""
let (sender, email, subject, date, organization, lines) = parser.fieldsByExtractingFrom(metadata)
// 5.
self.sender = sender
self.email = email
self.subject = subject
self.date = date
self.organization = organization
self.numberOfLines = lines
// 6.
let startIndex = string.characters.index(string.startIndex, offsetBy: scanner.scanLocation) // A
let message = string[startIndex..<string.endIndex] // B
self.message = message.trimmingCharacters(in: .whitespacesAndNewlines ) // C
// 7.
costs = parser.costInfoByExtractingFrom(message)
keywords = parser.keywordsByExtractingFrom(message)
}
Here's how HardwarePost
initializes its properties:
- Simply creates a
ParserEngine
object namedparser
. - Converts
data
into aString
. - Initializes an instance of
Scanner
to parse the Metadata and Message segments, which are separated by "\n\n". - Scans up to the first
\n\n
to grab the metadata string, then invokes theparser
'sfieldsByExtractingFrom(_:)
method to obtain all of the metadata fields. - Assigns the parsing results to the
HardwarePost
properties. - Prepares the message content:
- Gets the current reading cursor from
scanner
withscanLocation
and converts it toString.CharacterView.Index
, so you can substitutestring
by range. - Assigns the remaining string that
scanner
has yet to read into the newmessage
variable. - Since
message
value still contains\n\n
where thescanner
left off from the previous reading, you need to trim it and give the new value back to theHardwarePost
instance'smessage
property.
- Gets the current reading cursor from
- Invokes the
parser
's methods withmessage
to retrieve values forcost
andkeywords
properties.
At this point, you can create HardwarePost
instances directly from the files' data. You are only few more steps from displaying the final product!
Displaying Parsed Data
Open PostCell.swift and add the following method inside the PostCell
class implementation:
func configure(_ post: HardwarePost) {
senderLabel.stringValue = post.sender
emailLabel.stringValue = post.email
dateLabel.stringValue = post.date
subjectLabel.stringValue = post.subject
organizationLabel.stringValue = post.organization
numberOfLinesLabel.stringValue = "\(post.numberOfLines)"
// 1.
costLabel.stringValue = post.costs.isEmpty ? "NO" :
post.costs.map { "\($0)" }.lazy.joined(separator: "; ")
// 2.
keywordsLabel.stringValue = post.keywords.isEmpty ? "No keywords found" :
post.keywords.joined(separator: "; ")
}
This code assigns the post values to the cell labels. costLabel
and keywordsLabel
require special treatment because they can be empty. Here's what happens:
- If the
costs
array is empty, it sets thecostLabel
string value to NO; otherwise, it concatenates the cost values with "; " as a separator. - Similarly, sets
keywordsLabel
string value toNo words found
for an empty set ofpost.keywords
.
You're almost there! Open DataSource.swift. Delete the DataSource
initializer init()
and add the following code into the class:
let hardwarePosts: [HardwarePost] // 1.
override init() {
self.hardwarePosts = Bundle.main // 2.
.urls(forResourcesWithExtension: nil, subdirectory: "comp.sys.mac.hardware")? // 3.
.flatMap( { try? Data(contentsOf: $0) }).lazy // 4.
.map(HardwarePost.init) ?? [] // 5.
super.init()
}
This is what the code does:
- Stores the
HardwarePost
instances. - Obtains a reference to the application's main Bundle.
- Retrieves urls of the sample files inside the comp.sys.mac.hardware directory.
- Lazily acquires an array of
Data
instances by reading file contents withData
failable initializer andflatMap(_:)
. The idea of usingflatMap(_:)
is to get back a subarray containing only elements that are notnil
. - Finally, transforms the
Data
results to aHardwarePost
object and assigns them to theDataSource
hardwarePosts
property.
Now you need to set up the table view's data source and delegate so that your app can show your hard work.
Open DataSource.swift. Find numberOfRows(in:)
and replace it with the following:
func numberOfRows(in tableView: NSTableView) -> Int {
return hardwarePosts.count
}
numberOfRows(in:)
is part of the table view’s data source protocol; it sets the number of rows of the table view.
Next, find tableView(_:viewForTableColumn:row:)
and replace the comment that says: //TODO: Set up cell view
with the code below:
cell.configure(hardwarePosts[row])
The table view invokes its delegate tableView(_:viewForTableColumn:row:)
method to set up every individual cell. It gets a reference to the post for that row and invokes PostCell
's configure(_:)
method to display the data.
Now you need to show the post in the text view when you select a post on the table view. Replace the initial implementation of tableViewSelectionDidChange(_:)
with the following:
func tableViewSelectionDidChange(_ notification: Notification) {
guard let tableView = notification.object as? NSTableView else {
return
}
textView.string = hardwarePosts[tableView.selectedRow].message
}
tableViewSelectionDidChange(_:)
is called when the table view’s selection has changed. When that happens, this code gets the hardware post for the selected row and displays the message
in the text view.
Build and run your project.
All of the parsed fields are now neatly displayed on the table. Select a cell on the left, and you'll see the corresponding message on the right. Good Job!
Where to Go From Here?
Here’s the source code for the completed project
There is so much more you can do with the data you have parsed. You could write a formatter that converts a HardwarePost
object into JSON, XML, CSV or any other formats. With your new-found flexibility to represent data in different forms, you can share your data across different platforms.
If you're interested in the study of computer languages and how they are implemented, take a class in comparative languages. Your course will likely cover formal languages and BNF grammars—all important concepts in the design and implementation of parsers.
For more information on Scanner
and other parsing theory, check out the following resources:
- Swift Tutorial: Working with JSON
- Apple: Scanner Reference Guide
- XML Tutorial for iOS - How to choose the best XML parser for your iPhone-Project (in Objective-C)
- Writing a parser using NSScanner (a CSV parsing example) by Matt Gallagher (in Objective-C)
- Short Presentation on NSScanner by Lorex Antiono (in Objective-C)
If you have any questions or comments, please join the discussion below!
Comments