travis-yaml 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 752665752154cdb3b8bc22e2dd0cf9eb6c79e36c
+  data.tar.gz: c7449c2793420fe650091f84eb749e037436c453
+SHA512:
+  metadata.gz: 751b783a0265500138733893196c3853ec3f8eeee609a921077dad79bd7e8fcbfbef093259657ce9737112f6ea8234f00886663fdc167fe931ac721ca2eb54ef
+  data.tar.gz: 161583c79e9e1e820e1a9495d10b103d4f2a715a59d6956a4f1d8112fe07cb0baa328a69986d8613cdf716cca405d9c819e885fd69ad0db69bba5daa8539797e

data/.gitignore

@@ -0,0 +1 @@
+.coverage

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--tty
+-r support

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+- 1.9.3
+- 2.0.0
+script: bundle exec rspec
+bundler_args: "--without play"
+deploy:
+  provider: heroku
+  api_key:
+    secure: OrCcUz+MNjlxNkReqCvQZq62Y5mdKxjA+Lwo6VdsuoWHIJ8ShKIZUhoWOE6B0VIYSxSBObkXULitqiuZAvJfHSmS6soowPc79VvVeetMkIxRbHG9v3utg5O5pHqjHeW7pOWwrvTR5sria9YPevFN3+0R/C3xsxnQrc8dw+06jEQ=
+  app: travis-yaml
+  on:
+    repo: travis-ci/travis-yaml
+    ruby: 2.0.0

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+gemspec
+
+group :play do
+  gem 'sinatra'
+  gem 'sass', '~> 3.1'
+  gem 'slim', '~> 1.3'
+  gem 'gh'
+end

data/Gemfile.lock

@@ -0,0 +1,73 @@
+PATH
+  remote: .
+  specs:
+    travis-yaml (0.1.0)
+      psych (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.5)
+    backports (3.4.0)
+    diff-lcs (1.2.5)
+    docile (1.1.3)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    gh (0.13.0)
+      addressable
+      backports
+      faraday (~> 0.8)
+      multi_json (~> 1.0)
+      net-http-persistent (>= 2.7)
+      net-http-pipeline
+    multi_json (1.8.4)
+    multipart-post (2.0.0)
+    net-http-persistent (2.9)
+    net-http-pipeline (1.0.1)
+    psych (2.0.4)
+    rack (1.5.2)
+    rack-protection (1.5.2)
+      rack
+    rake (10.1.1)
+    rspec (3.0.0.beta2)
+      rspec-core (= 3.0.0.beta2)
+      rspec-expectations (= 3.0.0.beta2)
+      rspec-mocks (= 3.0.0.beta2)
+    rspec-core (3.0.0.beta2)
+      rspec-support (= 3.0.0.beta2)
+    rspec-expectations (3.0.0.beta2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (= 3.0.0.beta2)
+    rspec-mocks (3.0.0.beta2)
+      rspec-support (= 3.0.0.beta2)
+    rspec-support (3.0.0.beta2)
+    safe_yaml (1.0.1)
+    sass (3.3.3)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    sinatra (1.4.4)
+      rack (~> 1.4)
+      rack-protection (~> 1.4)
+      tilt (~> 1.3, >= 1.3.4)
+    slim (1.3.9)
+      temple (~> 0.6.3)
+      tilt (~> 1.3, >= 1.3.3)
+    temple (0.6.7)
+    tilt (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  gh
+  rake
+  rspec (~> 3.0.0.beta)
+  safe_yaml (~> 1.0.1)
+  sass (~> 3.1)
+  simplecov
+  sinatra
+  slim (~> 1.3)
+  travis-yaml!

data/LICENSE

@@ -0,0 +1,22 @@
+MIT LICENSE
+
+Copyright (c) 2014 Travis CI GmbH <support@travis-ci.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,232 @@
+# Travis Configuration Parser
+
+## What is this?
+
+This project is a library for loading Travis CI build configuration.
+
+It can create a configuration both from a normal Ruby Hash or a YAML string.
+These config objects generally behave like normal primitives (hashes, arrays, etc).
+
+``` ruby
+require 'travis/yaml'
+
+config = Travis::Yaml.parse('language: ruby')
+config = Travis::Yaml.parse(language: 'ruby')
+
+config[:language] # ruby
+config.language   # ruby
+
+# using parse! instead of parse will print out warnings
+Travis::Yaml.parse! deploy: []
+# .travis.yml: missing key "language", defaulting to "ruby"
+# .travis.yml: value for "deploy" section is empty, dropping
+
+# have it generate the build matrix for you
+Travis::Yaml.matrix('rvm: [jruby, 2.0.0]').each do |matrix_entry|
+  puts matrix_entry.ruby
+end
+```
+
+## Why use it?
+
+* **Prevents code execution.** Instead of deserializing arbitrary Ruby objects, it only deserializes primitive objects. To go even further, in contrast to SafeYAML, it only deserializes primitive objects that are expected for a certain part of the configuration.
+* **Prevents memory leaks.** Internally, only expected values are stored in the data structure, discarding any additional data. No user input is converted to symbols (which would allow a memory based DoS attack).
+* **Normalization is happening in one place.** Travis CI currently does config normalization in many different parts of its infrastructure, making it tedious to determine supported input formats and the resulting internal structure.
+* **Explicit structure.** Due to the explicit configuration structure, exceptions throughout the system can be greatly reduced, since the configuration will not contain unexpected objects.
+* **Forgiving about user input.** The parser knows the expected structure and can therefore automatically map some malformed input onto that structure. For instance, `node: 1.10` does not get converted to `node: 1.1` internally, because travis-yaml knows to expect a string here rather than a float.
+* **Built-in support for encrypted values**, making it easier to support these in different parts of the system and never leak the decrypted form if configuration is being serialized.
+* **Extensive warning and error handling**, making it possible to use this library for linting and also to display such warnings when running a build.
+* **Performance.** Using travis-yaml to load a configuration from a YAML string is slightly faster than using psych directly and significantly faster than using safeyaml.
+* **Compatibility.** This library is written in a way to not only be fully compatible with the current .travis.yml format, but also with the configuration data in the current Travis database and with the code interacting with the configuration data (for instance in travis-build).
+* **Extensibility.** The configuration structure is easily extended.
+* **Pluggable parser.** It is easy to write a new parser. This would be useful for instance for the Travis CI command line client, where one could imagine a parser for the small subset of the YAML format that is commonly in use. This would for instance allow to write a parser and serializer able to preserve comments and indentation when modifying the contents of the .travis.yml.
+
+## What is missing?
+
+* Full definition of current .travis.yml format
+* Serialization
+
+## Defining Structure
+
+Good starting points for getting into the code are the [root](lib/travis/yaml/nodes/root.rb) node and the [language](lib/travis/yaml/nodes/language.rb) node.
+
+A parsed configuration is very similar to a syntax tree. To create a new node type, you should inherit from one of the abstract types. Internal vocabulary is taken from the YAML spec rather than the Ruby names (ie, sequence vs array, mapping vs hash).
+
+### Scalar Values
+
+Most of the time, scalar values are just strings. In fact, if you create a new scalar node class and don't specify and other supported type, it will treat everything as string.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < Scalar
+  end
+end
+```
+
+This will parse `foo` to `"foo"` and `1.10` to `1.10`. This will also generate a warning and discard values like `!float 1.10`.
+
+#### Value Types
+
+You can also allow other types and change the default type unsupported implicit types are cast to.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < Scalar
+    cast :str, :binary, :int
+    default_type :int
+  end
+end
+```
+
+Available types are `str`, `binary`, `bool`, `float`, `int`, `time`, `secure` and `null`.
+
+#### Default Value
+
+It is also possible to give a scalar a default value.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < Scalar
+    default_value "example"
+  end
+end
+```
+
+This is handy when using it for a required entry in a mapping (for instance, `language` is required, but has a default).
+
+#### Fixed Value Set
+
+For entries that have a well defined set of values, you can inherit from `FixedValue`:
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < FixedValue
+    ignore_case
+
+    default_value :example
+    value :foo, :bar, baz: :bar
+  end
+end
+```
+
+This will, for example, map `FOO` to `"foo"`, `baz` to `"bar"`, and `blah` to `"example"` (and generate a warning about `blah` being not supported).
+
+#### Shorthands
+
+There are shorthands for creating `Scalar` and `FixedValue` subclasses:
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < Map
+    map :foo, to: Scalar[:int]
+    map :bar, to: FixedValue[:foo, :bar]
+  end
+end
+```
+
+### Sequences
+
+Sequences correspond to Ruby arrays. If you pass in a scalar or mapping instead of a sequence, it will be treated as if it was a sequence with a single entry of that value.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class ExampleList < Sequence
+    type ExampleValue # node type, defaults to Scalar
+  end
+end
+```
+
+### Mappings
+
+Mappings correspond to hashes in Ruby.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class ExampleMapping < Mapping
+    # map the value for the "example" key to an Example node
+    # map the value for the "other" key to an Other node
+    map :example, :other
+
+    # map the values for "foo" and "bar" to a Scalar
+    map :foo, :bar, to: Scalar
+
+    # map "list" to a Sequence, keep it even if it's empty
+    map :list, to: Sequence, drop_empty: false
+
+    # require "setting" to be present
+    map :setting, required: true
+
+    # make "option" an alias for "setting"
+    map :option, to: :setting
+
+    # if a scalar is passed in instead of a mapping, treat it as
+    # the value of "setting" ("foo" becomes { setting: "foo" })
+    prefix_scalar :setting
+  end
+end
+```
+
+#### Open Mappings
+
+Sometimes it is not possible to define all available keys for a mapping. You can solve this by using an open mapping:
+
+``` ruby
+module Travis::Yaml::Nodes
+  class ExampleMapping < OpenMapping
+    # node type for entries not specified (defaults to Scalar)
+    default_type ExampleValue
+
+    # map "setting" to Setting node, make it a requirement
+    map :setting, required: true
+  end
+end
+```
+
+You can also limit the possible keys by overriding `accept_key?`.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class ExampleMapping < OpenMapping
+    default_type ExampleValue
+
+    def accept_key?(key)
+      key.start_with? "example_"
+    end
+  end
+end
+```
+
+### Additional Verification
+
+Besides the generated warnings, validations and normalizations inherent to the structure, you can define your own checks and normalizations by overriding the `verify` method.
+
+``` ruby
+module Travis::Yaml::Nodes
+  class Example < Scalar
+    def verify
+      if value == "foo"
+        warning "foo is deprecated, using bar instead"
+        self.value = "bar"
+      end
+      super
+    end
+  end
+end
+```
+
+The `warning` method will generate track a warning, so it can be presented to the user later on. The `error` method will lead to the node being removed from its parent node. It will also propagate the error message as a warning in the parent node.
+
+### Nested Warnings
+
+When reflecting upon a node, `warnings` and `errors` will only contain the messages for that specific node. To get all the warnings for the entire tree, use `nested_warnings`, which will also give you the path (as array of strings).
+
+``` ruby
+config.nested_warnings.each do |path, message|
+  p path      # ["my", "example", "key"]
+  p message   # "this is the warning"
+end
+```
+
+## Requirements
+
+This project requires Ruby 1.9.3 or 2.0.0 and Psych ~> 2.0 (part of the stdlib).

data/Rakefile

@@ -0,0 +1,3 @@
+task(:spec)     { ruby '-S rspec' }
+task(:generate) { ruby 'play/spec.rb' }
+task(default: [:spec, :generate])

data/SPEC.md

@@ -0,0 +1,1018 @@
+## The `.travis.yml` Format
+Here is a list of all the options understood by travis-yaml.
+
+Note that stricitly speaking Travis CI might not have the same understanding of these as travis-yaml has at the moment, since travis-yaml is not yet being used.
+
+### Available Options
+#### `after_deploy`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `after_failure`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `after_result`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `after_script`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `after_success`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `before_deploy`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `before_install`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `before_script`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `branches`
+**Expected format:** Key value mapping.
+
+#### `branches.except`
+**Expected format:** List of strings or regular expressions; or a single string or regular expression.
+
+#### `branches.only`
+**Expected format:** List of strings or regular expressions; or a single string or regular expression.
+
+#### `bundler_args`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default).**
+
+**Expected format:** String.
+
+#### `cache`
+**Expected format:** Key value mapping.
+
+#### `cache.apt`
+**Expected format:** Boolean value.
+
+#### `cache.bundler`
+**Expected format:** Boolean value.
+
+#### `cache.directories`
+**Expected format:** List of strings; or a single string.
+
+#### `compiler`
+**This setting is only relevant if [`language`](#language) is set to `c` or `cpp`.**
+
+**Expected format:** List of strings; or a single string.
+
+#### `compiler[]`
+Value has to be `gcc` (default) or `clang`; or one of the known aliases: `g++` for `gcc` or `clang++` for `clang`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `composer_args`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+**Expected format:** String.
+
+#### `deploy`
+**Expected format:** List of key value mappings; or a single key value mapping.
+
+#### `deploy[]`
+**Expected format:** Key value mapping.
+
+#### `deploy[].*`
+**Expected format:** String.
+
+#### `deploy[].edge`
+**This setting is experimental and might be removed!**
+
+**Expected format:** Boolean value.
+
+#### `deploy[].on`
+**Expected format:** Key value mapping.
+
+#### `deploy[].on.all_branches`
+**Expected format:** Boolean value.
+
+#### `deploy[].on.branch`
+**Expected format:** String.
+
+#### `deploy[].on.condition`
+**Expected format:** String.
+
+#### `deploy[].on.jdk`
+**This setting is only relevant if [`language`](#language) is set to `clojure`, `groovy`, `java`, `ruby` (default), `scala` or `android`.**
+
+`jdk` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.node`
+`node` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.perl`
+**This setting is only relevant if [`language`](#language) is set to `perl`.**
+
+`perl` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.php`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+`php` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.python`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+`python` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.repo`
+**Expected format:** String.
+
+#### `deploy[].on.ruby`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+`ruby` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.rvm`
+Alias for [`deploy[].on.ruby`](#deployonruby).
+
+#### `deploy[].on.scala`
+`scala` version to use.
+
+**Expected format:** String.
+
+#### `deploy[].on.tags`
+**Expected format:** Boolean value.
+
+#### `deploy[].provider`
+**This setting is required!**
+
+**Expected format:** String.
+
+#### `env`
+**Expected format:** Key value mapping.
+
+#### `env.global`
+**Expected format:** List of strings or encrypted strings; or a single string or encrypted string.
+
+#### `env.matrix`
+**Expected format:** List of strings or encrypted strings; or a single string or encrypted string.
+
+#### `gemfile`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+Gemfile(s) to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `ghc`
+**This setting is only relevant if [`language`](#language) is set to `haskell`.**
+
+List of `ghc` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `git`
+**Expected format:** Key value mapping.
+
+#### `git.depth`
+**Expected format:** Integer value.
+
+#### `git.strategy`
+Value has to be `clone` or `tarball`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `git.submodules`
+**Expected format:** Boolean value.
+
+#### `go`
+**This setting is only relevant if [`language`](#language) is set to `go`.**
+
+List of `go` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `gobuild_args`
+**This setting is only relevant if [`language`](#language) is set to `go`.**
+
+**Expected format:** String.
+
+#### `install`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `jdk`
+**This setting is only relevant if [`language`](#language) is set to `clojure`, `groovy`, `java`, `ruby` (default), `scala` or `android`.**
+
+List of `jdk` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `language`
+**This setting is required!**
+
+Value has to be `c`, `cpp`, `clojure`, `erlang`, `go`, `groovy`, `haskell`, `java`, `node_js`, `objective-c`, `ruby` (default), `python`, `perl`, `php`, `scala` or `android`; or one of the known aliases: `jvm` for `java`, `javascript` for `node_js`, `node` for `node_js`, `nodejs` for `node_js`, `golang` for `go`, `objective_c` for `objective-c`, `obj_c` for `objective-c`, `objc` for `objective-c`, `c++` for `cpp`, `node.js` for `node_js` or `obj-c` for `objective-c`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `lein`
+**This setting is only relevant if [`language`](#language) is set to `clojure`.**
+
+List of `lein` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `matrix`
+**Expected format:** Key value mapping.
+
+#### `matrix.allow_failures`
+**Expected format:** List of key value mappings; or a single key value mapping.
+
+#### `matrix.allow_failures[]`
+**Expected format:** Key value mapping.
+
+#### `matrix.allow_failures[].compiler`
+**This setting is only relevant if [`language`](#language) is set to `c` or `cpp`.**
+
+Value has to be `gcc` (default) or `clang`; or one of the known aliases: `g++` for `gcc` or `clang++` for `clang`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].env`
+**Expected format:** String or encrypted string.
+
+#### `matrix.allow_failures[].gemfile`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+Gemfile to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].ghc`
+**This setting is only relevant if [`language`](#language) is set to `haskell`.**
+
+`ghc` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].go`
+**This setting is only relevant if [`language`](#language) is set to `go`.**
+
+`go` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].jdk`
+**This setting is only relevant if [`language`](#language) is set to `clojure`, `groovy`, `java`, `ruby` (default), `scala` or `android`.**
+
+`jdk` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].lein`
+**This setting is only relevant if [`language`](#language) is set to `clojure`.**
+
+`lein` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].node`
+Alias for [`matrix.allow_failures[].node_js`](#matrixallow_failuresnode_js).
+
+#### `matrix.allow_failures[].node_js`
+**This setting is only relevant if [`language`](#language) is set to `node_js`.**
+
+`node_js` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].os`
+Value has to be `linux` (default) or `osx`; or one of the known aliases: `ubuntu` for `linux`, `mac` for `osx` or `macos` for `osx`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].otp`
+Alias for [`matrix.allow_failures[].otp_release`](#matrixallow_failuresotp_release).
+
+#### `matrix.allow_failures[].otp_release`
+**This setting is only relevant if [`language`](#language) is set to `erlang`.**
+
+`otp_release` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].perl`
+**This setting is only relevant if [`language`](#language) is set to `perl`.**
+
+`perl` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].php`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+`php` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].python`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+`python` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].ruby`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+`ruby` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].rvm`
+Alias for [`matrix.allow_failures[].ruby`](#matrixallow_failuresruby).
+
+#### `matrix.allow_failures[].xcode_scheme`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_scheme` version to use.
+
+**Expected format:** String.
+
+#### `matrix.allow_failures[].xcode_sdk`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_sdk` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude`
+**Expected format:** List of key value mappings; or a single key value mapping.
+
+#### `matrix.exclude[]`
+**Expected format:** Key value mapping.
+
+#### `matrix.exclude[].compiler`
+**This setting is only relevant if [`language`](#language) is set to `c` or `cpp`.**
+
+Value has to be `gcc` (default) or `clang`; or one of the known aliases: `g++` for `gcc` or `clang++` for `clang`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].env`
+**Expected format:** String or encrypted string.
+
+#### `matrix.exclude[].gemfile`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+Gemfile to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].ghc`
+**This setting is only relevant if [`language`](#language) is set to `haskell`.**
+
+`ghc` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].go`
+**This setting is only relevant if [`language`](#language) is set to `go`.**
+
+`go` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].jdk`
+**This setting is only relevant if [`language`](#language) is set to `clojure`, `groovy`, `java`, `ruby` (default), `scala` or `android`.**
+
+`jdk` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].lein`
+**This setting is only relevant if [`language`](#language) is set to `clojure`.**
+
+`lein` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].node`
+Alias for [`matrix.exclude[].node_js`](#matrixexcludenode_js).
+
+#### `matrix.exclude[].node_js`
+**This setting is only relevant if [`language`](#language) is set to `node_js`.**
+
+`node_js` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].os`
+Value has to be `linux` (default) or `osx`; or one of the known aliases: `ubuntu` for `linux`, `mac` for `osx` or `macos` for `osx`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].otp`
+Alias for [`matrix.exclude[].otp_release`](#matrixexcludeotp_release).
+
+#### `matrix.exclude[].otp_release`
+**This setting is only relevant if [`language`](#language) is set to `erlang`.**
+
+`otp_release` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].perl`
+**This setting is only relevant if [`language`](#language) is set to `perl`.**
+
+`perl` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].php`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+`php` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].python`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+`python` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].ruby`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+`ruby` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].rvm`
+Alias for [`matrix.exclude[].ruby`](#matrixexcluderuby).
+
+#### `matrix.exclude[].xcode_scheme`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_scheme` version to use.
+
+**Expected format:** String.
+
+#### `matrix.exclude[].xcode_sdk`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_sdk` version to use.
+
+**Expected format:** String.
+
+#### `matrix.fast_finish`
+**Expected format:** Boolean value.
+
+#### `matrix.include`
+**Expected format:** List of key value mappings; or a single key value mapping.
+
+#### `matrix.include[]`
+**Expected format:** Key value mapping.
+
+#### `matrix.include[].compiler`
+**This setting is only relevant if [`language`](#language) is set to `c` or `cpp`.**
+
+Value has to be `gcc` (default) or `clang`; or one of the known aliases: `g++` for `gcc` or `clang++` for `clang`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.include[].env`
+**Expected format:** String or encrypted string.
+
+#### `matrix.include[].gemfile`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+Gemfile to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].ghc`
+**This setting is only relevant if [`language`](#language) is set to `haskell`.**
+
+`ghc` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].go`
+**This setting is only relevant if [`language`](#language) is set to `go`.**
+
+`go` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].jdk`
+**This setting is only relevant if [`language`](#language) is set to `clojure`, `groovy`, `java`, `ruby` (default), `scala` or `android`.**
+
+`jdk` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].lein`
+**This setting is only relevant if [`language`](#language) is set to `clojure`.**
+
+`lein` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].node`
+Alias for [`matrix.include[].node_js`](#matrixincludenode_js).
+
+#### `matrix.include[].node_js`
+**This setting is only relevant if [`language`](#language) is set to `node_js`.**
+
+`node_js` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].os`
+Value has to be `linux` (default) or `osx`; or one of the known aliases: `ubuntu` for `linux`, `mac` for `osx` or `macos` for `osx`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `matrix.include[].otp`
+Alias for [`matrix.include[].otp_release`](#matrixincludeotp_release).
+
+#### `matrix.include[].otp_release`
+**This setting is only relevant if [`language`](#language) is set to `erlang`.**
+
+`otp_release` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].perl`
+**This setting is only relevant if [`language`](#language) is set to `perl`.**
+
+`perl` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].php`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+`php` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].python`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+`python` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].ruby`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+`ruby` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].rvm`
+Alias for [`matrix.include[].ruby`](#matrixincluderuby).
+
+#### `matrix.include[].xcode_scheme`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_scheme` version to use.
+
+**Expected format:** String.
+
+#### `matrix.include[].xcode_sdk`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+`xcode_sdk` version to use.
+
+**Expected format:** String.
+
+#### `node`
+Alias for [`node_js`](#node_js).
+
+#### `node_js`
+**This setting is only relevant if [`language`](#language) is set to `node_js`.**
+
+List of `node_js` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications`
+**Expected format:** Key value mapping.
+
+#### `notifications.campfire`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.campfire.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.campfire.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.campfire.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.campfire.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.campfire.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.campfire.rooms`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.campfire.template`
+Strings will be interpolated. Available variables: `%{repository_slug}`, `%{repository_name}`, `%{repository}`, `%{build_number}`, `%{branch}`, `%{commit}`, `%{author}`, `%{message}`, `%{duration}`, `%{compare_url}`, `%{build_url}`.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.email`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.email.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.email.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.email.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.email.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.email.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.email.recipients`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.flowdoc`
+**Expected format:** Key value mapping, or string, encrypted string, or boolean value.
+
+#### `notifications.flowdoc.api_token`
+**Expected format:** String or encrypted string.
+
+#### `notifications.flowdoc.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.flowdoc.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.flowdoc.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.flowdoc.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.flowdoc.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.hipchat`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.hipchat.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.hipchat.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.hipchat.format`
+Value has to be `html` or `text`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.hipchat.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.hipchat.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.hipchat.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.hipchat.rooms`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.hipchat.template`
+Strings will be interpolated. Available variables: `%{repository_slug}`, `%{repository_name}`, `%{repository}`, `%{build_number}`, `%{branch}`, `%{commit}`, `%{author}`, `%{message}`, `%{duration}`, `%{compare_url}`, `%{build_url}`.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.irc`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.irc.channel_key`
+**Expected format:** String or encrypted string.
+
+#### `notifications.irc.channels`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.irc.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.irc.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.irc.nick`
+**Expected format:** String or encrypted string.
+
+#### `notifications.irc.nickserv_password`
+**Expected format:** String or encrypted string.
+
+#### `notifications.irc.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.irc.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.irc.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.irc.password`
+**Expected format:** String or encrypted string.
+
+#### `notifications.irc.skip_join`
+**Expected format:** Boolean value.
+
+#### `notifications.irc.template`
+Strings will be interpolated. Available variables: `%{repository_slug}`, `%{repository_name}`, `%{repository}`, `%{build_number}`, `%{branch}`, `%{commit}`, `%{author}`, `%{message}`, `%{duration}`, `%{compare_url}`, `%{build_url}`.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.irc.use_notice`
+**Expected format:** Boolean value.
+
+#### `notifications.slack`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.slack.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.slack.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.slack.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.slack.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.slack.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.slack.rooms`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.slack.template`
+Strings will be interpolated. Available variables: `%{repository_slug}`, `%{repository_name}`, `%{repository}`, `%{build_number}`, `%{branch}`, `%{commit}`, `%{author}`, `%{message}`, `%{duration}`, `%{compare_url}`, `%{build_url}`.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.sqwiggle`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.sqwiggle.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.sqwiggle.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.sqwiggle.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.sqwiggle.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.sqwiggle.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.sqwiggle.rooms`
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.sqwiggle.template`
+Strings will be interpolated. Available variables: `%{repository_slug}`, `%{repository_name}`, `%{repository}`, `%{build_number}`, `%{branch}`, `%{commit}`, `%{author}`, `%{message}`, `%{duration}`, `%{compare_url}`, `%{build_url}`.
+
+**Expected format:** List of strings; or a single string.
+
+#### `notifications.webhook`
+Alias for [`notifications.webhooks`](#notificationswebhooks).
+
+#### `notifications.webhooks`
+**Expected format:** Key value mapping, or list of strings or encrypted strings, or boolean value.
+
+#### `notifications.webhooks.disabled`
+**Expected format:** Boolean value.
+
+#### `notifications.webhooks.enabled`
+**Expected format:** Boolean value.
+
+#### `notifications.webhooks.on_failure`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.webhooks.on_start`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.webhooks.on_success`
+Value has to be `always`, `never` or `change`. Setting is case sensitive.
+
+**Expected format:** String.
+
+#### `notifications.webhooks.urls`
+**Expected format:** List of strings; or a single string.
+
+#### `npm_args`
+**This setting is only relevant if [`language`](#language) is set to `node_js`.**
+
+**Expected format:** String.
+
+#### `os`
+**Expected format:** List of strings; or a single string.
+
+#### `os[]`
+Value has to be `linux` (default) or `osx`; or one of the known aliases: `ubuntu` for `linux`, `mac` for `osx` or `macos` for `osx`. Setting is not case sensitive.
+
+**Expected format:** String.
+
+#### `osx_image`
+**This setting is experimental and might be removed!**
+
+`osx_image` version to use.
+
+**Expected format:** String.
+
+#### `otp`
+Alias for [`otp_release`](#otp_release).
+
+#### `otp_release`
+**This setting is only relevant if [`language`](#language) is set to `erlang`.**
+
+List of `otp_release` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `perl`
+**This setting is only relevant if [`language`](#language) is set to `perl`.**
+
+List of `perl` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `php`
+**This setting is only relevant if [`language`](#language) is set to `php`.**
+
+List of `php` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `python`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+List of `python` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `ruby`
+**This setting is only relevant if [`language`](#language) is set to `ruby` (default) or `objective-c`.**
+
+List of `ruby` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `rvm`
+Alias for [`ruby`](#ruby).
+
+#### `script`
+Commands that will be run on the VM.
+
+**Expected format:** List of strings; or a single string.
+
+#### `sdk_components`
+**This setting is only relevant if [`language`](#language) is set to `android`.**
+
+**Expected format:** List of strings; or a single string.
+
+#### `services`
+List of `services` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `source_key`
+**Expected format:** String or encrypted string.
+
+#### `virtual_env`
+Alias for [`virtualenv`](#virtualenv).
+
+#### `virtualenv`
+**This setting is only relevant if [`language`](#language) is set to `python`.**
+
+**Expected format:** Key value mapping.
+
+#### `virtualenv.system_site_packages`
+**Expected format:** Boolean value.
+
+#### `xcode_project`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+**Expected format:** String.
+
+#### `xcode_scheme`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+List of `xcode_scheme` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `xcode_sdk`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+List of `xcode_sdk` versions to use.
+
+**Expected format:** List of strings; or a single string.
+
+#### `xcode_workspace`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+**Expected format:** String.
+
+#### `xctool_args`
+**This setting is only relevant if [`language`](#language) is set to `objective-c`.**
+
+**Expected format:** String.
+
+## Generating the Specification
+
+This file is generated. You currently update it by running `play/spec.rb`.