Merge pull request #140.

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

This fixes stylelint in conjunction with stylelint/stylelint#3284

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "integration/stylelint"]
+	path = integration/stylelint
+	url = https://github.com/chriseppstein/stylelint.git
+  branch = selector-parser-4.0

.npmignore

@@ -0,0 +1 @@
+integration/*/

.travis.yml

@@ -3,11 +3,20 @@ sudo: false
 language: node_js
 matrix:
   include:
+    - node_js: '10'
+      env: INTEGRATION=false
     - node_js: '8'
-    - node_js: '7'
+      env: INTEGRATION=true
     - node_js: '6'
-    - node_js: '5'
-    - node_js: '4'
-
+      env: INTEGRATION=false
+install:
+  - npm install -g npm@latest
+  - npm ci
+script:
+  - npm test
+  - ./integration_test.sh
+cache:
+  directories:
+    - ~/.npm
 after_success:
   - './node_modules/.bin/nyc report --reporter=text-lcov | ./node_modules/.bin/coveralls'

API.md

@@ -78,6 +78,18 @@ Arguments:
 
 * `props (object)`: The new node's properties.
 
+Notes:
+* **Descendant Combinators** The value of descendant combinators created by the
+  parser always just a single space (`" "`). For descendant selectors with no
+  comments, additional space is now stored in `node.spaces.before`. Depending
+  on the location of comments, additional spaces may be stored in
+  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
+* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
+  named combinators like `/deep/` and `/for/` are parsed as combinators. The
+  `node.value` is name after being unescaped and normalized as lowercase. The
+  original value for the combinator name is stored in `node.raws.value`.
+
+
 ### `parser.comment([props])`
 
 Creates a new comment.
@@ -275,6 +287,17 @@ String(cloned);
 // => #search
 ```
 
+### `node.isAtPosition(line, column)`
+
+Return a `boolean` indicating whether this node includes the character at the
+position of the given line and column. Returns `undefined` if the nodes lack
+sufficient source metadata to determine the position.
+
+Arguments:
+
+* `line`: 1-index based line number relative to the start of the selector.
+* `column`: 1-index based column number relative to the start of the selector.
+
 ### `node.spaces`
 
 Extra whitespaces around the node will be moved into `node.spaces.before` and
@@ -285,15 +308,13 @@ no semantic meaning:
       h1     ,     h2   {}
 ```
 
-However, *combinating* spaces will form a `combinator` node:
+For descendent selectors, the value is always a single space.
 
 ```css
 h1        h2 {}
 ```
 
-A `combinator` node may only have the `spaces` property set if the combinator
-value is a non-whitespace character, such as `+`, `~` or `>`. Otherwise, the
-combinator value will contain all of the spaces between selectors.
+Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.
 
 ### `node.source`
 
@@ -369,6 +390,19 @@ Arguments:
 
 * `index`: The index of the node to return.
 
+### `container.atPosition(line, column)`
+
+Returns the node at the source position `index`.
+
+```js
+selector.at(0) === selector.first;
+selector.at(0) === selector.nodes[0];
+```
+
+Arguments:
+
+* `index`: The index of the node to return.
+
 ### `container.index(node)`
 
 Return the index of the node within its container.
@@ -551,7 +585,7 @@ support parsing of legacy CSS hacks.
 
 ## Selector nodes
 
-A selector node represents a single compound selector. For example, this
+A selector node represents a single complex selector. For example, this
 selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
 It has no special functionality of its own.
 

CHANGELOG.md

@@ -1,3 +1,235 @@
+# 5.0.0-rc.0
+
+This release has **BREAKING CHANGES** that were required to fix regressions
+in 4.0.0 and to make the Combinator Node API consistent for all combinator
+types. Please read carefully.
+
+## Summary of Changes
+
+* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
+* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
+* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
+* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
+* The minimum supported version of Node is now `v6.0.0`.
+
+### Changes to the Descendent Combinator
+
+In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.
+
+* `.a   .b`: Extra spaces are now stored as space before.
+  - Old & Busted:
+    - `combinator.value === "   "`
+  - New hotness:
+    - `combinator.value === " " && combinator.spaces.before === "  "`
+* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
+  - Old & Busted:
+    - `combinator.value === "   "`
+    - `combinator.raws.value === "   /*comment/"`
+  - New hotness:
+    - `combinator.value === " "`
+    - `combinator.spaces.after === "  "`
+    - `combinator.raws.spaces.after === "  /*comment*/"`
+* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
+  - Old & Busted:
+    - `combinator.value === "\n"`
+    - `combinator.raws.value === undefined`
+  - New hotness:
+    - `combinator.value === " "`
+    - `combinator.raws.value === "\n"`
+
+### Support for "Named Combinators"
+
+Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.
+
+Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.
+
+Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.
+
+* `.a /for/ .b` is parsed as a combinator.
+  - Old & Busted:
+    - `root.nodes[0].nodes[1].type === "tag"`
+    - `root.nodes[0].nodes[1].value === "/"`
+  - New hotness:
+    - `root.nodes[0].nodes[1].type === "combinator"`
+    - `root.nodes[0].nodes[1].value === "/for/"`
+* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
+  - Old & Busted:
+    - `root.nodes[0].nodes[2].type === "tag"`
+    - `root.nodes[0].nodes[2].value === "F\\6fR"`
+  - New hotness:
+    - `root.nodes[0].nodes[1].type === "combinator"`
+    - `root.nodes[0].nodes[1].value === "/for/"`
+    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`
+
+### Source position checks and lookups
+
+A new API was added to look up a node based on the source location.
+
+```js
+const selectorParser = require("postcss-selector-parser");
+// You can find the most specific node for any given character
+let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
+combinator.toString() === " > ";
+// You can check if a node includes a specific character
+// Whitespace surrounding the node that is owned by that node
+// is included in the check.
+[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
+// => [false, true, true, true, false]
+```
+
+# 4.0.0
+
+This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.
+
+* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
+  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
+  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
+  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
+  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
+  The original escape sequences for these values can be found in the corresponding property name
+  in `node.raws`. Where possible, deprecation warnings were added, but the nature
+  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
+  that most users are neither expecting nor handling escape sequences in their use of this library,
+  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
+  now update their code to remove the escape handling and let us do it for them.
+
+* **Mutating values with escapes** - When you make an update to a node property that has escape handling
+  The value is assumed to be unescaped, and any special characters are escaped automatically and
+  the corresponding `raws` value is immediately updated. This can result in changes to the original
+  escape format. Where the exact value of the escape sequence is important there are methods that
+  allow both values to be set in conjunction. There are a number of new convenience methods for
+  manipulating values that involve escapes, especially for attributes values where the quote mark
+  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
+  write-up on these changes.
+
+
+**Upgrade/API Example**
+
+In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
+to create a CSS file that did not parse correctly when some types of values
+were in use.
+
+```js
+const selectorParser = require("postcss-selector-parser");
+let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
+attr.value; // => "a-value"
+attr.toString(); // => [id=a-value]
+// Add quotes to an attribute's value.
+// All these values have to be set by the caller to be consistent:
+// no internal consistency is maintained.
+attr.raws.unquoted = attr.value
+attr.value = "'" + attr.value + "'";
+attr.value; // => "'a-value'"
+attr.quoted = true;
+attr.toString();  // => "[id='a-value']"
+```
+
+In `4.0` there is a convenient API for setting and mutating values
+that may need escaping. Especially for attributes.
+
+```js
+const selectorParser = require("postcss-selector-parser");
+
+// The constructor requires you specify the exact escape sequence
+let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
+className.toString(); // => '.illegal\\ class\\ name'
+
+// So it's better to set the value as a property
+className = selectorParser.className();
+// Most properties that deal with identifiers work like this
+className.value = "escape for me";
+className.value; // => 'escape for me'
+className.toString(); // => '.escape\\ for\\ me'
+
+// emoji and all non-ascii are escaped to ensure it works in every css file.
+className.value = "😱🦄😍";
+className.value; // => '😱🦄😍'
+className.toString(); // => '.\\1F631\\1F984\\1F60D'
+
+// you can control the escape sequence if you want, or do bad bad things
+className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
+className.value; // => "xxxx"
+className.toString(); // => ".yyyy"
+
+// Pass a value directly through to the css output without escaping it. 
+className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
+className.value; // => "$REPLACE_ME$"
+className.toString(); // => ".$REPLACE_ME$"
+
+// The biggest changes are to the Attribute class
+// passing quoteMark explicitly is required to avoid a deprecation warning.
+let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
+attr.toString(); // => "[id=a-value]"
+// Get the value with quotes on it and any necessary escapes.
+// This is the same as reading attr.value in 3.x.
+attr.getQuotedValue(); // => "a-value";
+attr.quoteMark; // => null
+
+// Add quotes to an attribute's value.
+attr.quoteMark = "'"; // This is all that's required.
+attr.toString(); // => "[id='a-value']"
+attr.quoted; // => true
+// The value is still the same, only the quotes have changed.
+attr.value; // => a-value
+attr.getQuotedValue(); // => "'a-value'";
+
+// deprecated assignment, no warning because there's no escapes
+attr.value = "new-value";
+// no quote mark is needed so it is removed
+attr.getQuotedValue(); // => "new-value";
+
+// deprecated assignment, 
+attr.value = "\"a 'single quoted' value\"";
+// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
+attr.getQuotedValue(); // => '"a \'single quoted\' value"';
+// quote mark inferred from first and last characters.
+attr.quoteMark; // => '"'
+
+// setValue takes options to make manipulating the value simple.
+attr.setValue('foo', {smart: true});
+// foo doesn't require any escapes or quotes.
+attr.toString(); // => '[id=foo]'
+attr.quoteMark; // => null 
+
+// An explicit quote mark can be specified
+attr.setValue('foo', {quoteMark: '"'});
+attr.toString(); // => '[id="foo"]'
+
+// preserves quote mark by default
+attr.setValue('bar');
+attr.toString(); // => '[id="bar"]'
+attr.quoteMark = null;
+attr.toString(); // => '[id=bar]'
+
+// with no arguments, it preserves quote mark even when it's not a great idea
+attr.setValue('a value \n that should be quoted');
+attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'
+
+// smart preservation with a specified default
+attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
+// => "[id='a value \\A  that should be quoted']"
+attr.quoteMark = '"';
+// => '[id="a value \\A  that should be quoted"]'
+
+// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
+attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
+// => '[id="this should be quoted"]'
+
+// picks single quotes because the value has double quotes
+attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
+// => "[id='a "double quoted" value']"
+
+// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
+attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
+attr.value; // => "xxxx"
+attr.toString(); // => "[id=the password is 42]"
+
+// Pass a value directly through to the css output without escaping it. 
+attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
+attr.value; // => "$REPLACEMENT$"
+attr.toString(); // => "[id=$REPLACEMENT$]"
+```
+
 # 3.1.2
 
 * Fix: Removed dot-prop dependency since it's no longer written in es5.

integration_test.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+if [[ $INTEGRATION == "false" ]]; then
+  exit 0;
+fi
+git submodule update --init --recursive
+npm link
+cd integration/stylelint
+npm link postcss-selector-parser
+npm install
+NODE_VERSION=`node -e "console.log(process.version.replace(/v(\d).*/,function(m){return m[1]}))"`
+CI="tests $NODE_VERSION"
+npm run jest -- --maxWorkers=2 --testPathIgnorePatterns lib/__tests__/standalone-cache.test.js || exit $?