gonja

README

Gonja - Jinja2-like Templating

Ignite your Go code with Jinja2-inspired magic and turbocharge your templating game!

View Docs · Report Bug · Request Feature

Table of Contents

• About
• Installation
• Synopsis
  • General Usage
  • Custom Filters and Tests
  • Custom Value Types
  • Handling of Undefined Variables
  • Extensions
  • References
    • Tests
    • Filters
    • Tags
• Roadmap
• Benchmark
• Contributing
• License
• Contact
• Acknowledgments

About

Gonja is your go-to templating engine for Go, closely resembling the beloved Python counterpart, Jinja2. Seamlessly generating dynamic content for a myriad of use cases, including web applications, email personalization, report generation and many more. Say goodbye to complex coding and hello to a simple yet flexible solution for all your content generation needs.

Features:

• Jinja2-like templating engine for Go
• Supports template inheritance, macros, filters, tests, and more
• Customizable handling of undefined variables
• Usage of custom value types
• Extensibility by creating custom filters, tests and more

back to top ⇧

Installation

go get github.com/aisbergg/gonja

back to top ⇧

Synopsis

Gonja's template syntax is mostly identical to Jinja2. Some of the included filters and tests might vary. The Jinja2 documentation is a great source for information on how to write the templates.

General Usage

• quick start
• customizing environment
  • You can find a list of all options here.
• usage of tests and filters

Custom Filters and Tests

Custom Value Types

Handling of Undefined Variables

Extensions

References

Tests

The following tests are included in Gonja:

Name	Description	Reference
callable	Return whether the object is callable (i.e., some kind of function).	Jinja2 Ref
defined	Return true if the variable is defined.	Jinja2 Ref
divisibleby	Return true if the variable is divisible by the argument.	Jinja2 Ref
eq equalto ==	Return true if the expression is equal to the argument.	Jinja2 Ref
even	Return true if the variable is even.	Jinja2 Ref
ge >=	Return true if the expression is greater than or equal to the argument.	Jinja2 Ref
gt greaterthan >	Return true if the expression is greater than the argument.	Jinja2 Ref
in	Return true if the expression is contained in the argument.	Jinja2 Ref
iterable	Return true if the variable is iterable.	Jinja2 Ref
le <=	Return true if the expression is less than or equal to the argument.	Jinja2 Ref
lower	Return a copy of the string with all the cased characters converted to lowercase.	Jinja2 Ref
lt lessthan <	Return true if the expression is less than the argument.	Jinja2 Ref
mapping	Return true if the variable is a mapping (i.e., a dictionary).	Jinja2 Ref
ne !=	Return true if the expression is not equal to the argument.	Jinja2 Ref
none	Return true if the variable is None.	Jinja2 Ref
number	Return true if the variable is a number.	Jinja2 Ref
odd	Return true if the variable is odd.	Jinja2 Ref
sameas	Return true if the expression is the same object as the argument.	Jinja2 Ref
sequence	Return true if the variable is a sequence (i.e., a list or tuple).	Jinja2 Ref
string	Return true if the variable is a string.	Jinja2 Ref
undefined	Return true if the variable is undefined.	Jinja2 Ref
upper	Return a copy of the string with all the cased characters converted to uppercase.	Jinja2 Ref

back to top ⇧

Filters

The following filters are included in Gonja:

Name	Description	Reference
abs	Return the absolute value of the argument.	Jinja2 Ref
attr	Get an attribute of an object dynamically.	Jinja2 Ref
batch	Group a sequence of objects into fixed-length chunks.	Jinja2 Ref
bool	Convert the value to a boolean.	Jinja2 Ref
boolean	Convert the value to a boolean.	Jinja2 Ref
capitalize	Capitalize the first character of a string.	Jinja2 Ref
center	Center a string in a field of a given width.	Jinja2 Ref
default d	Return a default value if the value is undefined.	Jinja2 Ref
dictsort	Sort a dictionary by key or value.	Jinja2 Ref
escape e	Escape a string for HTML rendering.	Jinja2 Ref
filesizeformat	Convert a file size to a human-readable format.	Jinja2 Ref
first	Get the first item of a sequence.	Jinja2 Ref
float	Convert the value to a floating-point number.	Jinja2 Ref
forceescape	Escape a string for HTML rendering, even if it is marked as safe.	Jinja2 Ref
format	Format a string using placeholders.	Jinja2 Ref
groupby	Group a sequence of objects by a common attribute.	Jinja2 Ref
indent	Indent a string by a given number of spaces.	Jinja2 Ref
int	Convert the value to an integer.	Jinja2 Ref
integer	Convert the value to an integer.	Jinja2 Ref
join	Join a sequence of strings with a delimiter.	Jinja2 Ref
last	Get the last item of a sequence.	Jinja2 Ref
length	Get the length of a sequence or a string.	Jinja2 Ref
list	Convert the value to a list.	Jinja2 Ref
lower	Convert a string to lowercase.	Jinja2 Ref
map	Apply a filter to each item in a sequence.	Jinja2 Ref
max	Get the maximum value in a sequence.	Jinja2 Ref
min	Get the minimum value in a sequence.	Jinja2 Ref
pprint	Pretty-print a Python object.	Jinja2 Ref
random	Get a random item from a sequence.	Jinja2 Ref
reject	Remove items from a sequence that match a condition.	Jinja2 Ref
rejectattr	Remove items from a sequence that have a certain attribute value.	Jinja2 Ref
replace	Replace occurrences of a substring with another string.	Jinja2 Ref
reverse	Reverse the order of a sequence.	Jinja2 Ref
round	Round a number to a given number of decimal places.	Jinja2 Ref
safe	Mark a string as safe for HTML rendering.	Jinja2 Ref
select	Select items from a sequence that match a condition.	Jinja2 Ref
selectattr	Select items from a sequence that have a certain attribute value.	Jinja2 Ref
slice	Get a slice of a sequence.	Jinja2 Ref
sort	Sort a sequence.	Jinja2 Ref
string	Convert the value to a string.	Jinja2 Ref
striptags	Remove HTML tags from a string.	Jinja2 Ref
sum	Get the sum of a sequence of numbers.	Jinja2 Ref
title	Convert a string to title case.	Jinja2 Ref
tojson	Convert a value to a JSON string.	Jinja2 Ref
trim	Remove whitespace from the beginning and end of a string.	Jinja2 Ref
truncate	Truncate a string to a given length.	Jinja2 Ref
unique	Remove duplicate items from a sequence.	Jinja2 Ref
upper	Convert a string to uppercase.	Jinja2 Ref
urlencode	URL-encode a string.	Jinja2 Ref
urlize	Convert URLs and email addresses in a string to clickable links.	Jinja2 Ref
wordcount	Count the number of words in a string.	Jinja2 Ref
wordwrap	Wrap a string to a given width.	Jinja2 Ref
xmlattr	Convert a dictionary to an XML attribute string.	Jinja2 Ref

back to top ⇧

Tags

back to top ⇧

Roadmap

• add comparable benchmarks; include Go built-in template engine, pongo2, liquid
• write more documentation
• write more tests
• clean up code
• optimize code and performance

Benchmark

Inside the benchmark directory reside some comparable benchmarks that allow some performance comparison of gonja with other error handling libraries. The benchmarks can be executed by running make bench. Here are my results:

cpu: AMD Ryzen 5 5600X 6-Core Processor             
BenchmarkParse-12                   9858            107232 ns/op           85165 B/op        806 allocs/op
BenchmarkExecute-12                 7198            156427 ns/op           86365 B/op       1971 allocs/op
BenchmarkParallelExecute-12        16735             73162 ns/op          110357 B/op       1981 allocs/op

back to top ⇧

Contributing

If you have any suggestions, want to file a bug report or want to contribute to this project in some other way, please read the contribution guideline.

And don't forget to give this project a star 🌟! Thanks again!

back to top ⇧

License

Distributed under the MIT License. See LICENSE for more information.

back to top ⇧

Contact

André Lehmann

• Email: aisberg@posteo.de
• GitHub
• LinkedIn

back to top ⇧

Acknowledgments

Gonja, initially developed by Axel Haustant, was built on pongo2, a template engine inspired by Django, created by Florian Schlachter. Many other awesome folks have also contributed to the code. Shoutout to all of you for doing an amazing job!

back to top ⇧