Skip to content

COMPATIBILITY.md

Latest commit

 

History

History
271 lines (208 loc) · 7.17 KB

COMPATIBILITY.md

File metadata and controls

271 lines (208 loc) · 7.17 KB

mojo-yaml v0.1.0 Lite - Compatibility Report

Generated: 2026-01-14
Status: Reader-only, ~80% common YAML coverage

Quick Summary

✅ WORKS: Simple configs, nested structures, basic types, comments
⚠️ LIMITATIONS: Quote multi-word strings, quote version numbers, no flow-style
❌ NOT SUPPORTED: Flow-style [...], empty values, anchors/aliases

Real-World Fixture Testing Results

✅ Works Perfectly

yaml_lite_example.yaml

  • Status: ✅ WORKS after quoting multi-word strings and version numbers
  • Patterns used: Nested mappings, sequences, inline list-mappings, all scalar types
  • Size: 740 bytes

pre_commit.yaml

  • Status: ✅ WORKS with flow-style arrays converted to block style
  • Patterns used: Nested list-mappings (repos → hooks), inline continuation
  • Note: Original has ['markdown'] which needs conversion to block style

yaml_lite_working.yaml

  • Status: ✅ WORKS perfectly as designed
  • Patterns used: All supported features without workarounds
  • Purpose: Reference implementation for v0.1.0

⚠️ Requires Workarounds

docker_compose.yaml

  • Issue: Empty value handling (e.g., db-data: at end)
  • Status: Needs explicit null or value

❌ Not Compatible

pre_commit.yaml

  • Issue: exclude_types: ['markdown'] fails at line 3
  • Reason: Flow-style arrays not supported
  • Workaround: Rewrite as block style: 
    exclude_types:
  - markdown

github_workflow.yaml

  • Issue: os: [ubuntu-latest, macos-latest] fails at line 14
  • Reason: Flow-style arrays not supported
  • Workaround: Rewrite as block style: 
    os:
  - ubuntu-latest
  - macos-latest

Feature Compatibility Matrix

Feature Support Notes
Basic Mappings ✅ Full key: value
Nested Mappings ✅ Full Any depth
Sequences ✅ Full - item block style only
Nested Sequences ✅ Full Any depth, block style
Inline List-Mapping ✅ Full - name: value with continuation
Comments ✅ Full # comment anywhere
Integers ✅ Full 42, -17
Floats ✅ Full 3.14, 1.5e10 (single decimal point)
Booleans ✅ Full true, false, yes, no
Null ✅ Full null, ~
Quoted Strings ✅ Full "text", 'text'
Unquoted Strings ⚠️ Single word only Must quote multi-word strings
Version Numbers ⚠️ Must quote version: "0.1.0" not version: 0.1.0
Empty Values ❌ Not supported key: causes errors
Flow-Style Arrays ❌ Not supported [1, 2, 3] fails
Flow-Style Mappings ❌ Not supported {key: value} fails
Anchors ❌ Not supported &anchor not recognized
Aliases ❌ Not supported *reference not recognized
Multi-Document ❌ Not supported --- separator ignored
Literal Blocks ❌ Not supported `
Folded Blocks ❌ Not supported > not recognized
Tags ❌ Not supported !tag not recognized
Directives ❌ Not supported %TAG, %YAML ignored

Common Issues and Workarounds

1. Version Numbers Fail to Parse

Problem:

version: 0.1.0  # ❌ FAILS - parsed as 0.1 then .0 is invalid

Solution:

version: "0.1.0"  # ✅ WORKS - quote version numbers

2. Flow-Style Arrays Not Supported

Problem:

platforms: [linux, macos, windows]  # ❌ FAILS

Solution:

platforms:  # ✅ WORKS - use block style
  - linux
  - macos
  - windows

3. Empty Values Cause Errors

Problem:

database:  # ❌ FAILS - empty value
  host:    # ❌ FAILS - empty value

Solution:

database: null  # ✅ WORKS - explicit null
  host: ""      # ✅ WORKS - empty string

4. Multi-Word Strings Must Be Quoted

Problem:

description: YAML parser for Mojo  # ❌ FAILS - spaces in unquoted string
message: Hello world  # ❌ FAILS

Solution:

description: "YAML parser for Mojo"  # ✅ WORKS
message: "Hello world"  # ✅ WORKS

Note: Single-word unquoted strings work fine:

name: localhost  # ✅ WORKS
path: /usr/bin  # ✅ WORKS

5. Complex Strings Need Quotes

Problem:

message: Hello, world!  # ❌ FAILS - comma
url: http://example.com?foo=bar  # ⚠️ MAY FAIL - special chars

Solution:

message: "Hello, world!"  # ✅ WORKS
url: "http://example.com?foo=bar&baz=qux"  # ✅ WORKS

---

## What Actually Works

This parser excels at:

1. **Configuration Files** - Simple block-style configs with nested structures
2. **Data Exports** - Lists of records with consistent structure
3. **Simple Documents** - Basic key-value stores with comments

### Working Example

```yaml
# Application configuration
app:
  name: "my-app"
  version: "1.0.0"  # Must quote version numbers!
  debug: true
  timeout: 30.5

database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password_file: /secrets/db_pass

servers:
  - name: web1
    ip: 192.168.1.10
    roles:
      - web
      - api
  - name: web2
    ip: 192.168.1.11
    roles:
      - web
      - api

features:
  - authentication
  - caching
  - logging

Known Limitations

Parser Limitations

  1. Number Parsing: Version numbers like 1.2.3 treated as 1.2 + invalid .3
  2. Empty Values: key: with no value causes parse errors
  3. Flow Style: No support for [...] or {...} syntax

Lexer Limitations

  1. String Detection: Unquoted strings with special characters may fail
  2. Multi-Decimal Numbers: Only one decimal point allowed in floats

By Design (Not Planned)

  1. Anchors/Aliases: &anchor and *reference - requires reference tracking
  2. Multi-Document: --- separators - would need document array return
  3. Literal/Folded: | and > - complex multiline string handling
  4. Complex Keys: ? complex\n: value - rarely used in practice

Testing Recommendations

When testing if your YAML file is compatible:

  1. Quote multi-word strings: Change description: YAML parser to description: "YAML parser"
  2. Quote version numbers: Change version: 1.0.0 to version: "1.0.0"
  3. Use block style: Convert [a, b] to list format
  4. Make values explicit: Change key: to key: null or key: ""
  5. Quote special characters: If string contains :[]{}#|>, quote it

Future Improvements (v0.2.0+)

Planned enhancements based on real-world needs:

  • Support version number patterns (multiple dots)
  • Handle empty values gracefully
  • Flow-style array support [1, 2, 3]
  • Better error messages with fix suggestions

Not planned:

  • ❌ Anchors/aliases (complex, rarely needed)
  • ❌ Multi-document (niche use case)
  • ❌ Literal/folded blocks (marginal utility)

Summary

Best for: Simple, block-style YAML configs and data files
Works great with: Quoted strings, explicit values, nested structures
Avoid: Flow style, empty values, unquoted multi-word strings, anchors
Remember: When in doubt, quote your strings!