PrettyString 1.0.0

PrettyString 1.0.0

Maintained by Cameron Eldridge.



  • By
  • Cameron Eldridge

PrettyString

CI Status Version License Platform

PrettyString defines a highly customizable, and extremely simple syntax for making strings pretty.

Where XML, HTML and Markdown based alternatives exist, PrettyString provides significantly more flexibility than Markdown with a much cleaner syntax than HTML.

Usage

PrettyString allows you to specify sections within your string which are to be styled using certain attributes. To denote a section uses the syntax {name:text}, like this:

let string = "Hello this is some {blue:blue text}"

Here, the name is blue, and the text is blue text. What this name means, however, is entirely up to you. There are no built in styles. Fortunately defining a style is very simple:

let config = PrettyString.Config(
    base: [],
    rules: [
        PrettyString.Config.Rule(
            name: "blue",
            attributes: [
                .foregroundColor(UIColor.blue)
            ]
        )
    ]
)

It looks a little big, but it's really very simple. The config consists of two parts: the base, and some rules.

The base is just a list of Attributes which should be applied to the entire string.

The rules are then a list of Rules. Each rule has a name, such as blue, and then a list of Attributes that should be applied when this name is encountered.

Once you have a string and a Config, you are ready to prettify your strings!

let attributedString = try! string.prettify(config)

Note that the conversion from String to NSAttributedString can fail, and so you must use try or one of its variations to handle the error. The error that is thrown is of type PrettyString.Error, and may provide some hint as to why your string has failed to parse.

If you find yourself always using the same Config object, you can even set the default config so that calling prettify with no arguments will use it automatically. That means, the attributedString below is the same as the one above!

PrettyString.Config.default = config
let attributedString = try! string.prettify()

The attributes

The full list of attributes is as follows:

enum Attribute {
    case attachment(NSTextAttachment)
    case backgroundColor(UIColor)
    case baselineOffset(Float)
    case expansion(Float)
    case font(UIFont)
    case foregroundColor(UIColor)
    case kern(Float)
    case ligature(Int)
    case link(URL)
    case obliqueness(Float)
    case paragraphStyle(NSParagraphStyle)
    case shadow(NSShadow)
    case strikethroughColor(UIColor)
    case strikethroughStyle(Int)
    case strokeColor(UIColor)
    case strokeWidth(Float)
    case textEffect(String)
    case underlineColor(UIColor)
    case underlineStyle(NSUnderlineStyle)
    case writingDirection([Int])
}

Each corresponds to the NSAttributedStringKey of the same name. Their usage should be pretty straightforward.

Advanced Usage

Escape Characters

All the regular escape characters and unicode sequences should just work, but what about actually writing the { or } character in your string? To do that, escape it with an extra { in front.

That is, this: "{{he said: hello{}" will actually give you the string {he said: hello} with no attributes, rather than trying to find a rule called he said and applying it to hello{.

Nesting

Nesting of the attributed sections works as well. The attributes from the inner-most section will override any of the outer styles, similar to how named sections will override the base styles:

{green-italics:hello {red-and-bold:there}} should show "hello" in green italics and "there" in bold red italics (assuming you named the rules well).

Rule Names

The actual rules can have any character in them except for :, since that is used to mark the end of the name. You can even have a rule with { or } in the name, so long as it's not the first character. I really suggest against doing this though, and just stick to the usual letters, underscores, and hyphens since that ends up being the most clear.

Explicit API

If you prefer not to use the extension to the String type, the PrettyString struct itself can be used directly:

let string = "This is some {blue:blue text}"
let prettyString = PrettyString(string, config: config)
let attributedString = try! prettyString.parse()

Requirements

This project uses Swift 4, and you should too.

Installation

PrettyString is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'PrettyString', '~> 0.1'

Author

Cameron Eldridge, [email protected]

License

PrettyString is available under the MIT license. See the LICENSE file for more info.