Version 4

Description

While working on tooling that deals with pre-parsing component files, I'm seeing props and values on the AST that are not present in the spec. While the AST is fairly understandable and deterministic, it emits nodes with numeric types and one-character properties whose meaning isn't immediately clear. Would be nice to have an updated document which one can look up a code, and check its properties.

[ceremcem]

I have an idea: Maybe we can create a reverse engineering tool for that purpose:

Input

doc = # AST documentation
  v: 
    alias: "Version"
    type: "Integer"

  t: 
    alias: "Template"
    type: "7 or Array"
    
  e: 
    alias: "Element"
    type: "String"
    
  f:
    alias: "Fragment"
    type: "Array"

sample = '''
  <p>hello <b>shiny</b> world</p>
  '''

Output

Generator

JS Bin Demo

alias = (name) -> 
  # returns Ractive AST key 
  for key, exp of doc when name is exp.alias
    return key 
  throw new Error "No such alias found: #{name}"
  
examine = (ast) -> 
  if typeof! ast is \Object 
    for key, value of ast 
      switch key
      | alias \Version  => \ok
      | alias \Template =>
        if typeof! value is \Array 
          # this is the root template 
          examine value 
        else 
          \ok 
      | alias \Element => \ok
      | alias \Fragment => examine value
      |_ => throw new Error "What is #{key}?"

  else if typeof! ast is \Array 
    for ast 
      examine .. 
      
  else if typeof! ast is \String 
    \ok 
  else 
    throw new Error "We don't expect this: #{ast}"
  'All documented'
  
check = (ast) -> 
  try
    examine ast 
  catch error 
    error 

new Ractive do 
  el: 'body'
  template: '''
    <p>Result: {{check(p(sample))}}</p>
    
    <h2>Documentation</h2>
    <ul>
    {{#each doc}}
      <ul>{{@key}}: {{.["alias"]}}
        <ul>
          <li>Type: {{.["type"]}}</li>
        </ul>
      </ul>
    {{/each}}
    </ul>
    <h2>Debug</h2>
    <pre>{{JSON.stringify(p(sample), null, 2)}}</pre>

    '''
  data: {doc, check, sample, p: Ractive.parse}