travis-conditions 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a86f16c9d6f3b178157b4244a5e6647777d9ac00
-  data.tar.gz: 50b3bf851a1946ad0a0f2dc51e768b5dfc8ea496
+  metadata.gz: 511bf5af9e9ff4684b09b23bdfb45c19cf16974b
+  data.tar.gz: 18653ac8eb0886b3c797c25fe7af4eba1f13c6b8
 SHA512:
-  metadata.gz: c95e11b39596ad69528635ce1d761ac17ccc9104fbffd7fe3a1b2dc43f830e991275c67d65ea09e5584f24f8b0da61c4c9a455709cce16055d07ceaa8437fd9a
-  data.tar.gz: a74367ce97002a1ec80e5c1de63547ac2d5a21d12e6af07a0910fe3d4bbddc17b8ef0d510bb08749c9ce286ba234217ba732dc29cba22f45bdf220a2101fd8f0
+  metadata.gz: ab283b0406a10b95be7d9ab0ef7c7fd052cd6db37944bd592493e4990983534370354e7de29091465c97f59d244e3dd6703fb133e8dae30ed07167a5c4438188
+  data.tar.gz: f98a63783c44fc3ddb29772d2e10290c9367fcb1b0bf63c71d31171c16f6156c3df92a92aacaee8ed1639b1d57bf1a5b6d96521683d6c21a76780f0ab5498763

data/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## [Unreleased]
+
+## v1.0.0-dev.1
+
+Major parser rewrite, removing Parslet
+
+### Added
+- Variables `os`, `dist`, `group`, `sudo`, `language`, `commit_message`
+- Boolean aliases `&&` (alias to `AND`), `||` (alias to `OR`), `!` (alias to `NOT`)
+- Operator aliases `==` (alias to `=`), `~=` (alias to `=~`)
+- Predicates `true`, `false`
+- Line continuation using `\`
+- Negated `IN` and `IS` operators:
+    ```
+    NOT branch IN (master, dev) # this worked, and continues to work
+    branch NOT IN (master, dev) # this did not work, and now does
+
+    NOT env(foo) IS present # this worked, and continues to work
+    env(foo) IS NOT present # this did not work, and now does
+    env(foo) IS blank       # btw this is the same
+    ```
+- Better boolean language parsing of:
+    ```
+    # evaluate individual terms (no operator)
+    true
+    false
+    env(FOO)
+
+    # compare values
+    1 = 1
+
+    # compare function calls
+    env(FOO) = env(BAR)
+
+    # compare function calls to variables
+    env(FOO) = type
+
+    # nested function calls
+    env(env(FOO))
+
+    # function calls in lists
+    repo IN (env(ONE), env(OTHER))
+
+    # parenthesis
+    (tag =~ ^v) AND (branch = master)
+    ```
+
+### Changed
+- All values continue to be treated as strings, except `true` and `false`
+  which are now treated like Ruby's types.
+- Individual terms such as `true` or `env(FOO)` will now evaluate according
+  to Ruby's concept of truthiness: everything is true except for `false`
+  and absent values.
+- Var names and unquoted strings starting with a dollar char `$` now raise
+  a parse error. Bash code is not available. Quoted strings still can start
+  with a dollar char.
+
+## v0.2.0
+### Changed
+- Reraise Parselet::ParseFailed as Travis::Conditions::ParseError
+
+## v0.1.0
+Initial release

data/Gemfile.lock

@@ -25,4 +25,4 @@ DEPENDENCIES
   rspec
 
 BUNDLED WITH
-   1.15.4
+   1.16.1

data/NOTES.md

@@ -0,0 +1,107 @@
+### New variables:
+
+* `os`
+* `dist`
+* `group`
+* `sudo`
+* `language`
+* `commit_message`
+
+### New predicates:
+
+* `true`
+* `false`
+
+It is now possible to use `fork IS true` instead of `fork = true`. These mean
+the same, and there's no reason to not use `=`, but we have seen a lot of
+people expect these to work.
+
+### New operator aliases:
+
+For the same reason we've added the following operator aliases:
+
+* `==` (alias to `=`)
+* `~=` (alias to `=~`)
+* `&&` (alias to `AND`)
+* `||` (alias to `OR`)
+* `!` (alias to `NOT`)
+
+### Negated `IN` and `IS` operators:
+
+The operators `IN` and `IS` could not be negated the way users expected.
+We allowed the following:
+
+```
+NOT branch IN (master, dev) # worked, and continues to work
+branch NOT IN (master, dev) # did not work, and now does
+
+NOT env(foo) IS present # worked, and continues to work
+env(foo) IS NOT present # did not work, and now does
+env(foo) IS blank       # (btw this is the same)
+```
+
+### Line continuation (multiline conditions):
+
+We were surprised to see users to expect line continuation using `\` to work,
+as it does, for example, in Ruby or Python. We liked the idea, so we allowed
+this:
+
+```
+if: env(PRIOR_VERSION) IS present AND \
+    env(PRIOR_VERSION) != env(RELEASE_VERSION) AND \
+    branch = master AND \
+    type = push
+```
+
+Using YAML multiline strings:
+
+```
+if: |
+  env(PRIOR_VERSION) IS present AND \
+  env(PRIOR_VERSION) != env(RELEASE_VERSION) AND \
+  branch = master AND \
+  type = push
+```
+
+### Proper boolean language parsing:
+
+Previously it was not possible to:
+
+* evaluate individual terms (such as `true`)
+* compare, say, a value (string) to another, one environment variable (function call) to another, or compare function calls to variables (such as `type` or `branch`).
+* nest function calls, or include things other than strings in lists.
+* enclose statements in parenthesis the way one would expect in some places (even though not documented).
+
+The following statements now parse and evaluate as expected:
+
+```
+# individual terms
+true
+false
+
+# compare values
+1 = 1
+true != false
+
+# compare function calls
+env(FOO) = env(BAR)
+
+# compare function calls to variables
+env(FOO) = type
+
+# nested function calls
+env(env(FOO))
+
+# function calls in lists
+repo IN (env(ONE), env(OTHER))
+
+# parenthesis
+(tag =~ ^v) AND (branch = master)
+```
+
+### No bash code, please
+
+Variable names and unquoted strings starting with a dollar char `$` now raise a
+parse error. Bash code is not available, and these expressions will never evaluate
+as the user expects, so it is better to raise an error instead. Quoted strings
+still can start with a dollar char.

data/README.md

@@ -1,33 +1,233 @@
-# Boolean language for conditional builds, stages, jobs (draft)
+# Boolean language for conditional builds, stages, jobs
+
+## Usage
+
+```ruby
+str  = 'branch IN (foo, bar) AND env(baz) =~ ^baz- OR tag IS present'
+data = { branch: 'foo', env: { baz: 'baz-1' }, tag: 'v.1.0.0' }
+Travis::Conditions.parse(str, data)
+# => true
+```
+
+## EBNF
+
+See [this file](https://github.com/travis-ci/travis-conditions/blob/master/lib/travis/conditions/v1/parser.rb#L6-L47) for the EBNF.
+
+## CLI
+
+With the gem installed you can use the command `travis-conditions` in order to
+test your conditions locally. For example:
+
+```
+$ travis-conditions "branch = foo" --data '{"branch": "foo"}'
+true
+
+$ echo '{"branch": "foo"}' | travis-conditions "branch = foo"
+true
+```
+
+The given `data` hash can include known attributes (such as branch, tag, repo)
+and an `env` key that can either hold a hash, or an array of strings:
+
+```
+$ travis-conditions "env(foo) = bar" --data '{"env": {"foo": "bar"}}'
+true
+$ travis-conditions "env(foo) = bar" --data '{"env": ["foo=bar"]}'
+true
+```
+
+## Conditions
+
+Conditions can be used to filter out, and reject builds, stages, and jobs by
+specifying conditions in your build configuration (your `.travis.yml` file).
+See [Conditional Builds, Stages, and Jobs](/user/conditional-builds-stages-jobs)
+for details.
+
+### Examples
+
+```
+# require the branch name to be master (note for PRs this is the base branch name)
+branch = master
+
+# require the tag name to match a regular expression (enclose in slashes for
+# more complicated expressions)
+tag =~ ^v1
+tag =~ /^(v1|v2)/
+
+# require the event type to be either `push` or `pull_request`
+type IN (push, pull_request)
+
+# require the branch name to not be one of several names
+branch NOT IN (master, dev)
+
+# require the sender login name to match a given name (use quotes for strings
+# that contain spaces or special characters)
+sender == my_account
+sender != "deploy bot"
+
+# exclude forks
+fork == false
+
+# match the commit message
+commit_message !~ /no-deploy/
+
+# match the os
+os == linux
+```
+
+### Integration
+
+Conditions are being parsed using [this library](https://github.com/travis-ci/travis-conditions)
+by the component that accepts your build request, and generates your build,
+stages, and jobs.
+
+The following known attributes are available:
+
+* `type` (the current event type, known event types are: `push`, `pull_request`, `api`, `cron`)
+* `repo` (the current repository slug `owner_name/name`)
+* `branch` (the current branch name; for pull requests: the base branch name)
+* `tag` (the current tag name)
+* `commit_message` (the current commit message)
+* `sender` (the event sender's login name)
+* `fork` (`true` or `false` depending if the repository is a fork)
+* `head_repo` (for pull requests: the head repository slug `owner_name/name`)
+* `head_branch` (for pull requests: the head repository branch name)
+* `os` (the operating system)
+* `language` (the build language)
+* `sudo` (sudo access)
+* `dist` (the distribution)
+* `group` (the image group)
+
+Also, environment variables from your build configuration (`.travis.yml`) and
+repository settings are available, and can be matched using `env(FOO)`, see
+below.
+
+Note that this means conditions do not have access to the build environment,
+and they are *not* evaluted in Bash. Bash variables or subprocesses can *not*
+be evaluated.
+
+Variable names and unquoted strings starting with a dollar char `$` raise a
+parse error, causing the build request to be rejected. Quoted strings still can
+start with a dollar char, so if you definitely need a string to start with a
+dollar char you can enclose it in quotes.
+
+### Specification
+
+The following expressions are parsed and evaluated as expected:
+
+```
+# individual terms
+true
+false
+
+# compare values
+1 = 1
+true != false
+
+# compare function calls
+env(FOO) = env(BAR)
+
+# compare function calls to attributes
+env(FOO) = type
+
+# nested function calls
+env(env(FOO))
+
+# function calls in lists
+repo IN (env(ONE), env(OTHER))
+
+# parenthesis
+(tag =~ ^v) AND (branch = master)
+```
+
+All keywords (such as `AND`, `OR`, `NOT`, `IN`, `IS`, attribute and functions names) are case-insensitive.
+
+The only functions currently is:
+
+```
+# (the value of the environment variable `FOO`)
+env(FOO)
+```
+
+The function `env` currently supports environment variables that are given in
+your build configuration (e.g. on `env` or `env.global`), and environment
+variables specified in your repository settings.  Note that there is no
+function `env.global` or similar. Instead all environment variables are
+available through `env`.
+
+#### Values
+
+Values are strings that are given without quotes, not containing any whitespace or special characters, or single or double quoted strings:
 
 ```
-(NOT [term] OR [term]) AND [term]
+"a word"
+'a word'
+a_word
 ```
 
-A term can be can be:
+#### Equality and inequality
 
-#### Equality
+This matches a string literally:
 
 ```
 branch = master
+sender != "my bot"
 env(foo) = bar
+"bar" = env("foo")
 ```
 
-#### Match
+#### Regular expressions
+
+This matches a string using a regular expression:
 
 ```
+# for simple expressions, not ending in a closing parenthesis:
 branch =~ ^master$
 env(foo) =~ ^bar$
+
+# if an expression needs to include whitespace, or end in a parenthesis wrap it with slashes:
+branch =~ /(master|foo)/
 ```
 
-#### Include
+Usually parenthesis are not required (e.g. the above list of alternatives could also be written as just `master|foo`). If you do need to end a regular expression with a parenthesis, or if it contains whitespace, then the whole expression needs to be wrapped in `/` slashes.
+
+#### Lists
+
+This matches against a list (array) of values:
 
 ```
 branch IN (master, dev)
 env(foo) IN (bar, baz)
 ```
 
-#### Presence
+Note that commas are required to separate values.
+
+Values that include whitespace or special characters should be quoted:
+
+```
+env(foo) IN ("bar baz", "buz bum")
+```
+
+The operator `IN` can be negated as follows:
+
+```
+# these are the same
+NOT branch IN (master, dev)
+branch NOT IN (master, dev)
+```
+
+#### Predicates
+
+Known predicates are:
+
+```
+present
+blank
+true
+false
+```
+
+This requires a value to be present or missing:
 
 ```
 branch IS present
@@ -36,11 +236,59 @@ env(foo) IS present
 env(foo) IS blank
 ```
 
-## Usage
+The operator `IS` can be negated as follows:
 
-```ruby
-str  = 'branch IN (foo, bar) AND env(baz) =~ ^baz- OR tag IS present'
-data = { branch: 'foo', env: { baz: 'baz-1' }, tag: 'v.1.0.0' }
-Travis::Conditions.apply(str, data)
-# => true
+```
+# these are all the same
+env(foo) IS NOT present
+NOT env(foo) IS present
+env(foo) IS blank
+```
+
+Note that the operator `IS` is intended to work with the well known predicates `present` and `blank`. It is not the same as `=`, and expressions like the following do *not* work:
+
+```
+# this does not work
+branch IS "master"
+
+# instead use =
+branch = "master"
+```
+
+However, `IS` can also be used to match against the boolean values `true` and `false` (this has been included after we found many users to expect this to work):
+
+```
+branch IS true
+branch = true # this is the same
+```
+
+#### Aliases
+
+The following aliases are in place:
+
+* `!` is an alias to `NOT`
+* `&&` is an alias to `AND`
+* `||` is an alias to `OR`
+* `==` is an alias to `=`
+* `~=` is an alias to `=~`
+
+#### Line continuation (multiline conditions):
+
+We were surprised to see users to expect line continuation using `\` to work, as it does, for example, in Ruby or Python. We liked the idea, so we allowed the following:
+
+```
+if: env(PRIOR_VERSION) IS present AND \
+    env(PRIOR_VERSION) != env(RELEASE_VERSION) AND \
+    branch = master AND \
+    type = push
+```
+
+Using YAML multiline strings:
+
+```
+if: |
+  env(PRIOR_VERSION) IS present AND \
+  env(PRIOR_VERSION) != env(RELEASE_VERSION) AND \
+  branch = master AND \
+  type = push
 ```