<commit_before>[![Swift 3 Compatible](https://img.shields.io/badge/swift3-compatible-4BC51D.svg?style=flat)](https://developer.apple.com/swift)
[![Platform](https://img.shields.io/cocoapods/p/Texty.svg?style=flat)](http://cocoadocs.org/docsets/Texty)
[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Texty.svg)](https://img.shields.io/cocoapods/v/Texty.svg)
[![Carthage Compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

# Texty
Texty's goal is to make styling text clean and easy. This is accomplished using things like style containers, styled label initializers, and string styling via XML-like tags.

Created and maintained by Vectorform, LLC.


## Requirements:
- iOS 8.0+
- Xcode 8.0+
- Swift 3.0+


## Installation
### CocoaPods
[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects. You can install it with the following command:
```bash
$ gem install cocoapods
```

> CocoaPods 1.0.0+ is required to build Texty.

To integrate Texty into your Xcode project using CocoaPods, specify it in your `Podfile`:

```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Texty', '~> 0.1.4'
end
```

Then, run the following command:

```bash
$ pod install
```

### Carthage
[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with [Homebrew](http://brew.sh/) using the following command:
```bash
$ brew update
$ brew install carthage
```

To integrate Texty into your Xcode project using Carthage, specify it in your `Cartfile`:
```ogdl
github "Vectorform/Texty" ~> 0.1.4
```

Run `carthage update` to build the framework and drag the built `Texty.framework` into your Xcode project.


### Manually
If you prefer not to use any of the listed dependency managers, you can integrate Texty into your project manually.


---


## Usage
### Creating styles
The TextStyle struct was designed to be created once and reused across your entire application.
```swift
/// Create static references to reusable styles
struct Style {
    static let Header1: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.boldSystemFont(ofSize: 24.0)])

    static let Header2: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.boldSystemFont(ofSize: 20.0)])

    static let Normal: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.systemFont(ofSize: 17.0)])
    
    static let Underline: TextStyle = TextStyle(attributes: [TextAttribute.underlineStyle : NSUnderlineStyle.styleSingle])
}
```
```swift
/// Reuse your defined styles across your entire application
class ViewController: UIViewController {
    private let headerLabel: TextyLabel = TextyLabel(style: Style.Header1)
    private let textLabel: TextyLabel = TextyLabel(style: Style.Normal)
}
```


### Available attributes
| TextAttribute      | Expected Type     | Native Equivalent                 |
|--------------------|-------------------|-----------------------------------|
| attachment         | NSTextAttachment  | NSAttachmentAttributeName         |
| backgroundColor    | UIColor           | NSBackgroundColorAttributeName    |
| baselineOffset     | NSNumber          | NSBaselineOffsetAttributeName     |
| expansion          | NSNumber          | NSExpansionAttributeName          |
| font               | UIFont            | NSFontAttributeName               |
| foregroundColor    | UIColor           | NSForegroundColorAttributeName    |
| kern               | NSNumber          | NSKernAttributeName               |
| ligature           | NSNumber          | NSLigatureAttributeName           |
| link               | NSURL or NSString | NSLinkAttributeName               |
| obliqueness        | NSNumber          | NSObliquenessAttributeName        |
| paragraphStyle     | NSParagraphStyle  | NSParagraphStyleAttributeName     |
| shadow             | NSShadow          | NSShadowAttributeName             |
| strikethroughColor | UIColor           | NSStrikethroughColorAttributeName |
| strikethroughStyle | NSNumber          | NSStrikethroughStyleAttributeName |
| strokeColor        | UIColor           | NSStrokeColorAttributeName        |
| strokeWidth        | NSNumber          | NSStrokeWidthAttributeName        |
| textEffect         | NSString          | NSTextEffectAttributeName         |
| underlineColor     | UIColor           | NSUnderlineColorAttributeName     |
| underlineStyle     | NSNumber          | NSUnderlineStyleAttributeName     |
| verticalGlyphForm  | NSNumber          | NSVerticalGlyphFormAttributeName  |
| writingDirection   | Array\<NSNumber\> | NSWritingDirectionAttributeName   |

More information about each attribute can be found in Apple's [documentation](https://developer.apple.com/reference/foundation/nsattributedstring/character_attributes).


### TextyLabel
TextyLabel is a subclass of UILabel created specifically to work with TextStyle structs. The core power of TextyLabel comes from its initializer.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
```
Be careful when subclassing TextyLabel as some properties are overriden to be referenced from the associated style struct rather than their native locations. 

Subclassing TextyLabel and overriding one of these properties without calling the super class ***will*** result in undefined behavior.

| Property      | Overriden Target                   |
|---------------|------------------------------------|
| font          | style.font                         |
| lineBreakMode | style.paragraphStyle.lineBreakMode |
| text          | attributedText                     |
| textAlignment | style.paragraphStyle.alignment     |
| textColor     | style.foregroundColor              |


### Styling text via tags
Texty provides the ability to style parts of a string using XML-like tags within the string.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
self.titleLabel.style.setStyle(Style.Underline, forTag: "underline")
self.titleLabel.text = "This is a <underline>TextyLabel</underline>"
```

You can also forego creating a TextStyle for simple attributes and use an attribute dictionary instead.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
self.titleLabel.style.setAttributes([TextAttribute.underlineStyle : NSUnderlineStyle.styleSingle.rawValue], forTag: "underline")
self.titleLabel.text = "This is a <underline>TextyLabel</underline>"
```

Unlike XML, tags do not have to be balanced. For example, the following string is valid (given that the bold and italic tags are defined):

```This is <italic>an example <bold>string used</italic> for demonstration</bold> purposes.```

**It is important that your closing tags have the forward slash at the beginning and not the end.**

| Good      | Bad       |
|-----------|-----------|
| \</bold\> | \<bold/\> |

Forward slashes at the end of a tag will cause the tag to be detected as a *short tag*, which will have a use in the future, but currently offers nothing.<commit_msg>Fix wording<commit_after>[![Swift 3 Compatible](https://img.shields.io/badge/swift3-compatible-4BC51D.svg?style=flat)](https://developer.apple.com/swift)
[![Platform](https://img.shields.io/cocoapods/p/Texty.svg?style=flat)](http://cocoadocs.org/docsets/Texty)
[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Texty.svg)](https://img.shields.io/cocoapods/v/Texty.svg)
[![Carthage Compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

# Texty
Texty's goal is to make styling text clean and easy. This is accomplished using things like style containers, styled label initializers, and string styling via XML-like tags.

Created and maintained by Vectorform, LLC.


## Requirements:
- iOS 8.0+
- Xcode 8.0+
- Swift 3.0+


## Installation
### CocoaPods
[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects. You can install it with the following command:
```bash
$ gem install cocoapods
```

> CocoaPods 1.0.0+ is required to build Texty.

To integrate Texty into your Xcode project using CocoaPods, specify it in your `Podfile`:

```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Texty', '~> 0.1.4'
end
```

Then, run the following command:

```bash
$ pod install
```

### Carthage
[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with [Homebrew](http://brew.sh/) using the following command:
```bash
$ brew update
$ brew install carthage
```

To integrate Texty into your Xcode project using Carthage, specify it in your `Cartfile`:
```ogdl
github "Vectorform/Texty" ~> 0.1.4
```

Run `carthage update` to build the framework and drag the built `Texty.framework` into your Xcode project.


### Manually
If you prefer not to use any of the listed dependency managers, you can integrate Texty into your project manually.


---


## Usage
### Creating styles
The TextStyle struct was designed to be created once and reused across your entire application.
```swift
/// Create static references to reusable styles
struct Style {
    static let Header1: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.boldSystemFont(ofSize: 24.0)])

    static let Header2: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.boldSystemFont(ofSize: 20.0)])

    static let Normal: TextStyle = TextStyle(attributes: [.foregroundColor : UIColor.black, .font : UIFont.systemFont(ofSize: 17.0)])
    
    static let Underline: TextStyle = TextStyle(attributes: [TextAttribute.underlineStyle : NSUnderlineStyle.styleSingle])
}
```
```swift
/// Reuse your defined styles across your entire application
class ViewController: UIViewController {
    private let headerLabel: TextyLabel = TextyLabel(style: Style.Header1)
    private let textLabel: TextyLabel = TextyLabel(style: Style.Normal)
}
```


### Available attributes
| TextAttribute      | Expected Type     | Native Equivalent                 |
|--------------------|-------------------|-----------------------------------|
| attachment         | NSTextAttachment  | NSAttachmentAttributeName         |
| backgroundColor    | UIColor           | NSBackgroundColorAttributeName    |
| baselineOffset     | NSNumber          | NSBaselineOffsetAttributeName     |
| expansion          | NSNumber          | NSExpansionAttributeName          |
| font               | UIFont            | NSFontAttributeName               |
| foregroundColor    | UIColor           | NSForegroundColorAttributeName    |
| kern               | NSNumber          | NSKernAttributeName               |
| ligature           | NSNumber          | NSLigatureAttributeName           |
| link               | NSURL or NSString | NSLinkAttributeName               |
| obliqueness        | NSNumber          | NSObliquenessAttributeName        |
| paragraphStyle     | NSParagraphStyle  | NSParagraphStyleAttributeName     |
| shadow             | NSShadow          | NSShadowAttributeName             |
| strikethroughColor | UIColor           | NSStrikethroughColorAttributeName |
| strikethroughStyle | NSNumber          | NSStrikethroughStyleAttributeName |
| strokeColor        | UIColor           | NSStrokeColorAttributeName        |
| strokeWidth        | NSNumber          | NSStrokeWidthAttributeName        |
| textEffect         | NSString          | NSTextEffectAttributeName         |
| underlineColor     | UIColor           | NSUnderlineColorAttributeName     |
| underlineStyle     | NSNumber          | NSUnderlineStyleAttributeName     |
| verticalGlyphForm  | NSNumber          | NSVerticalGlyphFormAttributeName  |
| writingDirection   | Array\<NSNumber\> | NSWritingDirectionAttributeName   |

More information about each attribute can be found in Apple's [documentation](https://developer.apple.com/reference/foundation/nsattributedstring/character_attributes).


### TextyLabel
TextyLabel is a subclass of UILabel created specifically to work with TextStyle structs. The core power of TextyLabel comes from its initializer.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
```
Be careful when subclassing TextyLabel as some properties are overriden to be referenced from the associated style struct rather than their native locations. 

Subclassing TextyLabel and overriding one of these properties without calling the super class ***will*** result in undefined behavior.

| Property      | Overriden Target                   |
|---------------|------------------------------------|
| font          | style.font                         |
| lineBreakMode | style.paragraphStyle.lineBreakMode |
| text          | attributedText                     |
| textAlignment | style.paragraphStyle.alignment     |
| textColor     | style.foregroundColor              |


### Styling text via tags
Texty provides the ability to style parts of a string using XML-like tags within the string.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
self.titleLabel.style.setStyle(Style.Underline, forTag: "underline")
self.titleLabel.text = "This is a <underline>TextyLabel</underline>"
```

You can also forego creating a TextStyle and use an attribute dictionary instead.
```swift
let titleLabel: TextyLabel = TextyLabel(style: Style.Header1)
self.titleLabel.style.setAttributes([TextAttribute.underlineStyle : NSUnderlineStyle.styleSingle.rawValue], forTag: "underline")
self.titleLabel.text = "This is a <underline>TextyLabel</underline>"
```

Unlike XML, tags do not have to be balanced. For example, the following string is valid (given that the bold and italic tags are defined):

```This is <italic>an example <bold>string used</italic> for demonstration</bold> purposes.```

**It is important that your closing tags have the forward slash at the beginning and not the end.**

| Good      | Bad       |
|-----------|-----------|
| \</bold\> | \<bold/\> |

Forward slashes at the end of a tag will cause the tag to be detected as a *short tag*, which will have a use in the future, but currently offers nothing.
{'fraction_non_alphanumeric': 0.11192180616740088, 'fraction_numerical': 0.005644273127753304, 'mean_word_length': 3.1334281650071123, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 33, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '584802', 'n_tokens_mistral': 4151, 'n_tokens_neox': 3871, 'n_words': 1217}