|
9 | 9 | YAML loader. It has also been converted to JSON in a file next to this one.
|
10 | 10 | The YAML file has lots of helpful comments. The JSON (of course) does not.
|
11 | 11 |
|
12 |
| - The purpose of this grammar-as-yaml file is to: |
13 |
| - * Make the spec clearer and more precise to people implementing YAML parsers |
14 |
| - * To generate 100% correct YAML parsers in most programming languages |
| 12 | + The purpose of this grammar-as-yaml file is to make the spec clearer and more |
| 13 | + precise to people implementing YAML parsers. The grammar in the YAML 1.2 |
| 14 | + specification is difficult to understand and in a few cases ambiguous or |
| 15 | + incorrect. |
15 | 16 |
|
16 | 17 | This grammar mirrors the 1.2 spec faithfully, but tries to express the rules
|
17 | 18 | in a more concrete and programatic fashion. Some of the rules that are more
|
18 |
| - difficult to understand have a comment section before them. Each rule |
19 |
| - definition is preceded by the original YAML 1.2 spec rule text, formatted as |
20 |
| - a comment. |
| 19 | + difficult to understand, ambiguous or incorrect, have a comment section |
| 20 | + before them. Each rule definition is preceded by the original YAML 1.2 spec |
| 21 | + rule text, formatted as a comment. |
| 22 | +
|
| 23 | + The YAML Reference Parser project ( which can be found at |
| 24 | + https://github.com/yaml/yaml-reference-parser/ ) uses this file to generate |
| 25 | + 100% correct YAML parsers in many programming languages. |
21 | 26 |
|
22 | 27 | - |2+
|
23 | 28 |
|
|
339 | 344 |
|
340 | 345 | m - relative indentation columns or 'auto-detect()'
|
341 | 346 | t - trailing whitespace indicator
|
342 |
| -
|
343 |
| - This production (162) is misleading. It claims to be called with 2 arguments, |
344 |
| - `m` and `t`, but it is not called with any arguments. In reality it is |
345 |
| - supposed to *create* 2 state variables `m` and `t`. To auto-detect `m` it |
346 |
| - will need the value of `n` (the current indentation). |
347 |
| -
|
348 |
| - The spec rule 162 should actually be: |
349 |
| -
|
350 |
| - c-b-block-header(n) ::= |
351 |
| - ( ( c-indentation-indicator |
352 |
| - c-chomping-indicator ) |
353 |
| - | ( c-chomping-indicator |
354 |
| - c-indentation-indicator(n) ) ) |
355 |
| - s-b-comment |
356 |
| -
|
357 |
| - The original from the spec is left intact below, but the generated YAML uses |
358 |
| - the version above. |
359 |
| -'163': | |
360 |
| - This production should receive the `n` indentation variable. It creates an |
361 |
| - `m` state variable that indicates the amount of relative indentation for a |
362 |
| - literal or folded scalar. |
363 |
| -
|
364 |
| - It should actually be: |
365 |
| -
|
366 |
| - c-indentation-indicator(n) ::= |
367 |
| - ( ns-dec-digit => m = ns-dec-digit - x:30 ) |
368 |
| - ( <empty> => m = auto-detect(n) ) |
369 |
| -'164': | |
370 |
| - This production should not receive any arguments. It creates a variable that |
371 |
| - indicates how trailing whitespace should be interpreted. |
372 |
| -
|
373 |
| - It should actually be: |
374 |
| -
|
375 |
| - c-chomping-indicator ::= |
376 |
| - ( '-' => t = strip ) |
377 |
| - ( '+' => t = keep ) |
378 |
| - ( <empty> => t = clip ) |
379 |
| -'170': | |
380 |
| - This production needs to call c-b-block-header with the variable `n`. |
381 |
| -
|
382 |
| - It should actually be: |
383 |
| -
|
384 |
| - c-l+literal(n) ::= |
385 |
| - '|' c-b-block-header(n) |
386 |
| - l-literal-content(n+m,t) |
387 |
| -'174': | |
388 |
| - This production needs to call c-b-block-header with the variable `n`. |
389 |
| -
|
390 |
| - It should actually be: |
391 |
| -
|
392 |
| - c-l+folded(n) ::= |
393 |
| - '>' c-b-block-header(n) |
394 |
| - l-folded-content(n+m,t) |
395 | 347 | '183': |
|
396 | 348 | The <auto-detect-indent> rule is a "special" rule that finds the new level of
|
397 | 349 | indentation and returns the number of columns. The level must be greater than
|
398 | 350 | 0. It does not consume the indentation.
|
399 |
| -'200': | |
400 |
| - This production tries to match collection properties and a collection. It has |
401 |
| - a problem where it consumes a property that might be for the key of the first |
402 |
| - pair of a mapping. To make sure the property applies to the collection itself |
403 |
| - it should check for a newline after the property (in the same scope as the |
404 |
| - property check). |
405 |
| -
|
406 |
| - In other words, it would be more clearly written as this: |
407 |
| -
|
408 |
| - s-l+block-collection(n,c) ::= |
409 |
| - ( s-separate(n+1,c) |
410 |
| - c-ns-properties(n+1,c) s-l-comments )? |
411 |
| - s-l-comments |
412 |
| - ( l+block-sequence(seq-spaces(n,c)) |
413 |
| - | l+block-mapping(n) ) |
414 | 351 | '207': |
|
415 | 352 | The l-bare-document is the topmost rule for parsing a document.
|
416 | 353 |
|
417 | 354 | The <excluding_c-forbidden_content> says that in every other rule you must
|
418 | 355 | check that c-forbidden does not occur.
|
419 | 356 |
|
420 | 357 | This is a bad design choice for a formal grammar.
|
421 |
| -'211': | |
422 |
| - This production has a bug in the rule quantifers for l-document-prefix. It |
423 |
| - should only be tried once (not multiple times). |
424 |
| -
|
425 |
| - It should actually be: |
426 |
| -
|
427 |
| - l-yaml-stream ::= |
428 |
| - l-document-prefix l-any-document? |
429 |
| - ( ( l-document-suffix+ l-document-prefix |
430 |
| - l-any-document? ) |
431 |
| - | ( l-document-prefix l-explicit-document? ) )* |
0 commit comments