SwiftRichString

SwiftRichString is a lightweight library wich allows you to simplify your work with attributed strings in UIKit. It provides convenient way to create and manage string with complex attributes, render tag-based string and manipulate styles at specified indexes.

Supported platforms:

• iOS 8.0+
• tvOS 9.0+
• macOS 10.10+
• watchOS 2.0+

And, best of all, it's fully compatible with unicode (who don't love emoji?).

★★ Star our github repository to help us! ★★

You also may like

Do you like SwiftRichString? I'm also working on several other opensource libraries.

Take a look here:

OTHER LIBRARIES YOU MAY LIKE

I'm also working on several other projects you may like. Take a look below:

On Medium

I've just wrote an article which cover the basic concepts of SwiftRichString. You can found it on Medium at Attributed String in Swift: the right way.

Documentation

• Introduction
• Playground
• Define your own Style
• Apply style to a String
• Apply style on substring with Range
• Apply style/s on substring with NSRegularExpression
• Apply Multiple Styles with a set of Regular Expressions
• Combine Strings and Attributed Strings
• Create tagged strings
• Parse and render tag-based content
• Available text attributes in Style
• API Documentation

Other Infos

• Installation (via CocoaPods, Carthage or Swift PM)
• Credits & License

Documentation

Introduction

SwiftRichString integrate seamlessy into UIKit/AppKit by allowing you to manage, combine and apply styles directly on NSMutableAttributedString instances. This library define only two main entities:

• Style is the central point of SwiftRichString: this class allows you to create easily and safety a collection of styles (align, text color, ligature, font etc.). In fact the ideal use-case is to create your own set of styles for your app, then apply to your strings.

• MarkupString allows you to load a string which is pretty like a web page where your content can contain styles enclosed between classic html-style tags (ie. "<bold>Hello</bold> <nameStyle>\(username)</nameStyle>). MarkupString will parse data for your by generating a valid NSMutableAttributedString along your choosed Styles.

• Also there are several NSMutableAttributedString and String extensions allows you to play and combine strings and styles easily without introducing extra structures to your code and by mantaing readability.

Latest Version

Latest version of SwiftRichString is:

• Swift 4.x: 1.1.0
• Swift 3.x: Up to 0.9.10 release

A complete list of changes for each release is available in the CHANGELOG file.

Playground

If you want to play with SwiftRichString we have also made a small Playground. Take a look at Playground.playground file inside the SwiftRichString.xcworkspace.

Define your own Style

Style is a class which define attributes you can apply to strings in a type-safe swifty way. Each style has a name and a set of attributes you can set.

Creating Style is pretty easy. In this example we create a style which set a particular font with given size and color.

let big = Style("italic", {
  $0.font = FontAttribute(.CourierNewPS_ItalicMT, size: 25)
  $0.color = UIColor.red
})

Default Style

This is also a special style called .default. Default - if present - is applied automatically before any other style to the entire sender string. Other styles are applied in order just after it.

let def = Style.default {
  $0.font = FontAttribute(.GillSans_Italic, size: 20)
}

Apply Style to String

Styles can be applied directly to String instances (by generating NSMutableAttributedString automatically) or on existing NSMutableAttributedString.

In this example we can combine simple String instances and apply your own set of styles:

// Define your own used styles
let bold = Style("bold", {
  $0.font = FontAttribute(.CourierNewPS_BoldItalicMT, size: 30) // font + size
  $0.color = UIColor.red // text color 
  $0.align = .center // align on center
})

let italic = Style("italic", {
  $0.font = FontAttribute(.CourierNewPS_ItalicMT, size: 25)
  $0.color = UIColor.green
})

let attributedString = ("Hello " + userName).set(style: bold) + "\nwelcome here".set(style: italic)

Will produce:

Apply style on substring with Range

You can also apply one or more styles to a substring by passing a valid range. In this example we want to apply bold style to the "Man!" substring.

let style_bold = Style("bold", {
  $0.font = FontAttribute(.Futura_CondensedExtraBold, size: 20)
})
let renderText = "Hello Man! Welcome".set(style: style_bold, range: 6..<10)

Will produce:

Apply style/s on substring with NSRegularExpression

Regular expressions are also supported; you can add your own style/s to matched strings. SwiftRichString has fully unicode support.

let sourceText = "👿🏅the winner"
let attributedString = sourceText.set(styles: myStyle, pattern: "the winner", options: .caseInsensitive)

// another example
let sourceText = "prefix12 aaa3 prefix45"
let attributedText = sourceText.set(styles: myStyle, pattern: "fix([0-9])([0-9])", options: .caseInsensitive)

Since 0.9.9 you can also use renderTags function of String:

let taggedString = "<center>The quick brown fox</center>\njumps over the lazy dog is an <italic>English-language</italic> pangram—a phrase that contains <italic>all</italic> of the letters of the alphabet. It is <extreme><underline>commonly</underline></extreme> used for touch-typing practice."
let attributed = taggedString.renderTags(withStyles: [tag_center,tag_italic,tag_extreme,tag_underline])

Will produce:

Apply Multiple Styles with a set of Regular Expressions

Sometimes you may need to apply different Style by matching some regular expression rules. In this case you can use .set(regExpStyles:default:) function and define your own matcher; each matcher is a RegExpPatternStyles struct which matches a particular regexp and apply a set of [Style].

In the following example we have applied two regexp to colorize email (in red) and url (in blue). The entire string is set to a base style (baseStyle) before all regexp are evaluated.

let regexp_url = "http?://([-\\w\\.]+)+(:\\d+)?(/([\\w/_\\.]*(\\?\\S+)?)?)?"
let regexp_email = "([A-Za-z0-9_\\-\\.\\+])+\\@([A-Za-z0-9_\\-\\.])+\\.([A-Za-z]+)"

let text_example = "My email is hello@danielemargutti.com and my website is http://www.danielemargutti.com"

let rule_email = RegExpPatternStyles(pattern: regexp_email) {
	$0.color = .red
}!

let rule_url = RegExpPatternStyles(pattern: regexp_url) {
	$0.color = .blue
}!

let baseStyle = Style("base", {
	$0.font = FontAttribute(.Georgia_Bold, size: 12)
})

var attributedString = text_example.set(regExpStyles: [rule_email, rule_url], default: baseStyle)

Combine Strings and Attributed Strings

You can combine String and NSMutableAttributedString easily with + operator.

For example:

let part1 = "Hello"
let part2 = "Mario"
let part3 = "Welcome here!"

// You can combine simple String and `NSMutableAttributedString`
// Resulting is an `NSMutableAttributedString` instance.
let result = part1 + " " + part2.set(style: bold) + " " + part3

You can avoid creating new instances of NSMutableAttributedString and change directly your instance:

let attributedText = "Welcome".set(style: bold)
// Render a simple string with given style and happend it to the previous instance
attributedText.append(string: " mario! ", style: bold)

Is possible to append a MarkupString to an NSMutableAttributedString instance:

let sourceURL = URL(fileURLWithPath: "...")
let markUpObj = MarkupString(sourceURL, [bold,italic])!

let finalAttributed = "Welcome!".set(style: bold)
// Create an `NSMutableAttributedString` render from markUpObj and append it to the instance
finalAttributed.append(markup: markUpObj)

Create tagged strings

Sometimes you may have a text you want to render with your own favorite application's styles, like HTML/CSS does with web page. With SwiftRichString it's really easy; add your favourite tags to your source string, create associated Style and apply them. Let me show an example:

// First of all we want to define all `Style` you want to use in your
// source string.
// Each style has its own name (any letter-based identifier) you should use in your source string
let tStyle1 = Style("style1", {
  $0.font = FontAttribute(.AvenirNextCondensed_Medium, size: 50)
  $0.color = UIColor.red
})

let tStyle2 = Style("style2", {
  $0.font = FontAttribute(.HelveticaNeue_LightItalic, size: 20)
  $0.color = UIColor.green
  $0.backColor = UIColor.yellow
})
		
// Create and render text
let text = "Hello <style1>\(userName)!</style1>, <style2>welcome here!</style2>"
let renderedText = text.parse(tStyle1,tStyle2).text

Parse and render tag-based content

MarkupString allows you to load an tags-based string (even from a file, a literals or content from url) and parse it by applying with your own styles.

Suppose you have this text:

<center>The quick brown fox</center>\njumps over the lazy dogis an <italic>English-language</italic> pangram—a phrase that contains <italic>all</italic> of the letters of the alphabet. It is <extreme><bold>commonly</bold></extreme> used for touch-typing practice.

This text defines following styles: "center", "bold", "italic" and "extreme".

So, in order to render your text you may want create Style instances which represent these tags:

let style_bold = Style("bold", {
  $0.font = FontAttribute(.Futura_CondensedExtraBold, size: 15)
})

let style_center = Style("center", {
  $0.font = FontAttribute(.Menlo_Regular, size: 15)
  $0.align = .center
})

let style_italic = Style("italic", {
  $0.font = FontAttribute(.HelveticaNeue_LightItalic, size: 15)
  $0.color = UIColor.red
})

let style_exteme = Style("extreme", {
  $0.font = FontAttribute(.TimesNewRomanPS_BoldItalicMT, size: 40)
  $0.underline = UnderlineAttribute(color: UIColor.blue, style: NSUnderlineStyle.styleSingle)
})

let sourceTaggedString = "<center>The quick brown fox ..."
let parser = MarkupString(source: sourceTaggedString, [style_center,style_italic,style_exteme,style_bold])!
// Render attributes string
// Result is parsed only upon requested, only first time (then it will be cached).
let test_7 = parser.render(withStyles: [style_bold,style_center,style_italic,style_exteme])

Will produce:

Clearly you can load string also from file at specified URL:

let sourceURL = URL(fileURLWithPath: "...")
let renderedText = RichString(sourceURL, encoding: .utf8, [bold,italic])!.text

Create NSMutableAttributedString from String

func set(style: Style, range: Range<Int>? = nil) -> NSMutableAttributedString Create an NSMutableAttributedString from a simple String instance by applying given style at specified range. If range is missing style will be applied to the entire string.

func set(styles: Style...) -> NSMutableAttributedString Create an NSMutableAttributedString from a simple String instance by applying given styles. Styles are applied in sequence as passed; the only exception is the .default Style if present; in this case .default style is applied in first place.

func set(styles: Style..., pattern: String, options: NSRegularExpression.Options = .caseInsensitive) -> NSAttributedString Create an NSMutableAttributedString from a simple String instance by applying given styles with specified regular expression pattern. Styles are applied in sequence as passed; the only exception is the .default Style if present; in this case .default style is applied in first place.

Manage NSMutableAttributedString

func append(string: String, style: Style) Append a String instance to an existing NSMutableAttributedString by applying given style.

func append(markup string: MarkupString, styles: Style...) Append a MarkupString instance to an existing NSMutableAttributedString by applying given styles.

func add(style: Style, range: Range<Int>? = nil) -> NSMutableAttributedString Append attributes defined by style at given range of existing NSMutableAttributedString Return self for chain purpose.

func add(styles: Style...) -> NSMutableAttributedString Append attributes defined by passed styles into current NSMutableAttributedString. Return self for chain purpose.

func set(style: Style, range: Range<Int>? = nil) -> NSMutableAttributedString Replace any exiting attribute into given range with the one passed in style. Return self for chain purpose.

func set(styles: Style...) -> NSMutableAttributedString Replace any existing attribute into current instance of the attributed string with styles passed. Styles are applied in sequence as passed; the only exception is the .default Style if present; in this case .default style is applied in first place. Return self for chain purpose.

func remove(style: Style, range: Range<Int>? = nil) -> NSMutableAttributedString Remove attributes keys defined in passed style from the instance.

Combine String and NSMutableAttributedString

Combine between simple String and NSMutableAttributedString is pretty straightforward using the Swift's standard + operator. Just an example:

var test_1 = "Hello".set(style: bold) + "\n" + "World!".set(style: highlighted)
test_1.append(string: "\nHow old are you?", style: monospaced)

Installation

You can install Swiftline using CocoaPods, carthage and Swift package manager

• Swift 4.x: 1.1.0
• Swift 3.x: Up to 0.9.10 release

CocoaPods

use_frameworks!
pod 'SwiftRichString'

Carthage

github "malcommac/SwiftRichString"

Swift Package Manager

Add swiftline as dependency in your Package.swift

  import PackageDescription

  let package = Package(name: "YourPackage",
    dependencies: [
      .Package(url: "https://github.com/malcommac/SwiftRichString.git", majorVersion: 0),
    ]
  )

Requirements

Current version (0.9.9+) is compatible with:

• Swift 3.x and Swift 4.x
• iOS 8.0+
• tvOS 9.0+
• macOS 10.10+
• watchOS 2.0+

Credits & License

SwiftRichString is owned and maintained by Daniele Margutti.

As open source creation any help is welcome!

The code of this library is licensed under MIT License; you can use it in commercial products without any limitation.

The only requirement is to add a line in your Credits/About section with the text below:

This software uses open source SwiftRichString's library to manage rich attributed strings.
Web: http://github.com/malcommac/SwiftRichString
Created by Daniele Margutti and licensed under MIT License.