Subversion Repositories openrisc

// Copyright 2009 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

// Code to parse a template.

package template

import (

        "fmt"

        "io"

        "io/ioutil"

        "reflect"

        "strconv"

        "strings"

        "unicode"

        "unicode/utf8"

)

// Errors returned during parsing and execution.  Users may extract the information and reformat

// if they desire.

type Error struct {

        Line int

        Msg  string

}

func (e *Error) Error() string { return fmt.Sprintf("line %d: %s", e.Line, e.Msg) }

// checkError is a deferred function to turn a panic with type *Error into a plain error return.

// Other panics are unexpected and so are re-enabled.

func checkError(error *error) {

        if v := recover(); v != nil {

                if e, ok := v.(*Error); ok {

                        *error = e

                } else {

                        // runtime errors should crash

                        panic(v)

                }

        }

}

// Most of the literals are aces.

var lbrace = []byte{'{'}

var rbrace = []byte{'}'}

var space = []byte{' '}

var tab = []byte{'\t'}

// The various types of "tokens", which are plain text or (usually) brace-delimited descriptors

const (

        tokAlternates = iota

        tokComment

        tokEnd

        tokLiteral

        tokOr

        tokRepeated

        tokSection

        tokText

        tokVariable

)

// FormatterMap is the type describing the mapping from formatter

// names to the functions that implement them.

type FormatterMap map[string]func(io.Writer, string, ...interface{})

// Built-in formatters.

var builtins = FormatterMap{

        "html": HTMLFormatter,

        "str":  StringFormatter,

        "":     StringFormatter,

}

// The parsed state of a template is a vector of xxxElement structs.

// Sections have line numbers so errors can be reported better during execution.

// Plain text.

type textElement struct {

        text []byte

}

// A literal such as .meta-left or .meta-right

type literalElement struct {

        text []byte

}

// A variable invocation to be evaluated

type variableElement struct {

        linenum int

        args    []interface{} // The fields and literals in the invocation.

        fmts    []string      // Names of formatters to apply. len(fmts) > 0

}

// A variableElement arg to be evaluated as a field name

type fieldName string

// A .section block, possibly with a .or

type sectionElement struct {

        linenum int    // of .section itself

        field   string // cursor field for this block

        start   int    // first element

        or      int    // first element of .or block

        end     int    // one beyond last element

}

// A .repeated block, possibly with a .or and a .alternates

type repeatedElement struct {

        sectionElement     // It has the same structure...

        altstart       int // ... except for alternates

        altend         int

}

// Template is the type that represents a template definition.

// It is unchanged after parsing.

type Template struct {

        fmap FormatterMap // formatters for variables

        // Used during parsing:

        ldelim, rdelim []byte // delimiters; default {}

        buf            []byte // input text to process

        p              int    // position in buf

        linenum        int    // position in input

        // Parsed results:

        elems []interface{}

}

// New creates a new template with the specified formatter map (which

// may be nil) to define auxiliary functions for formatting variables.

func New(fmap FormatterMap) *Template {

        t := new(Template)

        t.fmap = fmap

        t.ldelim = lbrace

        t.rdelim = rbrace

        t.elems = make([]interface{}, 0, 16)

        return t

}

// Report error and stop executing.  The line number must be provided explicitly.

func (t *Template) execError(st *state, line int, err string, args ...interface{}) {

        panic(&Error{line, fmt.Sprintf(err, args...)})

}

// Report error, panic to terminate parsing.

// The line number comes from the template state.

func (t *Template) parseError(err string, args ...interface{}) {

        panic(&Error{t.linenum, fmt.Sprintf(err, args...)})

}

// Is this an exported - upper case - name?

func isExported(name string) bool {

        r, _ := utf8.DecodeRuneInString(name)

        return unicode.IsUpper(r)

}

// -- Lexical analysis

// Is c a space character?

func isSpace(c uint8) bool { return c == ' ' || c == '\t' || c == '\r' || c == '\n' }

// Safely, does s[n:n+len(t)] == t?

func equal(s []byte, n int, t []byte) bool {

        b := s[n:]

        if len(t) > len(b) { // not enough space left for a match.

                return false

        }

        for i, c := range t {

                if c != b[i] {

                        return false

                }

        }

        return true

}

// isQuote returns true if c is a string- or character-delimiting quote character.

func isQuote(c byte) bool {

        return c == '"' || c == '`' || c == '\''

}

// endQuote returns the end quote index for the quoted string that

// starts at n, or -1 if no matching end quote is found before the end

// of the line.

func endQuote(s []byte, n int) int {

        quote := s[n]

        for n++; n < len(s); n++ {

                switch s[n] {

                case '\\':

                        if quote == '"' || quote == '\'' {

                                n++

                        }

                case '\n':

                        return -1

                case quote:

                        return n

                }

        }

        return -1

}

// nextItem returns the next item from the input buffer.  If the returned

// item is empty, we are at EOF.  The item will be either a

// delimited string or a non-empty string between delimited

// strings. Tokens stop at (but include, if plain text) a newline.

// Action tokens on a line by themselves drop any space on

// either side, up to and including the newline.

func (t *Template) nextItem() []byte {

        startOfLine := t.p == 0 || t.buf[t.p-1] == '\n'

        start := t.p

        var i int

        newline := func() {

                t.linenum++

                i++

        }

        // Leading space up to but not including newline

        for i = start; i < len(t.buf); i++ {

                if t.buf[i] == '\n' || !isSpace(t.buf[i]) {

                        break

                }

        }

        leadingSpace := i > start

        // What's left is nothing, newline, delimited string, or plain text

        switch {

        case i == len(t.buf):

                // EOF; nothing to do

        case t.buf[i] == '\n':

                newline()

        case equal(t.buf, i, t.ldelim):

                left := i         // Start of left delimiter.

                right := -1       // Will be (immediately after) right delimiter.

                haveText := false // Delimiters contain text.

                i += len(t.ldelim)

                // Find the end of the action.

                for ; i < len(t.buf); i++ {

                        if t.buf[i] == '\n' {

                                break

                        }

                        if isQuote(t.buf[i]) {

                                i = endQuote(t.buf, i)

                                if i == -1 {

                                        t.parseError("unmatched quote")

                                        return nil

                                }

                                continue

                        }

                        if equal(t.buf, i, t.rdelim) {

                                i += len(t.rdelim)

                                right = i

                                break

                        }

                        haveText = true

                }

                if right < 0 {

                        t.parseError("unmatched opening delimiter")

                        return nil

                }

                // Is this a special action (starts with '.' or '#') and the only thing on the line?

                if startOfLine && haveText {

                        firstChar := t.buf[left+len(t.ldelim)]

                        if firstChar == '.' || firstChar == '#' {

                                // It's special and the first thing on the line. Is it the last?

                                for j := right; j < len(t.buf) && isSpace(t.buf[j]); j++ {

                                        if t.buf[j] == '\n' {

                                                // Yes it is. Drop the surrounding space and return the {.foo}

                                                t.linenum++

                                                t.p = j + 1

                                                return t.buf[left:right]

                                        }

                                }

                        }

                }

                // No it's not. If there's leading space, return that.

                if leadingSpace {

                        // not trimming space: return leading space if there is some.

                        t.p = left

                        return t.buf[start:left]

                }

                // Return the word, leave the trailing space.

                start = left

                break

        default:

                for ; i < len(t.buf); i++ {

                        if t.buf[i] == '\n' {

                                newline()

                                break

                        }

                        if equal(t.buf, i, t.ldelim) {

                                break

                        }

                }

        }

        item := t.buf[start:i]

        t.p = i

        return item

}

// Turn a byte array into a space-split array of strings,

// taking into account quoted strings.

func words(buf []byte) []string {

        s := make([]string, 0, 5)

        for i := 0; i < len(buf); {

                // One word per loop

                for i < len(buf) && isSpace(buf[i]) {

                        i++

                }

                if i == len(buf) {

                        break

                }

                // Got a word

                start := i

                if isQuote(buf[i]) {

                        i = endQuote(buf, i)

                        if i < 0 {

                                i = len(buf)

                        } else {

                                i++

                        }

                }

                // Even with quotes, break on space only.  This handles input

                // such as {""|} and catches quoting mistakes.

                for i < len(buf) && !isSpace(buf[i]) {

                        i++

                }

                s = append(s, string(buf[start:i]))

        }

        return s

}

// Analyze an item and return its token type and, if it's an action item, an array of

// its constituent words.

func (t *Template) analyze(item []byte) (tok int, w []string) {

        // item is known to be non-empty

        if !equal(item, 0, t.ldelim) { // doesn't start with left delimiter

                tok = tokText

                return

        }

        if !equal(item, len(item)-len(t.rdelim), t.rdelim) { // doesn't end with right delimiter

                t.parseError("internal error: unmatched opening delimiter") // lexing should prevent this

                return

        }

        if len(item) <= len(t.ldelim)+len(t.rdelim) { // no contents

                t.parseError("empty directive")

                return

        }

        // Comment

        if item[len(t.ldelim)] == '#' {

                tok = tokComment

                return

        }

        // Split into words

        w = words(item[len(t.ldelim) : len(item)-len(t.rdelim)]) // drop final delimiter

        if len(w) == 0 {

                t.parseError("empty directive")

                return

        }

        first := w[0]

        if first[0] != '.' {

                tok = tokVariable

                return

        }

        if len(first) > 1 && first[1] >= '0' && first[1] <= '9' {

                // Must be a float.

                tok = tokVariable

                return

        }

        switch first {

        case ".meta-left", ".meta-right", ".space", ".tab":

                tok = tokLiteral

                return

        case ".or":

                tok = tokOr

                return

        case ".end":

                tok = tokEnd

                return

        case ".section":

                if len(w) != 2 {

                        t.parseError("incorrect fields for .section: %s", item)

                        return

                }

                tok = tokSection

                return

        case ".repeated":

                if len(w) != 3 || w[1] != "section" {

                        t.parseError("incorrect fields for .repeated: %s", item)

                        return

                }

                tok = tokRepeated

                return

        case ".alternates":

                if len(w) != 2 || w[1] != "with" {

                        t.parseError("incorrect fields for .alternates: %s", item)

                        return

                }

                tok = tokAlternates

                return

        }

        t.parseError("bad directive: %s", item)

        return

}

// formatter returns the Formatter with the given name in the Template, or nil if none exists.

func (t *Template) formatter(name string) func(io.Writer, string, ...interface{}) {

        if t.fmap != nil {

                if fn := t.fmap[name]; fn != nil {

                        return fn

                }

        }

        return builtins[name]

}

// -- Parsing

// newVariable allocates a new variable-evaluation element.

func (t *Template) newVariable(words []string) *variableElement {

        formatters := extractFormatters(words)

        args := make([]interface{}, len(words))

        // Build argument list, processing any literals

        for i, word := range words {

                var lerr error

                switch word[0] {

                case '"', '`', '\'':

                        v, err := strconv.Unquote(word)

                        if err == nil && word[0] == '\'' {

                                args[i], _ = utf8.DecodeRuneInString(v)

                        } else {

                                args[i], lerr = v, err

                        }

                case '.', '+', '-', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9':

                        v, err := strconv.ParseInt(word, 0, 64)

                        if err == nil {

                                args[i] = v

                        } else {

                                v, err := strconv.ParseFloat(word, 64)

                                args[i], lerr = v, err

                        }

                default:

                        args[i] = fieldName(word)

                }

                if lerr != nil {

                        t.parseError("invalid literal: %q: %s", word, lerr)

                }

        }

        // We could remember the function address here and avoid the lookup later,

        // but it's more dynamic to let the user change the map contents underfoot.

        // We do require the name to be present, though.

        // Is it in user-supplied map?

        for _, f := range formatters {

                if t.formatter(f) == nil {

                        t.parseError("unknown formatter: %q", f)

                }

        }

        return &variableElement{t.linenum, args, formatters}

}

// extractFormatters extracts a list of formatters from words.

// After the final space-separated argument in a variable, formatters may be

// specified separated by pipe symbols. For example: {a b c|d|e}

// The words parameter still has the formatters joined by '|' in the last word.

// extractFormatters splits formatters, replaces the last word with the content

// found before the first '|' within it, and returns the formatters obtained.

// If no formatters are found in words, the default formatter is returned.

func extractFormatters(words []string) (formatters []string) {

        // "" is the default formatter.

        formatters = []string{""}

        if len(words) == 0 {

                return

        }

        var bar int

        lastWord := words[len(words)-1]

        if isQuote(lastWord[0]) {

                end := endQuote([]byte(lastWord), 0)

                if end < 0 || end+1 == len(lastWord) || lastWord[end+1] != '|' {

                        return

                }

                bar = end + 1

        } else {

                bar = strings.IndexRune(lastWord, '|')

                if bar < 0 {

                        return

                }

        }

        words[len(words)-1] = lastWord[0:bar]

        formatters = strings.Split(lastWord[bar+1:], "|")

        return

}

// Grab the next item.  If it's simple, just append it to the template.

// Otherwise return its details.

func (t *Template) parseSimple(item []byte) (done bool, tok int, w []string) {

        tok, w = t.analyze(item)

        done = true // assume for simplicity

        switch tok {

        case tokComment:

                return

        case tokText:

                t.elems = append(t.elems, &textElement{item})

                return

        case tokLiteral:

                switch w[0] {

                case ".meta-left":

                        t.elems = append(t.elems, &literalElement{t.ldelim})

                case ".meta-right":

                        t.elems = append(t.elems, &literalElement{t.rdelim})

                case ".space":

                        t.elems = append(t.elems, &literalElement{space})

                case ".tab":

                        t.elems = append(t.elems, &literalElement{tab})

                default:

                        t.parseError("internal error: unknown literal: %s", w[0])

                }

                return

        case tokVariable:

                t.elems = append(t.elems, t.newVariable(w))

                return

        }

        return false, tok, w

}

// parseRepeated and parseSection are mutually recursive

func (t *Template) parseRepeated(words []string) *repeatedElement {

        r := new(repeatedElement)

        t.elems = append(t.elems, r)

        r.linenum = t.linenum

        r.field = words[2]

        // Scan section, collecting true and false (.or) blocks.

        r.start = len(t.elems)

        r.or = -1

        r.altstart = -1

        r.altend = -1

Loop:

        for {

                item := t.nextItem()

                if len(item) == 0 {

                        t.parseError("missing .end for .repeated section")

                        break

                }

                done, tok, w := t.parseSimple(item)

                if done {

                        continue

                }

                switch tok {

                case tokEnd:

                        break Loop

                case tokOr:

                        if r.or >= 0 {

                                t.parseError("extra .or in .repeated section")

                                break Loop

                        }

                        r.altend = len(t.elems)

                        r.or = len(t.elems)

                case tokSection:

                        t.parseSection(w)

                case tokRepeated:

                        t.parseRepeated(w)

                case tokAlternates:

                        if r.altstart >= 0 {

                                t.parseError("extra .alternates in .repeated section")

                                break Loop

                        }

                        if r.or >= 0 {

                                t.parseError(".alternates inside .or block in .repeated section")

                                break Loop

                        }

                        r.altstart = len(t.elems)

                default:

                        t.parseError("internal error: unknown repeated section item: %s", item)

                        break Loop

                }

        }

        if r.altend < 0 {

                r.altend = len(t.elems)

        }

        r.end = len(t.elems)

        return r

}

func (t *Template) parseSection(words []string) *sectionElement {

        s := new(sectionElement)

        t.elems = append(t.elems, s)

        s.linenum = t.linenum

        s.field = words[1]

        // Scan section, collecting true and false (.or) blocks.

        s.start = len(t.elems)

        s.or = -1

Loop:

        for {

                item := t.nextItem()

                if len(item) == 0 {

                        t.parseError("missing .end for .section")

                        break

                }

                done, tok, w := t.parseSimple(item)

                if done {

                        continue

                }

                switch tok {

                case tokEnd:

                        break Loop

                case tokOr:

                        if s.or >= 0 {

                                t.parseError("extra .or in .section")

                                break Loop

                        }

                        s.or = len(t.elems)

                case tokSection:

                        t.parseSection(w)

                case tokRepeated:

                        t.parseRepeated(w)

                case tokAlternates:

                        t.parseError(".alternates not in .repeated")

                default:

                        t.parseError("internal error: unknown section item: %s", item)

                }

        }

        s.end = len(t.elems)

        return s

}

func (t *Template) parse() {

        for {

                item := t.nextItem()

                if len(item) == 0 {

                        break

                }

                done, tok, w := t.parseSimple(item)

                if done {

                        continue

                }

                switch tok {

                case tokOr, tokEnd, tokAlternates:

                        t.parseError("unexpected %s", w[0])

                case tokSection:

                        t.parseSection(w)

                case tokRepeated:

                        t.parseRepeated(w)

                default:

                        t.parseError("internal error: bad directive in parse: %s", item)

                }

        }

}

// -- Execution

// -- Public interface

// Parse initializes a Template by parsing its definition.  The string

// s contains the template text.  If any errors occur, Parse returns

// the error.

func (t *Template) Parse(s string) (err error) {

        if t.elems == nil {

                return &Error{1, "template not allocated with New"}

        }

        if !validDelim(t.ldelim) || !validDelim(t.rdelim) {

                return &Error{1, fmt.Sprintf("bad delimiter strings %q %q", t.ldelim, t.rdelim)}

        }

        defer checkError(&err)

        t.buf = []byte(s)

        t.p = 0

        t.linenum = 1

        t.parse()

        return nil

}

// ParseFile is like Parse but reads the template definition from the

// named file.

func (t *Template) ParseFile(filename string) (err error) {

        b, err := ioutil.ReadFile(filename)

        if err != nil {

                return err

        }

        return t.Parse(string(b))

}

// Execute applies a parsed template to the specified data object,

// generating output to wr.

func (t *Template) Execute(wr io.Writer, data interface{}) (err error) {

        // Extract the driver data.

        val := reflect.ValueOf(data)

        defer checkError(&err)

        t.p = 0

        t.execute(0, len(t.elems), &state{parent: nil, data: val, wr: wr})

        return nil

}

// SetDelims sets the left and right delimiters for operations in the

// template.  They are validated during parsing.  They could be

// validated here but it's better to keep the routine simple.  The

// delimiters are very rarely invalid and Parse has the necessary

// error-handling interface already.

func (t *Template) SetDelims(left, right string) {

        t.ldelim = []byte(left)

        t.rdelim = []byte(right)

}

// Parse creates a Template with default parameters (such as {} for

// metacharacters).  The string s contains the template text while

// the formatter map fmap, which may be nil, defines auxiliary functions

// for formatting variables.  The template is returned. If any errors

// occur, err will be non-nil.

func Parse(s string, fmap FormatterMap) (t *Template, err error) {

        t = New(fmap)

        err = t.Parse(s)

        if err != nil {

                t = nil

        }

        return

}

// ParseFile is a wrapper function that creates a Template with default

// parameters (such as {} for metacharacters).  The filename identifies

// a file containing the template text, while the formatter map fmap, which

// may be nil, defines auxiliary functions for formatting variables.

// The template is returned. If any errors occur, err will be non-nil.

func ParseFile(filename string, fmap FormatterMap) (t *Template, err error) {

        b, err := ioutil.ReadFile(filename)

        if err != nil {

                return nil, err

        }

        return Parse(string(b), fmap)

}

// MustParse is like Parse but panics if the template cannot be parsed.

func MustParse(s string, fmap FormatterMap) *Template {

        t, err := Parse(s, fmap)

        if err != nil {

                panic("template.MustParse error: " + err.Error())

        }

        return t

}

// MustParseFile is like ParseFile but panics if the file cannot be read

// or the template cannot be parsed.

func MustParseFile(filename string, fmap FormatterMap) *Template {

        b, err := ioutil.ReadFile(filename)

        if err != nil {

                panic("template.MustParseFile error: " + err.Error())

        }

        return MustParse(string(b), fmap)

}