tmplstr

README

tmplstr - text and html template utilities

A collection of utilities for working with text and html template source files.

Installation

> go get github.com/go-corelibs/tmplstr@latest

Examples

RemoveTemplateComments

func main() {
    cleaned := tmplstr.RemoveTemplateComments(`{{ _ "message" /* comment */ }}`)
    // cleaned == `{{ _ "message"  }}`
}

ParseTemplate

func main() {
    tree, _ := tmplstr.ParseTemplate(`before{{pipeline}}after`)
}

From the above example, calling tree.Format() would produce the following JSON text:

[
  {
    "text": "before"
  },
  {
    "action": {
      "open": "{{",
      "pipelines": [
        {
          "variables": [
            {
              "ident": "pipeline"
            }
          ]
        }
      ],
      "close": "}}"
    }
  },
  {
    "text": "after"
  }
]

Go-CoreLibs

Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.

License

Copyright 2024 The Go-CoreLibs Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use 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.

Documentation

Overview

Package tmplstr provides text and html template utilities

Index

• func PruneTemplateComments(input string) (pruned string, err error)
• func RemoveTemplateComments(input string) (cleaned string)
• type Action
  • func (a *Action) Render() (source string)
  • func (a *Action) WalkVariables(fn VariablesWalkFn) (stopped bool)
• type Branch
  • func (b *Branch) Render() (source string)
• type Grouping
  • func (g Grouping) Render() (source string)
• type Pipeline
  • func (p *Pipeline) Render() (source string)
  • func (p *Pipeline) WalkVariables(fn func(variables *Variables) (stop bool)) (stopped bool)
• type Pipelines
  • func (p Pipelines) Render() (source string)
• type Tree
  • func ParseTemplate(filename, input string) (trees Tree, err error)
  • func (t Tree) Format() (output string)
  • func (t Tree) Render() (source string)
  • func (t Tree) WalkVariables(fn VariablesWalkFn) (stopped bool)
• type Variable
  • func (v *Variable) Render() (source string)
• type Variables
  • func (vs Variables) Render() (output string)
  • func (vs Variables) WalkVariables(fn func(variables *Variables) (stop bool)) (stopped bool)
• type VariablesWalkFn

Functions

func PruneTemplateComments

func PruneTemplateComments(input string) (pruned string, err error)

PruneTemplateComments is like RemoveTemplateComments with a very fundamental difference, instead of using ScanCarve and ScanBothCarve, PruneTemplateComments uses ParseTemplate, walks the Variables in the Tree, setting all Variable.Comment values to nil and finally returning the rendered results of the modified Tree. If PruneTemplateComments fails to ParseTemplate, the error is returned and pruned is empty

RemoveTemplateComments is much faster at this task and PruneTemplateComments is more-or-less an example of using ParseTemplate to modify the template source text programmatically

Benchmark Comparison:

|          | PruneTemplateComments |     RemoveTemplateComments      |
|----------|-----------------------|---------------------------------|
|          |        sec/op         |     sec/op       vs base        |
| Comments |        0.037610n ± 0% | 0.005125n ± 16%  -86.37% (n=50) |
|----------|---------------------------------------------------------|
|          |  (both implementations have 0 B/op and 0 allocs/op)     |

Deprecated: please use RemoveTemplateComments instead

func RemoveTemplateComments

func RemoveTemplateComments(input string) (cleaned string)

RemoveTemplateComments removes all C-style block comments from within template pipelines, preserving escaped and quoted comments, using github.com/go-corelibs/strings ScanCarve and ScanBothCarve making RemoveTemplateComments very fast compared to PruneTemplateComments

Types

type Action

type Action struct {
	Open      *string   `parser:"( @StatementOpen "   json:"open,omitempty"`
	Pipelines Pipelines `parser:"  @@"                json:"pipelines,omitempty"`
	Close     *string   `parser:"  @StatementClose )" json:"close,omitempty"`
}

Action represents a single text or html template action

See: https://pkg.go.dev/text/template#hdr-Actions

func (*Action) Render

func (a *Action) Render() (source string)

Render returns the source text represented by this Branch

func (*Action) WalkVariables

func (a *Action) WalkVariables(fn VariablesWalkFn) (stopped bool)

WalkVariables walks this Action, calling the given VariablesWalkFn for all Variables present

type Branch

type Branch struct {
	Action *Action `parser:"( @@ "        json:"action,omitempty"`
	Text   *string `parser:"  | @Text )"  json:"text,omitempty"`
}

func (*Branch) Render

func (b *Branch) Render() (source string)

Render returns the source text represented by this Branch

type Grouping

type Grouping struct {
	Open  *string   `parser:"( @GroupOpen"    json:"open,omitempty"`
	Group *Pipeline `parser:"  @@"            json:"group,omitempty"`
	Close *string   `parser:"  @GroupClose )" json:"close,omitempty"`
}

Grouping represents a grouping Pipeline

Example: in `{{ ident (inner pipeline) }}` the Grouping is the `(inner pipeline)` portion

func (Grouping) Render

func (g Grouping) Render() (source string)

Render returns the source text represented by this Grouping

type Pipeline

type Pipeline struct {
	Root Variables `parser:"@@ ( @@ )*"    json:"variables,omitempty"`
	Pipe *Pipeline `parser:"( Pipe @@ )?"  json:"piped,omitempty"`
}

Pipeline defines the source text representing a list of Variables which may also be piped into another Pipeline instance

func (*Pipeline) Render

func (p *Pipeline) Render() (source string)

Render returns the source text represented by this Pipeline

func (*Pipeline) WalkVariables

func (p *Pipeline) WalkVariables(fn func(variables *Variables) (stop bool)) (stopped bool)

type Pipelines

type Pipelines []*Pipeline

Pipelines is a list of Pipeline instances

func (Pipelines) Render

func (p Pipelines) Render() (source string)

Render returns the source text represented by this list of Pipelines

type Tree

type Tree []*Branch

Tree is a list of Branch instances and is the top of the ParseTemplate abstract syntax tree

func ParseTemplate

func ParseTemplate(filename, input string) (trees Tree, err error)

ParseTemplate uses github.com/alecthomas/participle/v2 to parse the given template file content into an abstract syntax tree. ParseTemplate is intended to facilitate extracting contextual information from text or html template source text

func (Tree) Format

func (t Tree) Format() (output string)

Format returns indented JSON output representing this Tree

func (Tree) Render

func (t Tree) Render() (source string)

Render returns the source text represented by this Tree

func (Tree) WalkVariables

func (t Tree) WalkVariables(fn VariablesWalkFn) (stopped bool)

WalkVariables walks this Tree, calling the given VariablesWalkFn for all Variables present

type Variable

type Variable struct {
	Assign   *string   `parser:"(  @Assignment" json:"assign,omitempty"`
	Range    *string   `parser:" | @Range"      json:"range,omitempty"`
	Ident    *string   `parser:" | @Ident"      json:"ident,omitempty"`
	Keyword  *string   `parser:" | @Keyword"    json:"keyword,omitempty"`
	Literal  *string   `parser:" | @Literal"    json:"literal,omitempty"`
	String   *string   `parser:" | @String"     json:"string,omitempty"`
	Rune     *string   `parser:" | @Rune"       json:"rune,omitempty"`
	Float    *float64  `parser:" | @Float"      json:"float,omitempty"`
	Int      *int      `parser:" | @Int"        json:"int,omitempty"`
	Space    *string   `parser:" | ( @Space )+" json:"space,omitempty"`
	Comment  *string   `parser:" | @Comment"    json:"comment,omitempty"`
	Grouping *Grouping `parser:" | @@ )"        json:"grouping,omitempty"`
}

func (*Variable) Render

func (v *Variable) Render() (source string)

Render returns the source text represented by this Variable

type Variables

type Variables []*Variable

func (Variables) Render

func (vs Variables) Render() (output string)

Render returns the source text represented by this list of Variables

func (Variables) WalkVariables

func (vs Variables) WalkVariables(fn func(variables *Variables) (stop bool)) (stopped bool)

type VariablesWalkFn

type VariablesWalkFn func(variables *Variables) (stop bool)

VariablesWalkFn is the function signature for Variable-walking methods. When these functions return true, the WalkVariables call is immediately stopped