AutoHyperlinks is the framework used by Adium to scan for URLs in strings and other text containers. Unlike the rest of the Adium project, as of r23419, this framework is released under the modified BSD license, and is free to be used in most any software project.
What, exactly, does AutoHyperlinks do?
The AutoHyperlinks framework handles the detection of hyperlinks in normal language, leaving you, the developer, free to concentrate on the core functionality of your application.
It's the same code we use in Adium to match all our hyperlinks, and we think it's pretty great.
AutoHyperlinks gives you a framework with a flex based lexer and two Objective-C classes in it: AHMarkedHyperlink and AHHyperlinkScanner. Together, these two classes can work together to identify and add the NSLinkAttributeNames like Adium does, or you can simply gather all the links strings and do whatever you want with them.
How do I get it?
A binary will be available as soon as Adium 1.3 goes final. Until then. the easiest way is to either check it out from Adium's Mercurial directory by following the directions on GettingAdiumSource.
How do I use it in my project?
AutoHyperlinks comes with it's own Xcode 2.4 compatible project. To use it in your existing project, take the following steps:
- Place the AutoHyperlinks Framework directory in a subdirectory of your main project
- Drag the AutoHyperlinks.xcodeproj file into your project.
- Xcode will ask you to what targets you'd like the project to reference
- Select the build target(s) you want to include AutoHyperlinks, and hit ok.
- Xcode will automatically build and install the AutoHyperlinks framework when you build your project.
What does it Include?
You're given two classes to work with: AHMarkedHyperlink and AHHyperlinkScanner. It's sole dependency is the system Cocoa.framework, and is technically compatible down to OS X 10.3 (though we recommend 10.4 or later).
AHMarkedHyperlink is a data type that holds onto information about each link; such as a NSURL object, a reference to it's parent string, and the link's range within that string. It also holds the links verification status as defined in AHLinkLexer.h so you know what type of link it is.
AHHyperlinkScanner is the main interface to all of the framework's link detection abilities.
It has two parsing modes: strict and non-strict.
- Strict Mode
- This is the default mode. Only proper URIs with specified schemes (http://example.com/ but not example.com) will get identified as links.
- Non-Strict Mode
- Setting strict checking to NO removes this restriction, so example.com is included as a link, as well as http://example.com/.
Creates a non-strict instance of AHHyperlinkScanner with a given NSString.
Creates a strict instance of AHHyperlinkScanner with a given NSString.
Creates a non-strict instance of AHHyperlinkScanner with a given NSAttributedString.
Creates a strict instance of AHHyperlinkScanner with a given NSAttributedString.
Returns a BOOL of the given string's validity.
Returns the next valid URI in the string as an AHMarkedHyperlink.
Returns an NSArray of all valid URIs in the scanner's string as AHMarkedHyperlinks.
Returns an attributed string of the original string with NSURLs attached to all URI substrings. If the class was instantiated with an attributed string, all original attributes are preserved.
What kinds of URLs will it match?
- Most anything that should be a link, and we respect enclosed links and punctuation, so <http://example.com/> and example.com, and "example.com" all get linked properly.
- Ugly URLs that include multiple and complex parameter strings.
- All sponsored and unsponsored TLDs, along with ccTLDs are valid matches.
- Unicode characters.
- IPv4 and IPv6 addresses with scheme specifiers are valid matches.
- Local/internal domains with scheme specifiers are valid matches. (ex: "http://example.megaCorp" or "http://localhost")
- Recognized schemes include:
- http and https
- ftp, sftp, ssh and svn
- radar links
- itms links
- several Chat/IM service links, including IRC, AIM, Jabber, and Yahoo!
What kinds of URLs will it not match
We allow simple domain names to be linked in non-strict mode, however we never match the following:
- IPv4 or IPv6 addresses without schemes.
- Common and simple abbreviations without schemes (they will, however, link with a scheme). (ex: B.Sc, m.in)
- Local/internal domains without schemes. (ex: "example.megaCorp" or "localhost" by themselves)
- links that already contain a NSLinkAttributeName within an attributed string.