spec.go

Documentation: golang.org/x/tools/godoc

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package godoc
     6  
     7  // This file contains the mechanism to "linkify" html source
     8  // text containing EBNF sections (as found in go_spec.html).
     9  // The result is the input source text with the EBNF sections
    10  // modified such that identifiers are linked to the respective
    11  // definitions.
    12  
    13  import (
    14  	"bytes"
    15  	"fmt"
    16  	"io"
    17  	"text/scanner"
    18  )
    19  
    20  type ebnfParser struct {
    21  	out     io.Writer // parser output
    22  	src     []byte    // parser input
    23  	scanner scanner.Scanner
    24  	prev    int    // offset of previous token
    25  	pos     int    // offset of current token
    26  	tok     rune   // one token look-ahead
    27  	lit     string // token literal
    28  }
    29  
    30  func (p *ebnfParser) flush() {
    31  	p.out.Write(p.src[p.prev:p.pos])
    32  	p.prev = p.pos
    33  }
    34  
    35  func (p *ebnfParser) next() {
    36  	p.tok = p.scanner.Scan()
    37  	p.pos = p.scanner.Position.Offset
    38  	p.lit = p.scanner.TokenText()
    39  }
    40  
    41  func (p *ebnfParser) printf(format string, args ...interface{}) {
    42  	p.flush()
    43  	fmt.Fprintf(p.out, format, args...)
    44  }
    45  
    46  func (p *ebnfParser) errorExpected(msg string) {
    47  	p.printf(`<span class="highlight">error: expected %s, found %s</span>`, msg, scanner.TokenString(p.tok))
    48  }
    49  
    50  func (p *ebnfParser) expect(tok rune) {
    51  	if p.tok != tok {
    52  		p.errorExpected(scanner.TokenString(tok))
    53  	}
    54  	p.next() // make progress in any case
    55  }
    56  
    57  func (p *ebnfParser) parseIdentifier(def bool) {
    58  	if p.tok == scanner.Ident {
    59  		name := p.lit
    60  		if def {
    61  			p.printf(`<a id="%s">%s</a>`, name, name)
    62  		} else {
    63  			p.printf(`<a href="#%s" class="noline">%s</a>`, name, name)
    64  		}
    65  		p.prev += len(name) // skip identifier when printing next time
    66  		p.next()
    67  	} else {
    68  		p.expect(scanner.Ident)
    69  	}
    70  }
    71  
    72  func (p *ebnfParser) parseTerm() bool {
    73  	switch p.tok {
    74  	case scanner.Ident:
    75  		p.parseIdentifier(false)
    76  
    77  	case scanner.String, scanner.RawString:
    78  		p.next()
    79  		const ellipsis = '…' // U+2026, the horizontal ellipsis character
    80  		if p.tok == ellipsis {
    81  			p.next()
    82  			p.expect(scanner.String)
    83  		}
    84  
    85  	case '(':
    86  		p.next()
    87  		p.parseExpression()
    88  		p.expect(')')
    89  
    90  	case '[':
    91  		p.next()
    92  		p.parseExpression()
    93  		p.expect(']')
    94  
    95  	case '{':
    96  		p.next()
    97  		p.parseExpression()
    98  		p.expect('}')
    99  
   100  	default:
   101  		return false // no term found
   102  	}
   103  
   104  	return true
   105  }
   106  
   107  func (p *ebnfParser) parseSequence() {
   108  	if !p.parseTerm() {
   109  		p.errorExpected("term")
   110  	}
   111  	for p.parseTerm() {
   112  	}
   113  }
   114  
   115  func (p *ebnfParser) parseExpression() {
   116  	for {
   117  		p.parseSequence()
   118  		if p.tok != '|' {
   119  			break
   120  		}
   121  		p.next()
   122  	}
   123  }
   124  
   125  func (p *ebnfParser) parseProduction() {
   126  	p.parseIdentifier(true)
   127  	p.expect('=')
   128  	if p.tok != '.' {
   129  		p.parseExpression()
   130  	}
   131  	p.expect('.')
   132  }
   133  
   134  func (p *ebnfParser) parse(out io.Writer, src []byte) {
   135  	// initialize ebnfParser
   136  	p.out = out
   137  	p.src = src
   138  	p.scanner.Init(bytes.NewBuffer(src))
   139  	p.next() // initializes pos, tok, lit
   140  
   141  	// process source
   142  	for p.tok != scanner.EOF {
   143  		p.parseProduction()
   144  	}
   145  	p.flush()
   146  }
   147  
   148  // Markers around EBNF sections
   149  var (
   150  	openTag  = []byte(`<pre class="ebnf">`)
   151  	closeTag = []byte(`</pre>`)
   152  )
   153  
   154  func Linkify(out io.Writer, src []byte) {
   155  	for len(src) > 0 {
   156  		// i: beginning of EBNF text (or end of source)
   157  		i := bytes.Index(src, openTag)
   158  		if i < 0 {
   159  			i = len(src) - len(openTag)
   160  		}
   161  		i += len(openTag)
   162  
   163  		// j: end of EBNF text (or end of source)
   164  		j := bytes.Index(src[i:], closeTag) // close marker
   165  		if j < 0 {
   166  			j = len(src) - i
   167  		}
   168  		j += i
   169  
   170  		// write text before EBNF
   171  		out.Write(src[0:i])
   172  		// process EBNF
   173  		var p ebnfParser
   174  		p.parse(out, src[i:j])
   175  
   176  		// advance
   177  		src = src[j:]
   178  	}
   179  }
   180
View as plain text