html

Documentation

Overview

Package html converts an AST file structure into html output. Text inside code segments is automatically escaped. Overlapping format tags in the source are converted into a tree structure. Directives are parsed according to the Bourne shell's word-splitting rules.

AST nodes correspond to the following HTML tags:

Paragraph                   <p></p>
Header                      <h1></h1>, <h2></h2>, <h3></h3>, <h4></h4>, <h5></h5>, <h6></h6>, <p></p>
List                        <ul></ul>
ListItem (bulleted)         <li class="bullet"></li>
ListItem (labeled)          <li><span></span></li>
Directive (raw string)      <pre></pre>
Directive (with command)    Depends on the result of command execution
Citation                    <a href=""></a>
Italics                     <em></em>
Bold                        <strong></strong>
BoldItalic                  <strong><em></em></strong>
Underline                   <u></u>
Strikethrough               <s></s>
Code Segment                <code></code>

Index

• type Generator
  • func Gen(file *ast.File) *Generator
  • func GenContext(ctx context.Context, file *ast.File) *Generator
  • func (g *Generator) CombinedOutput() ([]byte, error)
  • func (g *Generator) Output() ([]byte, error)
  • func (g *Generator) Run() error
  • func (g *Generator) Start() error
  • func (g *Generator) StderrPipe() (io.Reader, error)
  • func (g *Generator) StdoutPipe() (io.Reader, error)
  • func (g *Generator) Wait() error

Examples

• Gen
• GenContext
• Generator.CombinedOutput
• Generator.Output
• Generator.Run
• Generator.Start
• Generator.StderrPipe
• Generator.StdoutPipe

Types

type Generator

type Generator struct {
	// Stdout and Stderr specify the generator's standard output and standard error.
	//
	// HTML output will be written to standard out. Standard error is typically only
	// written by a process run for an *ast.Directive.
	//
	// If Stdout == Stderr, at most one goroutine at a time will call Write.
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Generator represents a non-reusable HTML output generator for an *ast.File.

func Gen

func Gen(file *ast.File) *Generator

Gen returns the Generator struct to convert the given file into HTML output.

It sets only the file in the returned structure.

Example

package main

import (
	"bytes"
	"fmt"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := `# Heading 1
This is a paragraph.
*something something Gopher...*
`
	file := parser.MustParse(strings.NewReader(src))
	g := html.Gen(file)
	var out bytes.Buffer
	g.Stdout = &out

	if err := g.Run(); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", out.String())
}

Output:

<h1> Heading 1</h1><p>This is a paragraph.
<em>something something Gopher...</em>
</p>

func GenContext

func GenContext(ctx context.Context, file *ast.File) *Generator

GenContext is like Gen but includes a context.

The provided context is used both to halt HTML generation after processing an ast.Stmt, and to kill any processes executed for an *ast.Directive.

Example

package main

import (
	"bytes"
	"context"
	"fmt"
	"strings"
	"time"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := "The following is a directive:\n```" +
		`sh -c "for i in {1..5}; do echo $i; sleep 1; done"` +
		"\n```"
	file := parser.MustParse(strings.NewReader(src))

	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()
	g := html.GenContext(ctx, file)
	var out bytes.Buffer
	g.Stdout = &out

	if err := g.Run(); err != nil {
		// The 5 second sleep will be interrupted by the 2 second timeout.
	}
	fmt.Printf("%s\n", out.String())
}

func (*Generator) CombinedOutput

func (g *Generator) CombinedOutput() ([]byte, error)

CombinedOutput runs the generator and returns its combined standard output and standard error.

Example

package main

import (
	"fmt"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := "```sh -c \"echo standard output; echo standard error 1>&2\"\n" +
		"```"
	file := parser.MustParse(strings.NewReader(src))
	b, err := html.Gen(file).CombinedOutput()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", b)
}

func (*Generator) Output

func (g *Generator) Output() ([]byte, error)

Output runs the generator and returns its standard output.

Example

package main

import (
	"fmt"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := `# Heading 1
This is a paragraph.
*something something Gopher...*
`
	file := parser.MustParse(strings.NewReader(src))
	b, err := html.Gen(file).Output()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", b)
}

Output:

<h1> Heading 1</h1><p>This is a paragraph.
<em>something something Gopher...</em>
</p>

func (*Generator) Run

func (g *Generator) Run() error

Run starts the generator and waits for it to complete, returning any errors enountered.

Example

package main

import (
	"bytes"
	"fmt"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := "This document simply displays the date when compiled:\n" +
		"```date\n" +
		"```"
	file := parser.MustParse(strings.NewReader(src))
	g := html.Gen(file)
	var out bytes.Buffer
	g.Stdout = &out

	err := g.Run()
	log.Printf("Generator finished with error: %v", err)
	fmt.Printf("%s\n", out.String())
}

func (*Generator) Start

func (g *Generator) Start() error

Start starts the generator but does not wait for it to complete.

Example

package main

import (
	"bytes"
	"fmt"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := "The following is a directive:\n" +
		"```sh -c \"for i in {1..5}; do echo $i; sleep 1; done\"\n" +
		"```"
	file := parser.MustParse(strings.NewReader(src))
	g := html.Gen(file)
	var out bytes.Buffer
	g.Stdout = &out

	if err := g.Start(); err != nil {
		log.Fatal(err)
	}
	log.Print("Waiting for generator to finish...")
	err := g.Wait()
	log.Printf("Generator finished with error: %v", err)
	fmt.Printf("%s\n", out.String())
}

func (*Generator) StderrPipe

func (g *Generator) StderrPipe() (io.Reader, error)

StderrPipe returns a pipe that is connected to the generator's standard error.

It is invalid to call Wait until all reads from the pipe have completed. For the same reason, it is invalid to call Run when using StderrPipe.

Example

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := "```sh -c \"echo standard output; echo standard error 1>&2\"\n" +
		"```"
	file := parser.MustParse(strings.NewReader(src))
	g := html.Gen(file)
	stderr, err := g.StderrPipe()
	if err != nil {
		log.Fatal(err)
	}

	if err := g.Start(); err != nil {
		log.Fatal(err)
	}
	b, _ := ioutil.ReadAll(stderr)
	fmt.Printf("Stderr: %s\n", b)

	if err := g.Wait(); err != nil {
		log.Fatal(err)
	}
}

func (*Generator) StdoutPipe

func (g *Generator) StdoutPipe() (io.Reader, error)

StdoutPipe returns a pipe that is connected to the generator's standard output.

It is invalid to call Wait until all reads from the pipe have completed. For the same reason, it is invalid to call Run when using StdoutPipe.

Example

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"strings"

	"akhil.cc/mexdown/gen/html"
	"akhil.cc/mexdown/parser"
)

func main() {
	src := `# Heading 1
This is a paragraph.
*something something Gopher...*
`
	file := parser.MustParse(strings.NewReader(src))
	g := html.Gen(file)
	stdout, err := g.StdoutPipe()
	if err != nil {
		log.Fatal(err)
	}

	if err := g.Start(); err != nil {
		log.Fatal(err)
	}
	b, _ := ioutil.ReadAll(stdout)
	fmt.Printf("%s\n", b)

	if err := g.Wait(); err != nil {
		log.Fatal(err)
	}
}

func (*Generator) Wait

func (g *Generator) Wait() error

Wait waits for the generator to complete and finish copying to Stdout and Stderr. It is an error to call Wait before Start has been called.

Wait will release any resources associated with the generator.