egon

package module
v0.0.0-...-d9ac57e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 13, 2018 License: MIT Imports: 12 Imported by: 0

README

Egon

Added in this fork

  • Added flags to the egon command
  • Added view geneartion optional, because it is only needed if your web framework supports late rendering
  • Added type safe generation like in ftmpl - use go vet
  • Added Debug mode, otherwise dont print comments inside generated functions
  • Added string optimisation, removed Sprintf for strings
  • Added examples
  • Added minify, currently only tested with HTML code
  • Reverted fmt.Fprintf -> io.WriteString to avoid unnecessary allocations

TODO

  • XML Rendering (xml.Escape...)

=== Note: This is a work in progress.

Egon is a templating language for go, based on Ego. Egon parses .egon templates and converts them into Go source files.

Differences from Ego

  • Ego generates a single source file for every template in a package. Egon generates a source file per template.
  • Ego includes options to name the output package and output files. Egon always determines these names based on the source structure.
  • Ego generates a single function per template for rendering the template. Egon includes a second function, [Template]View that returns an egon.View struct and does not require a writer to be called (but the View does require a writer to render).
  • Ego requires a full function definition, Egon only requires parameter declarations.

Usage

To install egon:

$ go get github.com/commondream/egon/cmd/egon

Running the egon command will process all templates for path.

$ egon ./templates/

All egon files found in the given path are converted to .egon.go files. Each .egon.go file defines two functions:

  1. The Template function - a function with an io.Writer parameter followed by all parameters defined in the template, in the order in which they were defined.
  2. The View function - a function with only the parameters defined in the template in the order that they were defined that returns an egon.View struct.

Language Definition

An ego template is made up of several types of blocks:

  • Code Block - These blocks execute raw Go code: <% var foo = "bar" %>

  • Print Block - These blocks print a Go expression. They use html.EscapeString to escape it before outputting: <%= myVar %>

  • Raw Print Block - These blocks print a Go expression raw into the HTML: <%== "<script>" %>

  • Header Block - These blocks allow you to import packages: <%% import "encoding/json" %%>

  • Parameter Block - This block defines the function signature for your template.

A single declaration block should exist at the top of your template and accept an w io.Writer and return an error. Other arguments can be added as needed. A function receiver can also be used.

<%! name string %>

Example

Below is an example egon template for a web page:

// my_tmpl.egon
<%% import "strings" %%>
<%! u *User %>

<html>
  <body>
    <h1>Hello <%= strings.TrimSpace(u.FirstName) %>!</h1>

    <p>Here's a list of your favorite colors:</p>
    <ul>
      <% for _, colorName := range u.FavoriteColors { %>
        <li><%= colorName %></li>
      <% } %>
    </ul>
  </body>
</html>

Once this template is compiled you can call it using the parameters you specified:

myUser := &User{
  FirstName: "Bob",
  FavoriteColors: []string{"blue", "green", "mauve"},
}
var buf bytes.Buffer
err := mypkg.MyTmplTemplate(&buf, myUser)

Caveats

Unlike other runtime-based templating languages, Egon does not support ad hoc templates. All templates must be generated before compile time.

Egon does not attempt to provide any security around the templates. Just like regular Go code, the security model is up to you.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrParameterFormat notifies the user that a parameter tag is poorly formatted.
	ErrParameterFormat = errors.New("parameters should be of form `param type`")

	// ErrUnidentifiablePackage notifies the user that the package name can't be
	// determined
	ErrUnidentifiablePackage = errors.New("package name cannot be determined")
)
View Source 
var Config struct {
	Typesafe            bool
	StringOptimisations bool
	TmplExtension       string
	Version             string
	Folders             []string
	Debug               bool
	Minify              bool
}

Functions

This section is empty.

Types

type Block 

type Block interface {
	// contains filtered or unexported methods
}

Block represents an element of the template.

type CodeBlock 

type CodeBlock struct {
	Pos     Pos
	Content string
}

CodeBlock represents a Go code block that is printed as-is to the template.

type CommentBlock 

type CommentBlock struct {
	Pos     Pos
	Content string
}

CommentBlock represents a block of text which is discarded

type HeaderBlock 

type HeaderBlock struct {
	Pos     Pos
	Content string
}

HeaderBlock represents a Go code block that is printed at the top of the template.

type Package 

type Package struct {
	Template *Template
}

Package represents the source file representation of a template. Note that it's on its way out, in favor of this functionality being included in Template.

func (*Package) Write 

func (p *Package) Write() error

Write writes out the package header and templates to a writer.

type ParameterBlock 

type ParameterBlock struct {
	Pos       Pos
	ParamName string
	ParamType string
}

DeclarationBlock represents a block that declaration the function signature.

type Pos 

type Pos struct {
	Path   string
	LineNo int
}

Pos represents a position in a given file.

type PrintBlock 

type PrintBlock struct {
	Pos     Pos
	Content string
	Type    byte
}

PrintBlock represents a block that will HTML escape the contents before outputting

type RawPrintBlock 

type RawPrintBlock struct {
	Pos     Pos
	Content string
	Type    byte
}

RawPrintBlock represents a block of the template that is printed out to the writer.

type Scanner 

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner is a tokenizer for Ego templates.

func NewScanner 

func NewScanner(r io.Reader, path string) *Scanner

NewScanner initializes a new scanner with a given reader.

func (*Scanner) Scan 

func (s *Scanner) Scan() (Block, error)

Scan returns the next block from the reader.

type Template 

type Template struct {
	Path   string
	Blocks []Block
}

Template represents an entire Ego template. Templates consist of a set of parameters and other block. Blocks can be either a TextBlock, a PrintBlock, a RawPrintBlock, or a CodeBlock.

func Parse 

func Parse(r io.Reader, path string) (*Template, error)

Parse parses an Ego template from a reader. The path specifies the path name used in the compiled template's pragmas.

func ParseFile 

func ParseFile(path string) (*Template, error)

ParseFile parses an Ego template from a file.

func (*Template) FileName 

func (t *Template) FileName() string

FileName returns the filename of the template, without the path.

func (*Template) Name 

func (t *Template) Name() string

Name returns a name for the template as a camel cased string based on the filename.

func (*Template) PackageName 

func (t *Template) PackageName() (string, error)

PackageName returns the name of the package, based on the last non-file part of the path.

func (*Template) SourceFile 

func (t *Template) SourceFile() string

SourceFile returns the path to the source file that should be generated from this template.

func (*Template) String 

func (t *Template) String() string

func (*Template) TemplateFuncName 

func (t *Template) TemplateFuncName() string

TemplateFuncName returns the name of the Template func for this template.

func (*Template) ViewFuncName 

func (t *Template) ViewFuncName() string

ViewFuncName returns the name fo the View func for this template.

func (*Template) Write 

func (t *Template) Write(w io.Writer) error

Write writes the template to a writer.

type TextBlock 

type TextBlock struct {
	Pos     Pos
	Content string
}

TextBlock represents a UTF-8 encoded block of text that is written to the writer as-is.

type View 

type View struct {
	PackageName  string
	Name         string
	TemplatePath string
	RenderFunc   func(io.Writer) error
}

View represents a runnable form of a template that can be passed between layers in an application without needing to render until the last necessary moment.

func (*View) Render 

func (view *View) Render(w io.Writer) error

Render renders the view to the given io.Writer.

Source Files

View all Source files

Directories

Path Synopsis
cmd
egon

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.