frontmatter

README

frontmatter

Go library for detecting and decoding various content front matter formats.

Supported formats

The following front matter formats are supported by default. If the default formats are not suitable for your use case, you can easily bring your own. For more information, see the usage examples below.

Installation

go get github.com/adrg/frontmatter

Usage

Default usage.

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/frontmatter"
)

var input = `
---
name: "frontmatter"
tags: ["go", "yaml", "json", "toml"]
---
rest of the content`

func main() {
	var matter struct {
		Name string   `yaml:"name"`
		Tags []string `yaml:"tags"`
	}

	rest, err := frontmatter.Parse(strings.NewReader(input), &matter)
	if err != nil {
		// Treat error.
	}
	// NOTE: If a front matter must be present in the input data, use
	//       frontmatter.MustParse instead.

	fmt.Printf("%+v\n", matter)
	fmt.Println(string(rest))

	// Output:
	// {Name:frontmatter Tags:[go yaml json toml]}
	// rest of the content
}

Bring your own formats.

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/frontmatter"
	"gopkg.in/yaml.v2"
)

var input = `
...
name: "frontmatter"
tags: ["go", "yaml", "json", "toml"]
...
rest of the content`

func main() {
	var matter struct {
		Name string   `yaml:"name"`
		Tags []string `yaml:"tags"`
	}

	formats := []*frontmatter.Format{
		frontmatter.NewFormat("...", "...", yaml.Unmarshal),
	}

	rest, err := frontmatter.Parse(strings.NewReader(input), &matter, formats...)
	if err != nil {
		// Treat error.
	}
	// NOTE: If a front matter must be present in the input data, use
	//       frontmatter.MustParse instead.

	fmt.Printf("%+v\n", matter)
	fmt.Println(string(rest))

	// Output:
	// {Name:frontmatter Tags:[go yaml json toml]}
	// rest of the content
}

Full documentation can be found at: https://pkg.go.dev/github.com/adrg/frontmatter.

Stargazers over time

Contributing

Contributions in the form of pull requests, issues or just general feedback, are always welcome. See CONTRIBUTING.MD.

Buy me a coffee

If you found this project useful and want to support it, consider buying me a coffee.

License

Copyright (c) 2020 Adrian-George Bostan.

This project is licensed under the MIT license. See LICENSE for more details.

Documentation

Overview

Package frontmatter implements detection and decoding for various content front matter formats.

The following front matter formats are supported by default.

- YAML identified by:
  • opening and closing `---` lines.
  • opening `---yaml` and closing `---` lines.
- TOML identified by:
  • opening and closing `+++` lines.
  • opening `---toml` and closing `---` lines.
- JSON identified by:
  • opening and closing `;;;` lines.
  • opening `---json` and closing `---` lines.
  • a single JSON object followed by an empty line.

If the default formats are not suitable for your use case, you can easily bring your own. See the examples for more information.

Index

• Variables
• func MustParse(r io.Reader, v interface{}, formats ...*Format) ([]byte, error)
• func Parse(r io.Reader, v interface{}, formats ...*Format) ([]byte, error)
• type Format
  • func NewFormat(start, end string, unmarshal UnmarshalFunc) *Format
• type UnmarshalFunc

Examples

• Parse (Custom)
• Parse (JSON)
• Parse (TOML)
• Parse (YAML)

Variables

var ErrNotFound = errors.New("not found")

ErrNotFound is reported by `MustParse` when a front matter is not found.

Functions

func MustParse

func MustParse(r io.Reader, v interface{}, formats ...*Format) ([]byte, error)

MustParse decodes the front matter from the specified reader into the value pointed to by `v`, and returns the rest of the data. If a front matter is not present, `ErrNotFound` is reported. Front matters are detected and decoded based on the passed in `formats`. If no formats are provided, the default formats are used.

func Parse

func Parse(r io.Reader, v interface{}, formats ...*Format) ([]byte, error)

Parse decodes the front matter from the specified reader into the value pointed to by `v`, and returns the rest of the data. If a front matter is not present, the original data is returned and `v` is left unchanged. Front matters are detected and decoded based on the passed in `formats`. If no formats are provided, the default formats are used.

Example (Custom)

r := strings.NewReader(`
...
name: "frontmatter"
tags: ["go", "yaml", "json", "toml"]
...
rest of the content`)

var matter struct {
	Name string   `yaml:"name"`
	Tags []string `yaml:"tags"`
}

formats := []*frontmatter.Format{
	frontmatter.NewFormat("...", "...", yaml.Unmarshal),
}

rest, err := frontmatter.Parse(r, &matter, formats...)
if err != nil {
	// Treat error.
}
// NOTE: If a front matter must be present in the input data, use
//       frontmatter.MustParse instead.

fmt.Printf("%+v\n", matter)
fmt.Println(string(rest))

Output:

{Name:frontmatter Tags:[go yaml json toml]}
rest of the content

Example (JSON)

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/frontmatter"
)

func main() {
	r := strings.NewReader(`
{
  "name": "frontmatter",
  "tags": ["go", "yaml", "json", "toml"]
}

rest of the content`)

	var matter struct {
		Name string   `yaml:"name" toml:"name" json:"name"`
		Tags []string `yaml:"tags" toml:"tags" json:"tags"`
	}

	rest, err := frontmatter.Parse(r, &matter)
	if err != nil {
		// Treat error.
	}
	// NOTE: If a front matter must be present in the input data, use
	//       frontmatter.MustParse instead.

	fmt.Printf("%+v\n", matter)
	fmt.Println(string(rest))

}

Output:

{Name:frontmatter Tags:[go yaml json toml]}
rest of the content

Example (TOML)

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/frontmatter"
)

func main() {
	r := strings.NewReader(`
+++
name = "frontmatter"
tags = ["go", "yaml", "json", "toml"]
+++
rest of the content`)

	var matter struct {
		Name string   `yaml:"name" toml:"name" json:"name"`
		Tags []string `yaml:"tags" toml:"tags" json:"tags"`
	}

	rest, err := frontmatter.Parse(r, &matter)
	if err != nil {
		// Treat error.
	}
	// NOTE: If a front matter must be present in the input data, use
	//       frontmatter.MustParse instead.

	fmt.Printf("%+v\n", matter)
	fmt.Println(string(rest))

}

Output:

{Name:frontmatter Tags:[go yaml json toml]}
rest of the content

Example (YAML)

package main

import (
	"fmt"
	"strings"

	"github.com/adrg/frontmatter"
)

func main() {
	r := strings.NewReader(`
---
name: "frontmatter"
tags: ["go", "yaml", "json", "toml"]
---
rest of the content`)

	var matter struct {
		Name string   `yaml:"name" toml:"name" json:"name"`
		Tags []string `yaml:"tags" toml:"tags" json:"tags"`
	}

	rest, err := frontmatter.Parse(r, &matter)
	if err != nil {
		// Treat error.
	}
	// NOTE: If a front matter must be present in the input data, use
	//       frontmatter.MustParse instead.

	fmt.Printf("%+v\n", matter)
	fmt.Println(string(rest))

}

Output:

{Name:frontmatter Tags:[go yaml json toml]}
rest of the content

Types

type Format

type Format struct {
	// Start defines the starting delimiter of the front matter.
	// E.g.: `---` or `---yaml`.
	Start string

	// End defines the ending delimiter of the front matter.
	// E.g.: `---`.
	End string

	// Unmarshal defines the unmarshal function used to decode
	// the front matter data, after it has been detected.
	// E.g.: json.Unmarshal (from the `encoding/json` package).
	Unmarshal UnmarshalFunc

	// UnmarshalDelims specifies whether the front matter
	// delimiters are included in the data to be unmarshaled.
	// Should be `false` in most cases.
	UnmarshalDelims bool

	// RequiresNewLine specifies whether a new (empty) line is
	// required after the front matter.
	// Should be `false` in most cases.
	RequiresNewLine bool
}

Format describes a front matter. It holds all the information necessary in order to detect and decode a front matter format.

func NewFormat

func NewFormat(start, end string, unmarshal UnmarshalFunc) *Format

NewFormat returns a new front matter format.

type UnmarshalFunc

type UnmarshalFunc func(data []byte, v interface{}) error

UnmarshalFunc decodes the passed in `data` and stores it into the value pointed to by `v`.