diff --git a/README.md b/README.md index 57468a4f..9cbec4c7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ [![Tailor](https://cloud.githubusercontent.com/assets/1350704/9867389/18ae2e06-5b3b-11e5-9b37-72a3e9621b9c.png)](https://tailor.sh) +

Build Status @@ -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 @@ -82,6 +97,7 @@ before_script: ``` ## Usage + Run Tailor with a list of files and directories to analyze, or via Xcode. ```bash @@ -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/" @@ -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: @@ -238,7 +253,6 @@ 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: @@ -246,11 +260,11 @@ except: - 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: @@ -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. ``` @@ -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. ```