Brunobkr/llama.cpp_AlgMor24_github

1# Abstract Syntax Tree (AST)2 3## Overview4 5The AST represents CSS as a tree structure where each node has a specific type and properties. All nodes share common properties and have type-specific properties.6 7## Common Properties8 9All AST nodes have these properties:10 11### `type`12 13The node type as a string. See [Node Types](#node-types) for all possible values.14 15### `position` (optional)16 17Position information for the node in the source code:18 19```typescript20{21  start: { line: number; column: number };22  end: { line: number; column: number };23  source?: string;24}25```26 27### `parent` (optional)28 29Reference to the parent node in the AST.30 31## Node Types32 33### `stylesheet`34 35The root node representing an entire CSS document.36 37**Properties:**38- `stylesheet.source` (optional): Source file path39- `stylesheet.rules`: Array of top-level rules40- `stylesheet.parsingErrors` (optional): Array of parse errors when `silent` option is used41 42**Example:**43```json44{45  "type": "stylesheet",46  "stylesheet": {47    "rules": [48      // ... other nodes49    ]50  }51}52```53 54### `rule`55 56A CSS rule with selectors and declarations.57 58**Properties:**59- `selectors`: Array of CSS selectors as strings60- `declarations`: Array of declarations and comments61 62**Example:**63```json64{65  "type": "rule",66  "selectors": ["body", "html"],67  "declarations": [68    {69      "type": "declaration",70      "property": "color",71      "value": "red"72    }73  ]74}75```76 77### `declaration`78 79A CSS property declaration.80 81**Properties:**82- `property`: The CSS property name83- `value`: The CSS property value as a string84 85**Example:**86```json87{88  "type": "declaration",89  "property": "background-color",90  "value": "#ffffff"91}92```93 94### `comment`95 96A CSS comment.97 98**Properties:**99- `comment`: The comment text (without `/*` and `*/`)100 101**Example:**102```json103{104  "type": "comment",105  "comment": " This is a comment "106}107```108 109### `media`110 111A `@media` rule.112 113**Properties:**114- `media`: The media query string115- `rules`: Array of rules within the media block116 117**Example:**118```json119{120  "type": "media",121  "media": "screen and (max-width: 768px)",122  "rules": [123    // ... nested rules124  ]125}126```127 128### `keyframes`129 130A `@keyframes` rule.131 132**Properties:**133- `name`: The keyframes name134- `vendor` (optional): Vendor prefix (e.g., "-webkit-")135- `keyframes`: Array of keyframe rules and comments136 137**Example:**138```json139{140  "type": "keyframes",141  "name": "fade",142  "keyframes": [143    {144      "type": "keyframe",145      "values": ["from"],146      "declarations": [147        {148          "type": "declaration",149          "property": "opacity",150          "value": "0"151        }152      ]153    }154  ]155}156```157 158### `keyframe`159 160A keyframe within a `@keyframes` rule.161 162**Properties:**163- `values`: Array of keyframe selectors (e.g., `["from"]`, `["to"]`, `["50%"]`)164- `declarations`: Array of declarations and comments165 166### `import`167 168An `@import` rule.169 170**Properties:**171- `import`: The import string (URL or media query)172 173**Example:**174```json175{176  "type": "import",177  "import": "url('styles.css')"178}179```180 181### `charset`182 183A `@charset` rule.184 185**Properties:**186- `charset`: The character encoding187 188**Example:**189```json190{191  "type": "charset",192  "charset": "utf-8"193}194```195 196### `namespace`197 198A `@namespace` rule.199 200**Properties:**201- `namespace`: The namespace declaration202 203**Example:**204```json205{206  "type": "namespace",207  "namespace": "url(http://www.w3.org/1999/xhtml)"208}209```210 211### `supports`212 213A `@supports` rule.214 215**Properties:**216- `supports`: The supports condition217- `rules`: Array of rules within the supports block218 219**Example:**220```json221{222  "type": "supports",223  "supports": "(display: grid)",224  "rules": [225    // ... nested rules226  ]227}228```229 230### `document`231 232A `@document` rule.233 234**Properties:**235- `document`: The document condition236- `vendor` (optional): Vendor prefix237- `rules`: Array of rules within the document block238 239### `page`240 241A `@page` rule.242 243**Properties:**244- `selectors`: Array of page selectors245- `declarations`: Array of declarations and comments246 247### `font-face`248 249A `@font-face` rule.250 251**Properties:**252- `declarations`: Array of font declarations and comments253 254### `host`255 256A `:host` rule.257 258**Properties:**259- `rules`: Array of rules within the host block260 261### `container`262 263A `@container` rule.264 265**Properties:**266- `container`: The container query267- `rules`: Array of rules within the container block268 269### `layer`270 271A `@layer` rule.272 273**Properties:**274- `layer`: The layer name275- `rules` (optional): Array of rules within the layer block276 277### `custom-media`278 279A `@custom-media` rule.280 281**Properties:**282- `name`: The custom media query name283- `media`: The media query definition284 285### `starting-style`286 287A `@starting-style` rule.288 289**Properties:**290- `rules`: Array of rules within the starting-style block291 292## Type Hierarchy293 294The AST nodes are organized in the following hierarchy:295 296- `CssStylesheetAST` - Root node297- `CssAtRuleAST` - Union of all at-rule and rule nodes298- `CssAllNodesAST` - Union of all possible node types299 300## Working with the AST301 302### Traversing Nodes303 304```typescript305import { parse, CssStylesheetAST } from '@adobe/css-tools';306 307const ast: CssStylesheetAST = parse('body { color: red; }');308 309// Access top-level rules310ast.stylesheet.rules.forEach(rule => {311  if (rule.type === 'rule') {312    console.log('Selectors:', rule.selectors);313    rule.declarations.forEach(decl => {314      if (decl.type === 'declaration') {315        console.log(`${decl.property}: ${decl.value}`);316      }317    });318  }319});320```321 322### Modifying Nodes323 324```typescript325// Add a new declaration326const newDecl = {327  type: 'declaration' as const,328  property: 'font-size',329  value: '16px'330};331 332// Find a rule and add the declaration333ast.stylesheet.rules.forEach(rule => {334  if (rule.type === 'rule' && rule.selectors.includes('body')) {335    rule.declarations.push(newDecl);336  }337});338```339 340### Error Handling341 342When parsing with the `silent` option, errors are collected in the AST:343 344```typescript345const ast = parse('invalid css {', { silent: true });346 347if (ast.stylesheet.parsingErrors) {348  ast.stylesheet.parsingErrors.forEach(error => {349    console.error('Parse error:', error.message);350  });351}352```353 354## Position Information355 356Position information is available on most nodes and includes:357 358- `start.line` and `start.column`: Beginning of the node359- `end.line` and `end.column`: End of the node  360- `source`: Source file path (if provided during parsing)361 362This is useful for:363- Error reporting364- Source mapping365- Code analysis tools366- IDE integration367