Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@adityatrivedi
adityatrivedi committed Mar 4, 2016
1 parent 0ea9d61 commit e656893
Showing 1 changed file with 91 additions and 62 deletions.
153 changes: 91 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[![Tailor](https://cloud.githubusercontent.com/assets/1350704/9867389/18ae2e06-5b3b-11e5-9b37-72a3e9621b9c.png)](https://tailor.sh)

<p align="center">
<a href="https://travis-ci.org/sleekbyte/tailor">
<img src="https://travis-ci.org/sleekbyte/tailor.svg?branch=master" alt="Build Status">
Expand All @@ -25,43 +26,57 @@

[Tailor][] is a cross-platform [static analysis][] and [lint][] tool for source code written in Apple's [Swift][] programming language. It analyzes your code to ensure consistent styling and help avoid bugs.

# [Tailor][]. Cross-platform static analyzer and linter for [Swift][].
[static analysis]: https://en.wikipedia.org/wiki/Static_program_analysis
[lint]: https://en.wikipedia.org/wiki/Lint_(software)

## [Tailor][]. Cross-platform static analyzer and linter for [Swift][].

[Tailor]: https://tailor.sh
[Swift]: https://swift.org

Tailor supports Swift 2 out of the box and helps enforce style guidelines outlined in the [The Swift Programming Language][], [GitHub][], [Ray Wenderlich][], and [Coursera][] style guides. It supports cross-platform usage and can be run on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows.

[The Swift Programming Language]: https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/
[GitHub]: https://github.com/github/swift-style-guide
[Ray Wenderlich]: https://github.com/raywenderlich/swift-style-guide
[Coursera]: https://github.com/coursera/swift-style-guide

Tailor parses Swift source code using the primary Java target of [ANTLR](http://www.antlr.org):

> ANTLR is a powerful parser generator [ . . . ] widely used in academia and industry to build all sorts of languages, tools, and frameworks.
-- [About the ANTLR Parser Generator](http://www.antlr.org/about.html)
— [About the ANTLR Parser Generator](http://www.antlr.org/about.html)

**See the [wiki](https://github.com/sleekbyte/tailor/wiki) for the full documentation.**

# Getting Started

## Installation
Requires Java (JRE or JDK) Version 8 or above: [Java SE Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html)

### [Homebrew](http://brew.sh), [Linuxbrew](http://brew.sh/linuxbrew/)
Requires Java (JRE or JDK) Version 8 or above: [Java SE Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
#### [Homebrew](http://brew.sh), [Linuxbrew](http://brew.sh/linuxbrew/)

```bash
brew install tailor
```

### Mac OS X (10.10+), Linux
#### Mac OS X (10.10+), Linux

```bash
curl -fsSL https://tailor.sh/install.sh | sh
```

### Windows (10+)
#### Windows (10+)

```powershell
iex (new-object net.webclient).downloadstring('https://tailor.sh/install.ps1')
```

### Manually
#### Manually
You may also download Tailor via [GitHub Releases](https://github.com/sleekbyte/tailor/releases), extract the archive, and symlink the `tailor/bin/tailor` shell script to a location in your `$PATH`.

### Continuous Integration
#### Continuous Integration

If your continuous integration server supports [Homebrew](http://brew.sh) installation, you may use the following snippet:

```yaml
Expand All @@ -82,6 +97,7 @@ before_script:
```

## Usage

Run Tailor with a list of files and directories to analyze, or via Xcode.

```bash
Expand Down Expand Up @@ -126,88 +142,88 @@ Options:
```

# Features
- [Enabling and Disabling Rules](#enabling-and-disabling-rules)
- [Cross-Platform](#cross-platform)
- [Automatic Xcode Integration](#automatic-xcode-integration)
- [Colorized Output](#colorized-output)
- [Warnings, Errors, and Failing the Build](#warnings-errors-and-failing-the-build)
- [Disable Violations within Source Code](#disable-violations-within-source-code)
- [Configuration](#configuration)
- [Formatters](#formatters)

## Enabling and Disabling Rules
* [Enabling and Disabling Rules](#enabling-and-disabling-rules)
* [Cross-Platform](#cross-platform)
* [Automatic Xcode Integration](#automatic-xcode-integration)
* [Colorized Output](#colorized-output)
* [Warnings, Errors, and Failing the Build](#warnings-errors-and-failing-the-build)
* [Disable Violations within Source Code](#disable-violations-within-source-code)
* [Configuration](#configuration)
* [Formatters](#formatters)

### Enabling and Disabling Rules

**Rule identifiers and "preferred/not preferred" code samples may be found on the [Rules](https://github.com/sleekbyte/tailor/wiki/Rules) page.**

Rules may be individually disabled (blacklist) or enabled (whitelist) via the `--except` and `--only` command-line flags.

### Except

#### Except
```bash
tailor --except=brace-style,trailing-whitespace main.swift
```

### Only

#### Only
```bash
tailor --only=redundant-parentheses,terminating-semicolon main.swift
```

## Cross-Platform
### Cross-Platform
Tailor may be used on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows.

### Linux
#### Linux
![Tailor on Ubuntu](https://cloud.githubusercontent.com/assets/1350704/9894130/2b959794-5bee-11e5-9ed2-84d035895239.png)

### Windows
#### Windows
![Tailor on Windows](https://cloud.githubusercontent.com/assets/1791760/9913016/2ff0e9a8-5cc8-11e5-8722-d5a6f9d84027.PNG)

## Automatic Xcode Integration
### Automatic Xcode Integration
Tailor can be integrated with Xcode projects using the `--xcode` option.

```bash
tailor --xcode /path/to/demo.xcodeproj/
```
This adds the following Build Phase Run Script to your project's default target.
![Run Script](https://cloud.githubusercontent.com/assets/1350704/11074861/5bae6b24-87f2-11e5-8167-4328b9b01174.png)

This adds the following Build Phase Run Script to your project's default target. ![Run Script](https://cloud.githubusercontent.com/assets/1350704/11074861/5bae6b24-87f2-11e5-8167-4328b9b01174.png)
Tailor's output will be displayed inline within the Xcode Editor Area and as a list in the Log Navigator.
![Xcode messages](https://cloud.githubusercontent.com/assets/1350704/11017260/b79cb162-8599-11e5-94fa-e7cf77fdc657.png)

Tailor's output will be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. ![Xcode messages](https://cloud.githubusercontent.com/assets/1350704/11017260/b79cb162-8599-11e5-94fa-e7cf77fdc657.png)

## Colorized Output
### Colorized Output
Tailor uses the following color schemes to format CLI output:
- **Dark theme** (enabled by default)
- ![Dark theme](https://cloud.githubusercontent.com/assets/1791760/9807444/fde82de6-5870-11e5-9e20-05a9d736e136.png)
- **Light theme** (enabled via `--invert-color` option)
- ![Light theme](https://cloud.githubusercontent.com/assets/1791760/9807312/129ce45e-586f-11e5-8e26-fe818af0ec09.png)
- **No color theme** (enabled via `--no-color` option)
- ![No color](https://cloud.githubusercontent.com/assets/1791760/9807318/261811d4-586f-11e5-9010-0e627431bbb9.png)

## Warnings, Errors, and Failing the Build

* **Dark theme** (enabled by default)
![Dark theme](https://cloud.githubusercontent.com/assets/1791760/9807444/fde82de6-5870-11e5-9e20-05a9d736e136.png)
* **Light theme** (enabled via `--invert-color` option)
![Light theme](https://cloud.githubusercontent.com/assets/1791760/9807312/129ce45e-586f-11e5-8e26-fe818af0ec09.png)
* **No color theme** (enabled via `--no-color` option)
![No color](https://cloud.githubusercontent.com/assets/1791760/9807318/261811d4-586f-11e5-9010-0e627431bbb9.png)

### Warnings, Errors, and Failing the Build
`--max-severity` can be used to control the maximum severity of violation messages. It can be set to `error` or `warning` (by default, it is set to `warning`). Setting it to `error` allows you to distinguish between lower and higher priority messages. It also fails the build in Xcode, if any errors are reported (similar to how a compiler error fails the build in Xcode). With `max-severity` set to `warning`, all violation messages are warnings and the Xcode build will never fail.

This setting also affects Tailor's exit code on the command-line, a failing build will `exit 1` whereas having warnings only will `exit 0`, allowing Tailor to be easily integrated into pre-commit hooks.

## Disable Violations within Source Code
### Disable Violations within Source Code
Violations on a specific line may be disabled with a **trailing** single-line comment.

```swift
import Foundation; // tailor:disable
```

## Configuration
### Configuration
The behavior of Tailor can be customized via the `.tailor.yml` configuration file. It enables you to
- include/exclude certain files and directories from analysis
- enable and disable specific analysis rules
- specify output format
* include/exclude certain files and directories from analysis
* enable and disable specific analysis rules
* specify output format
* specify CLI output color scheme

You can tell Tailor which configuration file to use by specifying its file path via the `--config` CLI option. By default, Tailor will look for the configuration file in the directory where you will run Tailor from.

The file follows the [YAML 1.1](http://www.yaml.org/spec/1.1/) format.

### Including/Excluding files
#### Including/Excluding files
Tailor checks all files found by a recursive search starting from the directories given as command line arguments. However, it only analyzes Swift files that end in `.swift`. If you would like Tailor to analyze specific files and directories, you will have to add entries for them under `include`. Files and directories can also be ignored through `exclude`.

Here is an example that might be used for an iOS project:

```YAML
include:
- Source # Inspect all Swift files under "Source/"
Expand All @@ -217,17 +233,16 @@ exclude:
- Source/Pods # Ignore Swift files under "Source/Pods/"
```

#### Notes
- Files and directories are specified relative to where `tailor` is run from
- Paths to directories or Swift files provided explicitly via CLI will cause the `include`/`exclude` rules specified in `.tailor.yml` to be ignored
- _Exclude_ is given higher precedence than _Include_
- Tailor recognizes the [Java Glob](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob) syntax
##### Notes
* Files and directories are specified relative to where `tailor` is run from
* Paths to directories or Swift files provided explicitly via CLI will cause the `include`/`exclude` rules specified in `.tailor.yml` to be ignored
* *Exclude* is given higher precedence than *Include*
* Tailor recognizes the [Java Glob](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob) syntax

### Enabling/Disabling rules
#### Enabling/Disabling rules
Tailor allows you to individually disable (blacklist) or enable (whitelist) rules via the `except` and `only` labels.

Here is an example showcasing how to enable certain rules:

```YAML
# Tailor will solely check for violations to the following rules
only:
Expand All @@ -238,19 +253,18 @@ only:
```

Here is an example showcasing how to disable certain rules:

```YAML
# Tailor will check for violations to all rules except for the following ones
except:
- parenthesis-whitespace
- lower-camel-case
```

#### Notes
- _only_ is given precedence over _except_
- Rules that are explicitly included/excluded via CLI will cause the `only`/`except` rules specified in `.tailor.yml` to be ignored
##### Notes
* *only* is given precedence over *except*
* Rules that are explicitly included/excluded via CLI will cause the `only`/`except` rules specified in `.tailor.yml` to be ignored

### Specifying output format
#### Specifying output format
Tailor allows you to specify the output format (`xcode`/`json`) via the `format` label.

Here is an example showcasing how to specify the output format:
Expand All @@ -260,13 +274,27 @@ Here is an example showcasing how to specify the output format:
format: json
```

#### Notes
##### Note
- The output format explicitly specified via CLI will cause the output format defined in `.tailor.yml` to be ignored

## Formatters
#### Specifying CLI output color scheme
Tailor allows you to specify the CLI output color schemes via the `color` label. To disable colored output, set `color` to `disable`. To invert the color scheme, set `color` to `invert`.

Here is an example showcasing how to specify the CLI output color scheme:

```YAML
# The CLI output will not be colored
format: disable
```

##### Note
- The CLI output color scheme explicitly specified via CLI will cause the output color scheme defined in `.tailor.yml` to be ignored

### Formatters
Tailor's output format may be customized via the `-f`/`--format` option. The Xcode formatter is selected by default.

### Xcode Formatter (default)
#### Xcode Formatter (default)

The default `xcode` formatter outputs violation messages according to the format expected by Xcode to be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. This format is also as human-friendly as possible on the console.

```
Expand All @@ -282,7 +310,8 @@ $ tailor main.swift
Analyzed 1 file, skipped 0 files, and detected 5 violations (0 errors, 5 warnings).
```

### [JSON](http://www.json.org) Formatter
#### [JSON](http://www.json.org) Formatter

The `json` formatter outputs an array of violation messages for each file, and a `summary` object indicating the parsing results and the violation counts.

```
Expand Down

0 comments on commit e656893

Please sign in to comment.