Documentation Source Text

#!/bin/tclsh
#
# Run this TCL script to generate syntax bubble diagrams from
# text descriptions.
#
# This version generates a pure HTML table based version with
# no graphics, all in one file named "all-text.html".  It may
# be useful to people wanting text search or screen reader 
# support.

# Graphs:
#
set all_graphs {
  sql-stmt-list {
    toploop {optx sql-stmt} ;
  }
  sql-stmt {
    line
      {opt EXPLAIN {opt QUERY PLAN}}
      {or
         alter-table-stmt
         analyze-stmt
         attach-stmt
         begin-stmt
         commit-stmt
         create-index-stmt
         create-table-stmt
         create-trigger-stmt
         create-view-stmt
         create-virtual-table-stmt
         delete-stmt
         delete-stmt-limited
         detach-stmt
         drop-index-stmt
         drop-table-stmt
         drop-trigger-stmt
         drop-view-stmt
         insert-stmt
         pragma-stmt
         reindex-stmt
         release-stmt
         rollback-stmt
         savepoint-stmt
         select-stmt
         update-stmt
         update-stmt-limited
         vacuum-stmt
      }
  }
  alter-table-stmt {
    stack
       {line ALTER TABLE {optx /database-name .} /table-name}
       {tailbranch
          {line RENAME TO /new-table-name}
          {line ADD {optx COLUMN} column-def}
       }
  }
  analyze-stmt {
     line ANALYZE {or nil /database-name /table-name
                    {line /database-name . /table-name}}
  }
  attach-stmt {
     line ATTACH {or DATABASE nil} /filename AS /database-name
  }
  begin-stmt {
     line BEGIN {or nil DEFERRED IMMEDIATE EXCLUSIVE}
          {optx TRANSACTION}
  }
  commit-stmt {
     line {or COMMIT END} {optx TRANSACTION}
  }
  rollback-stmt {
     line ROLLBACK {optx TRANSACTION}
        {optx TO {optx SAVEPOINT} /savepoint-name}
  }
  savepoint-stmt {
     line SAVEPOINT /savepoint-name
  }
  release-stmt {
     line RELEASE {optx SAVEPOINT} /savepoint-name
  }
  create-index-stmt {
    stack
       {line CREATE {opt UNIQUE} INDEX {opt IF NOT EXISTS}}
       {line {optx /database-name .} /index-name
             ON /table-name ( {loop indexed-column ,} )}
  }
  indexed-column {
      line /column-name {optx COLLATE /collation-name} {or ASC DESC nil} 
  }
  create-table-stmt {
    stack
       {line CREATE {or {} TEMP TEMPORARY} TABLE {opt IF NOT EXISTS}}
       {line {optx /database-name .} /table-name
          {tailbranch
            {line ( {loop column-def ,} {loop {} {, table-constraint}} )}
            {line AS select-stmt}
          }
       }
  }
  column-def {
    line /column-name {or type-name nil} {loop nil {nil column-constraint nil}}
  }
  type-name {
     line {loop /name {}} {or {}
        {line ( signed-number )}
        {line ( signed-number , signed-number )}
     }
  }
  column-constraint {
    stack
      {optx CONSTRAINT /name}
      {or
         {line PRIMARY KEY {or nil ASC DESC} 
               conflict-clause {opt AUTOINCREMENT}
         }
         {line NOT NULL conflict-clause}
         {line UNIQUE conflict-clause}
         {line CHECK ( expr )}
         {line DEFAULT 
            {or
                signed-number
                literal-value
                {line ( expr )}
            }
         }
         {line COLLATE /collation-name}
         {line foreign-key-clause}
      }
  }
  signed-number {
     line
        {or nil + -}
        {or /integer-literal /floating-point-literal}
  }
  table-constraint {
     stack
       {optx CONSTRAINT /name}
       {or
          {line {or {line PRIMARY KEY} UNIQUE}
                ( {loop indexed-column ,} ) conflict-clause}
          {line CHECK ( expr )}
          {line FOREIGN KEY ( {loop /column-name ,} ) foreign-key-clause }
       }
  }
  foreign-key-clause {
      stack 
        {line REFERENCES /foreign-table {optx ( {loop /column-name ,} )}}
        {optx 
          {loop
             {or 
                {line ON {or DELETE UPDATE}
                         {or {line SET NULL} {line SET DEFAULT}
                             CASCADE RESTRICT {line NO ACTION}
                         }
                }
                {line MATCH /name}
             }
             {}
          }
        }
        {optx
          {line {optx NOT} DEFERRABLE 
             {or 
                {line INITIALLY DEFERRED}
                {line INITIALLY IMMEDIATE}
                {}
             }
          }
          nil
        }
  }
  conflict-clause {
    opt {line ON CONFLICT {or ROLLBACK ABORT FAIL IGNORE REPLACE}}
  }
  create-trigger-stmt {
    stack
       {line CREATE {or {} TEMP TEMPORARY} TRIGGER {opt IF NOT EXISTS}}
       {line {optx /database-name .} /trigger-name
             {or BEFORE AFTER {line INSTEAD OF} nil}
       }
       {line
             {or DELETE INSERT 
                 {line UPDATE {opt OF {loop /column-name ,} }}
             }
             ON /table-name
       }
       {line {optx FOR EACH ROW}
             {optx WHEN expr}
       }
       {line BEGIN
             {loop 
                {line {or update-stmt insert-stmt delete-stmt select-stmt} ;} 
                nil
             }
             END
       }
  }
  create-view-stmt {
    stack
       {line CREATE {or {} TEMP TEMPORARY} VIEW {opt IF NOT EXISTS}}
       {line {optx /database-name .} /view-name AS select-stmt}
  }
  create-virtual-table-stmt {
    stack
       {line CREATE VIRTUAL TABLE {optx /database-name .} /table-name}
       {line USING /module-name {optx ( {loop /module-argument ,} )}}
  }
  delete-stmt {
    line DELETE FROM qualified-table-name {optx WHERE expr}
  }
  delete-stmt-limited {
    stack
        {line DELETE FROM qualified-table-name {optx WHERE expr}}
        {optx
            {stack
              {optx ORDER BY {loop ordering-term ,}}
              {line LIMIT /integer {optx {or OFFSET ,} /integer}}
            }
        }
  }
  detach-stmt {
    line DETACH {optx DATABASE} /database-name
  }
  drop-index-stmt {
    line DROP INDEX {optx IF EXISTS} {optx /database-name .} /index-name
  }
  drop-table-stmt {
    line DROP TABLE {optx IF EXISTS} {optx /database-name .} /table-name
  }
  drop-trigger-stmt {
    line DROP TRIGGER {optx IF EXISTS} {optx /database-name .} /trigger-name
  }
  drop-view-stmt {
    line DROP VIEW {optx IF EXISTS} {optx /database-name .} /view-name
  }
  expr {
    or
     {line literal-value}
     {line bind-parameter}
     {line {optx {optx /database-name .} /table-name .} /column-name}
     {line /unary-operator expr}
     {line expr /binary-operator expr}
     {line /function-name ( {or {line {optx DISTINCT} {toploop expr ,}} {} *} )}
     {line ( expr )}
     {line CAST ( expr AS type-name )}
     {line expr COLLATE /collation-name}
     {line expr {optx NOT} {or LIKE GLOB REGEXP MATCH} expr
           {optx ESCAPE expr}}
     {line expr {or ISNULL NOTNULL {line NOT NULL}}}
     {line expr IS {optx NOT} expr}
     {line expr {optx NOT} BETWEEN expr AND expr}
     {line expr {optx NOT} IN 
            {or
               {line ( {or {} select-stmt {loop expr ,}} )}
               {line {optx /database-name .} /table-name}
            }
     }
     {line {optx {optx NOT} EXISTS} ( select-stmt )}
     {line CASE {optx expr} {loop {line WHEN expr THEN expr} {}}
           {optx ELSE expr} END}
     {line raise-function}
  }
  raise-function {
     line RAISE ( 
           {or IGNORE
               {line {or ROLLBACK ABORT FAIL} , /error-message }
           } )
  }
  literal-value {
    or
     {line /integer-literal}
     {line /floating-point-literal}
     {line /string-literal}
     {line /blob-literal}
     {line NULL}
     {line CURRENT_TIME}
     {line CURRENT_DATE}
     {line CURRENT_TIMESTAMP}
  }
  insert-stmt {
    stack
       {line
          {or 
              {line INSERT {opt OR {or ROLLBACK ABORT REPLACE FAIL IGNORE}}}
              REPLACE
          }
          INTO {optx /database-name .} /table-name
       }
       {tailbranch
          {line 
                {optx ( {loop /column-name ,} )}
                {tailbranch
                    {line VALUES ( {loop expr ,} )}
                    select-stmt
                }
          }
          {line DEFAULT VALUES}
       }
  }
  pragma-stmt {
     line PRAGMA {optx /database-name .} /pragma-name
          {or
              nil
              {line = pragma-value}
              {line ( pragma-value )}
          }
  }
  pragma-value {
     or
        signed-number
        /name
        /string-literal
  }
  reindex-stmt {
     line REINDEX
          {tailbranch
             /collation-name
             {line {optx /database-name .}
                 {tailbranch /table-name /index-name}
             }
          }
  }
  select-stmt {
    stack
       {loop {line select-core nil} {nil compound-operator nil}}
       {optx ORDER BY {loop ordering-term ,}}
       {optx LIMIT /integer {optx {or OFFSET ,} /integer}}
  }
  select-core {
     stack
       {line SELECT {or nil DISTINCT ALL} {loop result-column ,}}
       {optx FROM join-source}
       {optx WHERE expr}
       {optx GROUP BY {loop ordering-term ,} {optx HAVING expr}}
        
  }
  result-column {
     or
        *
        {line /table-name . *}
        {line expr {optx {optx AS} /column-alias}}
  }
  join-source {
     line
        single-source
        {opt {loop {line nil join-op single-source join-constraint nil} {}}}
  }
  single-source {
     or
       {line
          {optx /database-name .} /table-name
          {optx {optx AS} /table-alias}
          {or nil {line INDEXED BY /index-name} {line NOT INDEXED}}
       }
       {line
          ( select-stmt ) {optx {optx AS} /table-alias}
       }
       {line ( join-source )}
  }
  join-op {
     or
        {line ,}
        {line
            {opt NATURAL}
            {or {line {opt LEFT} {opt OUTER}} INNER CROSS}
            JOIN
        }
  }
  join-constraint {
     or
        {line ON expr}
        {line USING ( {loop /column-name ,} )}
        nil
  }
  ordering-term {
      line expr {opt COLLATE /collation-name} {or nil ASC DESC} 
  }
  compound-operator {
     or {line UNION {optx ALL}} INTERSECT EXCEPT
  }
  update-stmt {
     stack
        {line UPDATE {opt OR {or ROLLBACK ABORT REPLACE FAIL IGNORE}}
              qualified-table-name}
        {line SET {loop {line /column-name = expr} ,} {optx WHERE expr}}
  }
  update-stmt-limited {
     stack
        {line UPDATE {opt OR {or ROLLBACK ABORT REPLACE FAIL IGNORE}}
              qualified-table-name}
        {line SET {loop {line /column-name = expr} ,} {optx WHERE expr}}
        {optx
            {stack
              {optx ORDER BY {loop ordering-term ,}}
              {line LIMIT /integer {optx {or OFFSET ,} /integer}}
            }
        }
  }
  qualified-table-name {
     line {optx /database-name .} /table-name
          {or nil {line INDEXED BY /index-name} {line NOT INDEXED}}
  }
  vacuum-stmt {
      line VACUUM
  }
  comment-syntax {
    or
      {line -- {loop nil /anything-except-newline} 
           {or /newline /end-of-input}}
      {line /* {loop nil /anything-except-*/}
           {or */ /end-of-input}}
  }
}

# padding (diff betwee font1 and font2)
set pad "6px"
# used for bubble text
set font1 "12px"
# used for bnf syntax [ ] | etc.
set font2 "18px"
# used for everything else (~ font1+5)
set font3 "16px"

# Draw a bubble containing $txt. 
#
proc draw_bubble {txt} {
  global font1

  if {$txt=="nil"} {
    return [list 1 ""]
  }

  if {[regexp {^/[a-z]} $txt]} {
    set txt [string range $txt 1 end]
    set istoken 1
  } elseif {[regexp {^[a-z]} $txt]} {
    set istoken 0
  } else {
    set istoken 1
  }

  if {!$istoken} {
    set txt "&lt;<a href=\"#$txt\">$txt</a>&gt;"
  }
  
  return [list 1 "<font style=\"white-space:nowrap; font-size:$font1;\">$txt</font>"]
}

# Draw a sequence of terms from left to write.  Each element of $lx
# descripts a single term.
#
proc draw_line {lx} {
  global font1

  set n [llength $lx]

  set h 1
  set content ""
  set i 0
  foreach term $lx {
    incr i

    set rc [draw_diagram $term]
    set th [lindex $rc 0]
    set tcontent [lindex $rc 1]

    if { $tcontent != "" } {
      if { $content != "" } {
        set content "$content&nbsp;$tcontent"
      } else {
        set content "$tcontent"
      }
      if { $th > $h } { set h $th }
    }
  }
  set content "$content"

  return [list $h $content]
}

# Draw a sequence of terms from top to bottom.
#
proc draw_stack {indent lx} {
  global font1

  set n [llength $lx]

  set h 0
  set content ""

  set i 0
  foreach term $lx {
    if { $term != "" } {
      set rc [draw_diagram $term]
      set th [lindex $rc 0]
      set tcontent [lindex $rc 1]
      set h [ expr { $h + $th } ]
      
      incr i
      if {$i == 1} {
        set content "$tcontent"
      } else {
        set content "$content<br>$tcontent"
      }
    }
  }

  return [list $h $content]
}

proc draw_loop {forward back} {
  global font1

  set h 0
  set content ""

  set rc [draw_diagram $forward]
  set th [lindex $rc 0]
  set tcontent [lindex $rc 1]

  if { $tcontent != "" } {
    set content "$tcontent"
    if { $th > $h } { set h $th }
  }
  
  set rc [draw_line $back]
  set th [lindex $rc 0]
  set tcontent [lindex $rc 1]

  if { $tcontent != "" } {
    if { $content != "" } {
      set content "$content \[&nbsp;$tcontent&nbsp;$content&nbsp;]*"
    } else {
      set content "\[&nbsp;$tcontent&nbsp;]*"
    }
    if { $th > $h } { set h $th }
  }

  return [list $h $content]
}

proc draw_or {lx} {
  global font1

  set n [llength $lx]

  set h 0
  if {$n < 1} {
    set content ""
  } else {
    set content ""
    set i 0
    set req "<font style=\"vertical-align:top; font-size:$font1;\">1</font>"
    foreach term $lx {

      set rc [draw_diagram $term]
      set th [lindex $rc 0]
      set tcontent [lindex $rc 1]

      if { $tcontent == "" } {
        set req ""
      } else {
        incr i
        if {$i == 1} {
          set content "$tcontent"
        } else {
          set content "$content | $tcontent"
        }
        if { $th > $h } { set h $th }
      }

    }
  }
  set content "\[&nbsp;$content&nbsp;]$req"
  return [list $h $content]
}

proc draw_diagram {spec} {
  global font1

  set n [llength $spec]
  set cmd [lindex $spec 0]

  if {$n==1} {
    set rc [draw_bubble $spec]
  } elseif {$n==0} {
    set rc [draw_bubble nil]
  } elseif {$cmd=="line"} {
    set rc [draw_line [lrange $spec 1 end]]
  } elseif {$cmd=="stack"} {
    set rc [draw_stack 0 [lrange $spec 1 end]]
  } elseif {$cmd=="indentstack"} {
    set rc [draw_stack $::HSEP [lrange $spec 1 end]]
  } elseif {$cmd=="loop"} {
    set rc [draw_loop [lindex $spec 1] [lindex $spec 2]]
  } elseif {$cmd=="toploop"} {
    set rc [draw_loop [lindex $spec 1] [lindex $spec 2]]
  } elseif {$cmd=="or"} {
    set rc [draw_or [lrange $spec 1 end]]
  } elseif {$cmd=="opt"} {
    set args [lrange $spec 1 end]
    if {[llength $args]==1} {
      set rc [draw_or [list nil [lindex $args 0]]]
    } else {
      set rc [draw_or [list nil "line $args"]]
    }
  } elseif {$cmd=="optx"} {
    set args [lrange $spec 1 end]
    if {[llength $args]==1} {
      set rc [draw_or [list [lindex $args 0] nil]]
    } else {
      set rc [draw_or [list "line $args" nil]]
    }
  } elseif {$cmd=="tailbranch"} {
    # set rc [draw_tail_branch [lrange $spec 1 end]]
    set rc [draw_or [lrange $spec 1 end]]
  } else {
    error "unknown operator: $cmd"
  }

  set h [lindex $rc 0]
  set content [lindex $rc 1]

  return [list $h $content]
}

proc draw_graph {name spec} {
  global font1 pad

  set cmd1 [lindex $spec 0]
  if { $cmd1 == "or" } {
    set req 1
    set spec1 [lrange $spec 1 end]
    foreach term $spec1 {
      if { $term == "" || $term == "nil"} {
        set req 0
      }
    }
    if { $req == 1 } {
      set content "<table>"
      set h 0
      foreach term $spec1 {
        set rc [ draw_diagram "line [list $term]"]
        set th [lindex $rc 0]
        set tcontent [lindex $rc 1]
        set content "$content<tr><td style=\"font-size:$font1; white-space:nowrap; padding-top:$pad;\">$name</td><td>::=</td><td>$tcontent</td></tr>"
        set h [ expr { $h + $th } ]
      }
      set content "$content</table>"
      return [list $h $content]
    }
  }

  set rc [ draw_diagram "line [list $spec]"]
  set h [lindex $rc 0]
  set content [lindex $rc 1]
  set content "<table><tr><td style=\"font-size:$font1; white-space:nowrap; padding-top:$pad;\">$name</td><td>::=</td><td>$content</td></tr></table>"
  return [list $h $content]
}

set f [open all-bnf.html w]
puts $f "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\">"
puts $f "<html>"
puts $f "<head>"
puts $f "<style type='text/css'>"
puts $f "h3 { font-family:helvetica; font-size:$font3; }"
puts $f "table, tr, td { font-family:helvetica; font-size:$font2; empty-cells:show; border-collapse:separate; border-style:none; vertical-align:top; }"
puts $f "</style>"
puts $f "</head>"
puts $f "<body>"
foreach {name graph} $all_graphs {
  if {$name == "sql-stmt-list" || 1} {
    puts $f "<h3><a name=\"$name\">$name</a>:</h3>"
    set rc [draw_graph $name $graph]
    set h [lindex $rc 0]
    set content [lindex $rc 1]
    puts $f "$content"
  }
}
puts $f "</body>"
puts $f "</html>"
close $f