0
# Parser & Processor
1

2
Core parser function and processor class for parsing and transforming CSS selectors with both synchronous and asynchronous processing capabilities.
3

4
## Capabilities
5

6
### Parser Function
7

8
Main entry point that creates processor instances with optional transform functions and default options.
9

10
```javascript { .api }
11
/**
12
 * Creates a new processor instance
13
 * @param transform - Optional transform function to process the AST
14
 * @param options - Default options for all processor calls
15
 * @returns Processor instance
16
 */
17
function parser(transform?: ProcessorFn, options?: Options): Processor;
18

19
type ProcessorFn = (root: Root) => any;
20
type AsyncProcessor = (root: Root) => Promise<any>;
21
type SyncProcessor = (root: Root) => any;
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const parser = require('postcss-selector-parser');
28

29
// Basic processor
30
const processor = parser();
31

32
// With transform function
33
const transform = selectors => {
34
    selectors.walkUniversals(selector => {
35
        selector.remove();
36
    });
37
};
38
const processor = parser(transform);
39

40
// With options
41
const processor = parser(null, { lossless: false });
42
```
43

44
### Processor Class
45

46
Handles parsing, transformation, and output generation for CSS selectors.
47

48
```javascript { .api }
49
/**
50
 * Processor for parsing and transforming CSS selectors
51
 */
52
interface Processor<TransformType = never, SyncSelectorsType extends Selectors | never = Selectors> {
53
  /** The parsed AST root node */
54
  res: Root;
55
  /** String representation of the result */
56
  result: string;
57
  
58
  /**
59
   * Parse selectors to AST asynchronously
60
   * @param selectors - CSS selector string or PostCSS rule
61
   * @param options - Parsing options
62
   * @returns Promise resolving to Root AST node
63
   */
64
  ast(selectors: Selectors, options?: Options): Promise<Root>;
65
  
66
  /**
67
   * Parse selectors to AST synchronously
68
   * @param selectors - CSS selector string or PostCSS rule
69
   * @param options - Parsing options
70
   * @returns Root AST node
71
   */
72
  astSync(selectors: Selectors, options?: Options): Root;
73
  
74
  /**
75
   * Transform selectors asynchronously
76
   * @param selectors - CSS selector string or PostCSS rule
77
   * @param options - Processing options
78
   * @returns Promise resolving to transform result
79
   */
80
  transform(selectors: Selectors, options?: Options): Promise<any>;
81
  
82
  /**
83
   * Transform selectors synchronously
84
   * @param selectors - CSS selector string or PostCSS rule
85
   * @param options - Processing options
86
   * @returns Transform result
87
   */
88
  transformSync(selectors: Selectors, options?: Options): any;
89
  
90
  /**
91
   * Process selectors to string asynchronously
92
   * @param selectors - CSS selector string or PostCSS rule
93
   * @param options - Processing options
94
   * @returns Promise resolving to processed selector string
95
   */
96
  process(selectors: Selectors, options?: Options): Promise<string>;
97
  
98
  /**
99
   * Process selectors to string synchronously
100
   * @param selectors - CSS selector string or PostCSS rule
101
   * @param options - Processing options
102
   * @returns Processed selector string
103
   */
104
  processSync(selectors: Selectors, options?: Options): string;
105
}
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
const parser = require('postcss-selector-parser');
112
const processor = parser();
113

114
// Async processing
115
const ast = await processor.ast('.class1, .class2');
116
const result = await processor.process('.class1, .class2');
117

118
// Sync processing
119
const ast = processor.astSync('.class1, .class2');
120
const result = processor.processSync('.class1, .class2');
121

122
// With options
123
const normalized = processor.processSync('h1 , h2 , h3', { lossless: false });
124
// Result: "h1,h2,h3"
125
```
126

127
### Processing Options
128

129
Configuration options for parsing and processing selectors.
130

131
```javascript { .api }
132
interface Options {
133
  /**
134
   * Preserve whitespace when true (default: true)
135
   */
136
  lossless?: boolean;
137
  
138
  /**
139
   * When true and a PostCSS Rule is passed, set the result back onto the rule (default: true)
140
   */
141
  updateSelector?: boolean;
142
}
143

144
type Selectors = string | PostCSSRuleNode;
145

146
interface PostCSSRuleNode {
147
  selector: string;
148
  error(message: string, options?: ErrorOptions): Error;
149
}
150

151
interface ErrorOptions {
152
  plugin?: string;
153
  word?: string;
154
  index?: number;
155
}
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
// Lossless parsing (preserves formatting)
162
const result1 = processor.processSync('h1 , h2 , h3', { lossless: true });
163
// Result: "h1 , h2 , h3"
164

165
// Non-lossless parsing (normalizes whitespace)
166
const result2 = processor.processSync('h1 , h2 , h3', { lossless: false });
167
// Result: "h1,h2,h3"
168

169
// Working with PostCSS rule
170
const rule = { selector: '.class1, .class2' };
171
processor.processSync(rule, { updateSelector: true });
172
// rule.selector is updated with the processed result
173
```
174

175
### Parser Class
176

177
Internal parser class used for low-level parsing operations.
178

179
```javascript { .api }
180
/**
181
 * Internal parser class for CSS selector parsing
182
 */
183
interface Parser {
184
  input: ParserOptions;
185
  lossy: boolean;
186
  position: number;
187
  root: Root;
188
  selectors: string;
189
  current: Selector;
190
  
191
  /**
192
   * Creates new parser instance
193
   * @param input - Parser configuration
194
   */
195
  constructor(input: ParserOptions): Parser;
196
  
197
  /**
198
   * Raises a parsing error with context
199
   * @param message - Error message
200
   * @param options - Error options
201
   */
202
  error(message: string, options?: ErrorOptions): void;
203
}
204

205
interface ParserOptions {
206
  css: string;
207
  error: (message: string, options: ErrorOptions) => Error;
208
  options: Options;
209
}
210
```