quote.go

// Copyright 2020 CUE Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package literal

import (
	"strconv"
	"strings"
	"unicode/utf8"
)

// Form defines how to quote a string or bytes literal.
type Form struct {
	hashCount   int
	quote       byte
	multiline   bool
	auto        bool
	exact       bool
	asciiOnly   bool
	graphicOnly bool
	indent      string
	tripleQuote string
}

// TODO:
// - Fixed or max level of escape modifiers (#""#).
// - Option to fall back to bytes if value cannot be represented as string.
//   E.g. ExactString.
// - QuoteExact that fails with an error if a string cannot be represented
//   without loss.
// - Handle auto-breaking for long lines (Swift-style, \-terminated lines).
//   This is not supported yet in CUE, but may, and should be considered as
//   a possibility in API design.
// - Other possible convenience forms: Blob (auto-break bytes), String (bytes
//   or string), Label.

// WithTabIndent returns a new Form with indentation set to the given number
// of tabs. The result will be a multiline string.
func (f Form) WithTabIndent(n int) Form {
	f.indent = tabs(n)
	f.multiline = true
	return f
}

const tabIndent = "\t\t\t\t\t\t\t\t\t\t\t\t"

func tabs(n int) string {
	if n < len(tabIndent) {
		return tabIndent[:n]
	}
	return strings.Repeat("\t", n)
}

// WithOptionalIndent is like WithTabIndent, but only returns a multiline
// strings if it doesn't contain any newline characters.
func (f Form) WithOptionalTabIndent(tabs int) Form {
	if tabs < len(tabIndent) {
		f.indent = tabIndent[:tabs]
	} else {
		f.indent = strings.Repeat("\t", tabs)
	}
	f.auto = true
	return f
}

// WithASCIIOnly ensures the quoted strings consists solely of valid ASCII
// characters.
func (f Form) WithASCIIOnly() Form {
	f.asciiOnly = true
	return f
}

// WithGraphicOnly ensures the quoted strings consists solely of printable
// characters.
func (f Form) WithGraphicOnly() Form {
	f.graphicOnly = true
	return f
}

var (
	// String defines the format of a CUE string. Conversions may be lossy.
	String Form = stringForm

	// TODO: ExactString: quotes to bytes type if the string cannot be
	// represented without loss of accuracy.

	// Label is like Text, but optimized for labels.
	Label Form = stringForm

	// Bytes defines the format of bytes literal.
	Bytes Form = bytesForm

	stringForm = Form{
		quote:       '"',
		tripleQuote: `"""`,
	}
	bytesForm = Form{
		quote:       '\'',
		tripleQuote: `'''`,
		exact:       true,
	}
)

// Quote returns CUE string literal representing s. The returned string uses CUE
// escape sequences (\t, \n, \u00FF, \u0100) for control characters and
// non-printable characters as defined by strconv.IsPrint.
//
// It reports an error if the string cannot be converted to the desired form.
func (f Form) Quote(s string) string {
	return string(f.Append(make([]byte, 0, 3*len(s)/2), s))
}

const (
	lowerhex = "0123456789abcdef"
)

// Append appends a CUE string literal representing s, as generated by Quote, to
// buf and returns the extended buffer.
func (f Form) Append(buf []byte, s string) []byte {
	if f.auto && strings.ContainsRune(s, '\n') {
		f.multiline = true
	}
	if f.multiline {
		f.hashCount = f.requiredHashCount(s)
	}

	// Often called with big strings, so preallocate. If there's quoting,
	// this is conservative but still helps a lot.
	if cap(buf)-len(buf) < len(s) {
		nBuf := make([]byte, len(buf), len(buf)+1+len(s)+1)
		copy(nBuf, buf)
		buf = nBuf
	}
	for i := 0; i < f.hashCount; i++ {
		buf = append(buf, '#')
	}
	if f.multiline {
		buf = append(buf, f.quote, f.quote, f.quote, '\n')
		if s == "" {
			buf = append(buf, f.indent...)
			buf = append(buf, f.quote, f.quote, f.quote)
			return buf
		}
		if len(s) > 0 && s[0] != '\n' {
			buf = append(buf, f.indent...)
		}
	} else {
		buf = append(buf, f.quote)
	}

	buf = f.appendEscaped(buf, s)

	if f.multiline {
		buf = append(buf, '\n')
		buf = append(buf, f.indent...)
		buf = append(buf, f.quote, f.quote, f.quote)
	} else {
		buf = append(buf, f.quote)
	}
	for i := 0; i < f.hashCount; i++ {
		buf = append(buf, '#')
	}

	return buf
}

// AppendEscaped appends a CUE string literal representing s, as generated by
// Quote but without the quotes, to buf and returns the extended buffer.
//
// It does not include the last indentation.
func (f Form) AppendEscaped(buf []byte, s string) []byte {
	if f.auto && strings.ContainsRune(s, '\n') {
		f.multiline = true
	}

	// Often called with big strings, so preallocate. If there's quoting,
	// this is conservative but still helps a lot.
	if cap(buf)-len(buf) < len(s) {
		nBuf := make([]byte, len(buf), len(buf)+1+len(s)+1)
		copy(nBuf, buf)
		buf = nBuf
	}

	buf = f.appendEscaped(buf, s)

	return buf
}

func (f Form) appendEscaped(buf []byte, s string) []byte {
	for width := 0; len(s) > 0; s = s[width:] {
		r := rune(s[0])
		width = 1
		if r >= utf8.RuneSelf {
			r, width = utf8.DecodeRuneInString(s)
		}
		if f.exact && width == 1 && r == utf8.RuneError {
			buf = append(buf, `\x`...)
			buf = append(buf, lowerhex[s[0]>>4])
			buf = append(buf, lowerhex[s[0]&0xF])
			continue
		}
		if f.multiline && r == '\n' {
			buf = append(buf, '\n')
			if len(s) > 1 && s[1] != '\n' {
				buf = append(buf, f.indent...)
			}
			continue
		}
		buf = f.appendEscapedRune(buf, r)
	}
	return buf
}

func (f *Form) appendEscapedRune(buf []byte, r rune) []byte {
	var runeTmp [utf8.UTFMax]byte
	if (!f.multiline && r == rune(f.quote)) || r == '\\' { // always backslashed
		buf = f.appendEscape(buf)
		buf = append(buf, byte(r))
		return buf
	}
	if f.asciiOnly {
		if r < utf8.RuneSelf && strconv.IsPrint(r) {
			buf = append(buf, byte(r))
			return buf
		}
	} else if strconv.IsPrint(r) || f.graphicOnly && isInGraphicList(r) {
		n := utf8.EncodeRune(runeTmp[:], r)
		buf = append(buf, runeTmp[:n]...)
		return buf
	}
	buf = f.appendEscape(buf)
	switch r {
	case '\a':
		buf = append(buf, 'a')
	case '\b':
		buf = append(buf, 'b')
	case '\f':
		buf = append(buf, 'f')
	case '\n':
		buf = append(buf, 'n')
	case '\r':
		buf = append(buf, 'r')
	case '\t':
		buf = append(buf, 't')
	case '\v':
		buf = append(buf, 'v')
	default:
		switch {
		case r < ' ' && f.exact:
			buf = append(buf, 'x')
			buf = append(buf, lowerhex[byte(r)>>4])
			buf = append(buf, lowerhex[byte(r)&0xF])
		case r > utf8.MaxRune:
			r = 0xFFFD
			fallthrough
		case r < 0x10000:
			buf = append(buf, 'u')
			for s := 12; s >= 0; s -= 4 {
				buf = append(buf, lowerhex[r>>uint(s)&0xF])
			}
		default:
			buf = append(buf, 'U')
			for s := 28; s >= 0; s -= 4 {
				buf = append(buf, lowerhex[r>>uint(s)&0xF])
			}
		}
	}
	return buf
}

func (f *Form) appendEscape(buf []byte) []byte {
	buf = append(buf, '\\')
	for i := 0; i < f.hashCount; i++ {
		buf = append(buf, '#')
	}
	return buf
}

// requiredHashCount returns the number of # characters
// that are required to quote the multiline string s.
func (f *Form) requiredHashCount(s string) int {
	hashCount := 0
	i := 0
	// Find all occurrences of the triple-quote and count
	// the maximum number of succeeding # characters.
	for {
		j := strings.Index(s[i:], f.tripleQuote)
		if j == -1 {
			break
		}
		i += j + 3
		// Absorb all extra quotes, so we
		// get to the end of the sequence.
		for ; i < len(s); i++ {
			if s[i] != f.quote {
				break
			}
		}
		e := i - 1
		// Count succeeding # characters.
		for ; i < len(s); i++ {
			if s[i] != '#' {
				break
			}
		}
		if nhash := i - e; nhash > hashCount {
			hashCount = nhash
		}
	}
	return hashCount
}

// isInGraphicList reports whether the rune is in the isGraphic list. This separation
// from IsGraphic allows quoteWith to avoid two calls to IsPrint.
// Should be called only if IsPrint fails.
func isInGraphicList(r rune) bool {
	// We know r must fit in 16 bits - see makeisprint.go.
	if r > 0xFFFF {
		return false
	}
	rr := uint16(r)
	i := bsearch16(isGraphic, rr)
	return i < len(isGraphic) && rr == isGraphic[i]
}

// bsearch16 returns the smallest i such that a[i] >= x.
// If there is no such i, bsearch16 returns len(a).
func bsearch16(a []uint16, x uint16) int {
	i, j := 0, len(a)
	for i < j {
		h := i + (j-i)/2
		if a[h] < x {
			i = h + 1
		} else {
			j = h
		}
	}
	return i
}

// isGraphic lists the graphic runes not matched by IsPrint.
var isGraphic = []uint16{
	0x00a0,
	0x1680,
	0x2000,
	0x2001,
	0x2002,
	0x2003,
	0x2004,
	0x2005,
	0x2006,
	0x2007,
	0x2008,
	0x2009,
	0x200a,
	0x202f,
	0x205f,
	0x3000,
}