Skip to content

G
golang
Commit c1c8d46d authored by Rob Pike's avatar Rob Pike
Browse files
Options

go_tutorial: change the way it's generated. 

No longer do we generate HTML from it; instead the input
file is already in HTML but has template invocations to
extract programs from other files.
Delete htmlgen, which is no longer needed.
Add tmpltohtml, which runs the templating code.

R=golang-dev, dsymonds, adg
CC=golang-dev
https://golang.org/cl/4699041
parent f1df07bf
Expand all Show whitespace changes
Inline Side-by-side
Showing with 181 additions and 317 deletions
doc/Makefile
View file @ c1c8d46d
......@@ -4,8 +4,8 @@
include ../src/Make.inc
TARG=htmlgen
TARG=tmpltohtml
GOFILES=\
htmlgen.go\
tmpltohtml.go\
include ../src/Make.cmd
doc/go_tutorial.html
View file @ c1c8d46d
This diff is collapsed.
doc/htmlgen.go deleted 100644 → 0
View file @ f1df07bf
// 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.
// If --html is set, process plain text into HTML.
// - h2's are made from lines followed by a line "----\n"
// - tab-indented blocks become <pre> blocks with the first tab deleted
// - blank lines become <p> marks (except inside <pre> tags)
// - "quoted strings" become <code>quoted strings</code>
// Lines beginning !src define pieces of program source to be
// extracted from other files and injected as <pre> blocks.
// The syntax is simple: 1, 2, or 3 space-separated arguments:
//
// Whole file:
// !src foo.go
// One line (here the signature of main):
// !src foo.go /^func.main/
// Block of text, determined by start and end (here the body of main):
// !src foo.go /^func.main/ /^}/
//
// Patterns can be /regular.expression/, a decimal number, or $
// to signify the end of the file.
// TODO: the regular expression cannot contain spaces; does this matter?
package main
import (
"bufio"
"bytes"
"flag"
"fmt"
"io/ioutil"
"log"
"os"
"regexp"
"strconv"
"strings"
"template"
)
var (
html = flag.Bool("html", true, "process text into HTML")
)
var (
// lines holds the input and is reworked in place during processing.
lines = make([][]byte, 0, 20000)
empty = []byte("")
newline = []byte("\n")
tab = []byte("\t")
quote = []byte(`"`)
indent = []byte(" ")
sectionMarker = []byte("----\n")
preStart = []byte("<pre>")
preEnd = []byte("</pre>\n")
pp = []byte("<p>\n")
srcPrefix = []byte("!src")
)
func main() {
flag.Parse()
read()
programs()
if *html {
headings()
coalesce(preStart, foldPre)
coalesce(tab, foldTabs)
paragraphs()
quotes()
}
write()
}
// read turns standard input into a slice of lines.
func read() {
b := bufio.NewReader(os.Stdin)
for {
line, err := b.ReadBytes('\n')
if err == os.EOF {
break
}
if err != nil {
log.Fatal(err)
}
lines = append(lines, line)
}
}
// write puts the result on standard output.
func write() {
b := bufio.NewWriter(os.Stdout)
for _, line := range lines {
b.Write(expandTabs(line))
}
b.Flush()
}
// programs injects source code from !src invocations.
func programs() {
nlines := make([][]byte, 0, len(lines)*3/2)
for _, line := range lines {
if bytes.HasPrefix(line, srcPrefix) {
line = trim(line)[len(srcPrefix):]
prog := srcCommand(string(line))
if *html {
nlines = append(nlines, []byte(fmt.Sprintf("<pre><!--%s\n-->", line)))
}
for _, l := range prog {
nlines = append(nlines, htmlEscape(l))
}
if *html {
nlines = append(nlines, preEnd)
}
} else {
nlines = append(nlines, line)
}
}
lines = nlines
}
// srcCommand processes one !src invocation.
func srcCommand(command string) [][]byte {
// TODO: quoted args so we can have 'a b'?
args := strings.Fields(command)
if len(args) == 0 || len(args) > 3 {
log.Fatal("bad syntax for src command: %s", command)
}
file := args[0]
lines := bytes.SplitAfter(readFile(file), newline)
// File plus zero args: whole file:
// !src file.go
if len(args) == 1 {
return lines
}
start := match(file, 0, lines, string(args[1]))
// File plus one arg: one line:
// !src file.go /foo/
if len(args) == 2 {
return [][]byte{lines[start]}
}
// File plus two args: range:
// !src file.go /foo/ /^}/
end := match(file, start, lines, string(args[2]))
return lines[start : end+1] // +1 to include matched line.
}
// htmlEscape makes sure input is HTML clean, if necessary.
func htmlEscape(input []byte) []byte {
if !*html || bytes.IndexAny(input, `&"<>`) < 0 {
return input
}
var b bytes.Buffer
template.HTMLEscape(&b, input)
return b.Bytes()
}
// readFile reads and returns a file as part of !src processing.
func readFile(name string) []byte {
file, err := ioutil.ReadFile(name)
if err != nil {
log.Fatal(err)
}
return file
}
// match identifies the input line that matches the pattern in a !src invocation.
// If start>0, match lines starting there rather than at the beginning.
func match(file string, start int, lines [][]byte, pattern string) int {
// $ matches the end of the file.
if pattern == "$" {
return len(lines) - 1
}
// Number matches the line.
if i, err := strconv.Atoi(pattern); err == nil {
return i - 1 // Lines are 1-indexed.
}
// /regexp/ matches the line that matches the regexp.
if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
re, err := regexp.Compile(pattern[1 : len(pattern)-1])
if err != nil {
log.Fatal(err)
}
for i := start; i < len(lines); i++ {
if re.Match(lines[i]) {
return i
}
}
log.Fatalf("%s: no match for %s", file, pattern)
}
log.Fatalf("unrecognized pattern: %s", pattern)
return 0
}
// coalesce combines lines. Each time prefix is found on a line,
// it calls fold and replaces the line with return value from fold.
func coalesce(prefix []byte, fold func(i int) (n int, line []byte)) {
j := 0 // output line number goes up by one each loop
for i := 0; i < len(lines); {
if bytes.HasPrefix(lines[i], prefix) {
nlines, block := fold(i)
lines[j] = block
i += nlines
} else {
lines[j] = lines[i]
i++
}
j++
}
lines = lines[0:j]
}
// foldPre returns the <pre> block as a single slice.
func foldPre(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
for i < len(lines) {
buf.Write(lines[i])
n++
if bytes.Equal(lines[i], preEnd) {
break
}
i++
}
return n, buf.Bytes()
}
// foldTabs returns the tab-indented block as a single <pre>-bounded slice.
func foldTabs(i int) (n int, line []byte) {
buf := new(bytes.Buffer)
buf.WriteString("<pre>\n")
for i < len(lines) {
if !bytes.HasPrefix(lines[i], tab) {
break
}
buf.Write(lines[i][1:]) // delete leading tab.
n++
i++
}
buf.WriteString("</pre>\n")
return n, buf.Bytes()
}
// headings turns sections into HTML sections.
func headings() {
b := bufio.NewWriter(os.Stdout)
for i, l := range lines {
if i > 0 && bytes.Equal(l, sectionMarker) {
lines[i-1] = []byte("<h2>" + string(trim(lines[i-1])) + "</h2>\n")
lines[i] = empty
}
}
b.Flush()
}
// paragraphs turns blank lines into paragraph marks.
func paragraphs() {
for i, l := range lines {
if bytes.Equal(l, newline) {
lines[i] = pp
}
}
}
// quotes turns "x" in the file into <code>x</code>.
func quotes() {
for i, l := range lines {
lines[i] = codeQuotes(l)
}
}
// quotes turns "x" in the line into <code>x</code>.
func codeQuotes(l []byte) []byte {
if bytes.HasPrefix(l, preStart) {
return l
}
n := bytes.Index(l, quote)
if n < 0 {
return l
}
buf := new(bytes.Buffer)
inQuote := false
for _, c := range l {
if c == '"' {
if inQuote {
buf.WriteString("</code>")
} else {
buf.WriteString("<code>")
}
inQuote = !inQuote
} else {
buf.WriteByte(c)
}
}
return buf.Bytes()
}
// trim drops the trailing newline, if present.
func trim(l []byte) []byte {
n := len(l)
if n > 0 && l[n-1] == '\n' {
return l[0 : n-1]
}
return l
}
// expandTabs expands tabs to spaces. It doesn't worry about columns.
func expandTabs(l []byte) []byte {
return bytes.Replace(l, tab, indent, -1)
}
doc/makehtml
View file @ c1c8d46d
......@@ -5,8 +5,8 @@
set -e
TXT=${1:-go_tutorial.txt} # input file
HTML=$(basename $TXT .txt).html # output file (basename)
TMPL=${1:-go_tutorial.tmpl} # input file
HTML=$(basename $TMPL .tmpl).html # output file (basename)
if ! test -w $HTML
then
......@@ -14,4 +14,4 @@ then
exit 1
fi
make && ./htmlgen < $TXT > $HTML
make && ./tmpltohtml $TMPL > $HTML
doc/tmpltohtml.go 0 → 100644
View file @ c1c8d46d
// Copyright 2011 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.
// The template uses the function "code" to inject program
// source into the output by extracting code from files and
// injecting them as HTML-escaped <pre> blocks.
//
// The syntax is simple: 1, 2, or 3 space-separated arguments:
//
// Whole file:
// {{code "foo.go"}}
// One line (here the signature of main):
// {{code "foo.go" `/^func.main/`}}
// Block of text, determined by start and end (here the body of main):
// {{code "foo.go" `/^func.main/` `/^}/`
//
// Patterns can be `/regular expression/`, a decimal number, or "$"
// to signify the end of the file.
package main
import (
"exp/template"
"flag"
"fmt"
"io/ioutil"
"log"
"os"
"regexp"
"strings"
)
func Usage() {
fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
os.Exit(2)
}
func main() {
flag.Usage = Usage
flag.Parse()
if len(flag.Args()) != 1 {
Usage()
}
// Read and parse the input.
name := flag.Args()[0]
tmpl := template.New(name).Funcs(template.FuncMap{"code": code})
if err := tmpl.ParseFile(name); err != nil {
log.Fatal(err)
}
// Execute the template.
if err := tmpl.Execute(os.Stdout, 0); err != nil {
log.Fatal(err)
}
}
// contents reads a file by name and returns its contents as a string.
func contents(name string) string {
file, err := ioutil.ReadFile(name)
if err != nil {
log.Fatal(err)
}
return string(file)
}
// format returns a textual representation of the arg, formatted according to its nature.
func format(arg interface{}) string {
switch arg := arg.(type) {
case int:
return fmt.Sprintf("%d", arg)
case string:
if len(arg) > 2 && arg[0] == '/' && arg[len(arg)-1] == '/' {
return fmt.Sprintf("%#q", arg)
}
return fmt.Sprintf("%q", arg)
default:
log.Fatalf("unrecognized argument: %v type %T", arg, arg)
}
return ""
}
func code(file string, arg ...interface{}) (string, os.Error) {
text := contents(file)
var command string
switch len(arg) {
case 0:
// text is already whole file.
command = fmt.Sprintf("code %q", file)
case 1:
command = fmt.Sprintf("code %q %s", file, format(arg[0]))
text = oneLine(file, text, arg[0])
case 2:
command = fmt.Sprintf("code %q %s %s", file, format(arg[0]), format(arg[1]))
text = multipleLines(file, text, arg[0], arg[1])
default:
return "", fmt.Errorf("incorrect code invocation: code %q %q", file, arg)
}
// Replace tabs by spaces, which work better in HTML.
text = strings.Replace(text, "\t", " ", -1)
// Escape the program text for HTML.
text = template.HTMLEscapeString(text)
// Include the command as a comment.
text = fmt.Sprintf("<pre><!--{{%s}}\n-->%s</pre>", command, text)
return text, nil
}
// parseArg returns the integer or string value of the argument and tells which it is.
func parseArg(arg interface{}, file string, max int) (ival int, sval string, isInt bool) {
switch n := arg.(type) {
case int:
if n <= 0 || n > max {
log.Fatalf("%q:%d is out of range", file, n)
}
return n, "", true
case string:
return 0, n, false
}
log.Fatalf("unrecognized argument %v type %T", arg, arg)
return
}
// oneLine returns the single line generated by a two-argument code invocation.
func oneLine(file, text string, arg interface{}) string {
lines := strings.SplitAfter(contents(file), "\n")
line, pattern, isInt := parseArg(arg, file, len(lines))
if isInt {
return lines[line-1]
}
return lines[match(file, 0, lines, pattern)-1]
}
// multipleLines returns the text generated by a three-argument code invocation.
func multipleLines(file, text string, arg1, arg2 interface{}) string {
lines := strings.SplitAfter(contents(file), "\n")
line1, pattern1, isInt1 := parseArg(arg1, file, len(lines))
line2, pattern2, isInt2 := parseArg(arg2, file, len(lines))
if !isInt1 {
line1 = match(file, 0, lines, pattern1)
}
if !isInt2 {
line2 = match(file, line1, lines, pattern2)
} else if line2 < line1 {
log.Fatal("lines out of order for %q: %d %d", line1, line2)
}
return strings.Join(lines[line1-1:line2], "")
}
// match identifies the input line that matches the pattern in a code invocation.
// If start>0, match lines starting there rather than at the beginning.
// The return value is 1-indexed.
func match(file string, start int, lines []string, pattern string) int {
// $ matches the end of the file.
if pattern == "$" {
if len(lines) == 0 {
log.Fatal("%q: empty file", file)
}
return len(lines)
}
// /regexp/ matches the line that matches the regexp.
if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
re, err := regexp.Compile(pattern[1 : len(pattern)-1])
if err != nil {
log.Fatal(err)
}
for i := start; i < len(lines); i++ {
if re.MatchString(lines[i]) {
return i + 1
}
}
log.Fatalf("%s: no match for %#q", file, pattern)
}
log.Fatalf("unrecognized pattern: %q", pattern)
return 0
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment