.config/coc/extensions/node_modules/coc-prettier/node_modules/postcss-media-query-parser/README.md

   1 # postcss-media-query-parser\r
   2 \r
   3 [![NPM version](http://img.shields.io/npm/v/postcss-media-query-parser.svg)](https://www.npmjs.com/package/postcss-media-query-parser) [![Build Status](https://travis-ci.org/dryoma/postcss-media-query-parser.svg?branch=master)](https://travis-ci.org/dryoma/postcss-media-query-parser)\r
   4 \r
   5 Media query parser with very simple traversing functionality.\r
   6 \r
   7 ## Installation and usage\r
   8 \r
   9 First install it via NPM:\r
  10 \r
  11 ```\r
  12 npm install postcss-media-query-parser\r
  13 ```\r
  14 \r
  15 Then in your Node.js application:\r
  16 \r
  17 ```js\r
  18 import mediaParser from "postcss-media-query-parser";\r
  19 \r
  20 const mediaQueryString = "(max-width: 100px), not print";\r
  21 const result = mediaParser(mediaQueryString);\r
  22 ```\r
  23 \r
  24 The `result` will be this object:\r
  25 \r
  26 ```js\r
  27 {\r
  28   type: 'media-query-list',\r
  29   value: '(max-width: 100px), not print',\r
  30   after: '',\r
  31   before: '',\r
  32   sourceIndex: 0,\r
  33 \r
  34   // the first media query\r
  35   nodes: [{\r
  36     type: 'media-query',\r
  37     value: '(max-width: 100px)',\r
  38     before: '',\r
  39     after: '',\r
  40     sourceIndex: 0,\r
  41     parent: <link to parent 'media-query-list' node>,\r
  42     nodes: [{\r
  43       type: 'media-feature-expression',\r
  44       value: '(max-width: 100px)',\r
  45       before: '',\r
  46       after: '',\r
  47       sourceIndex: 0,\r
  48       parent: <link to parent 'media-query' node>,\r
  49       nodes: [{\r
  50         type: 'media-feature',\r
  51         value: 'max-width',\r
  52         before: '',\r
  53         after: '',\r
  54         sourceIndex: 1,\r
  55         parent: <link to parent 'media-feature-expression' node>,\r
  56       }, {\r
  57         type: 'colon',\r
  58         value: ':',\r
  59         before: '',\r
  60         after: ' ',\r
  61         sourceIndex: 10,\r
  62         parent: <link to parent 'media-feature-expression' node>,\r
  63       }, {\r
  64         type: 'value',\r
  65         value: '100px',\r
  66         before: ' ',\r
  67         after: '',\r
  68         sourceIndex: 12,\r
  69         parent: <link to parent 'media-feature-expression' node>,\r
  70       }]\r
  71     }]\r
  72   },\r
  73   // the second media query\r
  74   {\r
  75     type: 'media-query',\r
  76     value: 'not print',\r
  77     before: ' ',\r
  78     after: '',\r
  79     sourceIndex: 20,\r
  80     parent: <link to parent 'media-query-list' node>,\r
  81     nodes: [{\r
  82       type: 'keyword',\r
  83       value: 'not',\r
  84       before: ' ',\r
  85       after: ' ',\r
  86       sourceIndex: 20,\r
  87       parent: <link to parent 'media-query' node>,\r
  88     }, {\r
  89       type: 'media-type',\r
  90       value: 'print',\r
  91       before: ' ',\r
  92       after: '',\r
  93       sourceIndex: 24,\r
  94       parent: <link to parent 'media-query' node>,\r
  95     }]\r
  96   }]\r
  97 }\r
  98 ```\r
  99 \r
 100 One of the likely sources of a string to parse would be traversing [a PostCSS container node](http://api.postcss.org/Root.html) and getting the `params` property of nodes with the name of "atRule":\r
 101 \r
 102 ```js\r
 103 import postcss from "postcss";\r
 104 import mediaParser from "postcss-media-query-parser";\r
 105 \r
 106 const root = postcss.parse(<contents>);\r
 107 // ... or any other way to get sucn container\r
 108 \r
 109 root.walkAtRules("media", (atRule) => {\r
 110   const mediaParsed = mediaParser(atRule.params);\r
 111   // Do something with "mediaParsed" object\r
 112 });\r
 113 ```\r
 114 \r
 115 ## Nodes\r
 116 \r
 117 Node is a very generic item in terms of this parser. It's is pretty much everything that ends up in the parsed result. Each node has these properties:\r
 118 \r
 119 * `type`: the type of the node (see below);\r
 120 * `value`: the node's value stripped of trailing whitespaces;\r
 121 * `sourceIndex`: 0-based index of the node start relative to the source start (excluding trailing whitespaces);\r
 122 * `before`: a string that contain a whitespace between the node start and the previous node end/source start;\r
 123 * `after`: a string that contain a whitespace between the node end and the next node start/source end;\r
 124 * `parent`: a link to this node's parent node (a container).\r
 125 \r
 126 A node can have one of these types (according to [the 2012 CSS3 standard](https://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/)):\r
 127 \r
 128 * `media-query-list`: that is the root level node of the parsing result. A [container](#containers); its children can have types of `url` and `media-query`.\r
 129 * `url`: if a source is taken from a CSS `@import` rule, it will have a `url(...)` function call. The value of such node will be `url(http://uri-address)`, it is to be parsed separately.\r
 130 * `media-query`: such nodes correspond to each media query in a comma separated list. In the exapmle above there are two. Nodes of this type are [containers](#containers).\r
 131 * `media-type`: `screen`, `tv` and other media types.\r
 132 * `keyword`: `only`, `not` or `and` keyword.\r
 133 * `media-feature-expression`: an expression in parentheses that checks for a condition of a particular media feature. The value would be like this: `(max-width: 1000px)`. Such nodes are [containers](#containers). They always have a `media-feature` child node, but might not have a `value` child node (like in `screen and (color)`).\r
 134 * `media-feature`: a media feature, e.g. `max-width`.\r
 135 * `colon`: present if a media feature expression has a colon (e.g. `(min-width: 1000px)`, compared to `(color)`).\r
 136 * `value`: a media feature expression value, e.g. `100px` in `(max-width: 1000px)`.\r
 137 \r
 138 ### Parsing details\r
 139 \r
 140 postcss-media-query-parser allows for cases of some **non-standard syntaxes** and tries its best to work them around. For example, in a media query from a code with SCSS syntax:\r
 141 \r
 142 ```scss\r
 143 @media #{$media-type} and ( #{"max-width" + ": 10px"} ) { ... }\r
 144 ```\r
 145 \r
 146 `#{$media-type}` will be the node of type `media-type`, alghough `$media-type`'s value can be `only screen`. And inside `media-feature-expression` there will only be a `media-feature` type node with the value of `#{"max-width" + ": 10px"}` (this example doesn't make much sense, it's for demo purpose).\r
 147 \r
 148 But the result of parsing **malformed media queries** (such as with incorrect amount of closing parens, curly braces, etc.) can be unexpected. For exapmle, parsing:\r
 149 \r
 150 ```scss\r
 151 @media ((min-width: -100px)\r
 152 ```\r
 153 \r
 154 would return a media query list with the single `media-query` node that has no child nodes.\r
 155 \r
 156 ## Containers\r
 157 \r
 158 Containers are [nodes](#nodes) that have other nodes as children. Container nodes have an additional property `nodes` which is an array of their child nodes. And also these methods:\r
 159 \r
 160 * `each(callback)` - traverses the direct child nodes of a container, calling `callback` function for each of them. Returns `false` if traversing has stopped by means of `callback` returning `false`, and `true` otherwise.\r
 161 * `walk([filter, ]callback)` - traverses ALL descendant nodes of a container, calling `callback` function for each of them. Returns `false` if traversing has stopped by means of `callback` returning `false`, and `true` otherwise.\r
 162 \r
 163 In both cases `callback` takes these parameters:\r
 164 \r
 165 - `node` - the current node (one of the container's descendats, that the callback has been called against).\r
 166 - `i` - 0-based index of the `node` in an array of its parent's children.\r
 167 - `nodes` - array of child nodes of `node`'s parent.\r
 168 \r
 169 If `callback` returns `false`, the traversing stops.\r
 170 \r
 171 ## License\r
 172 \r
 173 MIT\r