particle

README

Particle

Particle is a go library that provides an Encoder/Decoder and Marshaler/Unmarshaler for frontmatter files.

A frontmatter file contains a block of metadata at the beginning of the file. This block is usually delimited by a --- or +++, as defined by Jekyll, however JSON may be included without a specific delimiter.

The Particle library can decode and encode frontmatter metadata blocks that are YAML, TOML or JSON. It is also a generic library so it's easy to define new custom block types to decode and encode as well.

See the GoDoc for more information.

Installation

go get github.com/njones/particle

Example of how to pull data from a frontmatter data string

package main

import (
  "fmt"

  "github.com/njones/particle"
)

var jsonFrontmatterFile = `
{
  "title":"front-matter example"
}

This is some example text
`

func main() {
  
  metadata := struct {
    Title string
  }{}

  body, err := particle.JSONEncoding.DecodeString(jsonFrontmatterFile, &metadata)
  if err != nil {
    // handle err
  }

  fmt.Println("Frontmatter metadata: %#v", metadata)
  fmt.Println("File body: %s", string(body))

}

Example of creating a frontmatter data string

package main

import (
  "fmt"

  "github.com/njones/particle"
)

func main() {
  
  metadata := struct {
    Title string
  }{
    Title: "front-matter example"
  }

  body := particle.JSONEncoding.EncodeToString([]byte("This is some example text\n"), &metadata)

  fmt.Println("File body: %s", body)

}

This package depends on the following external encoding/decoding libraries:

• http://gopkg.in/yaml.v2
• https://github.com/BurntSushi/toml

Note that the standard marshaling/unmarshaling function signatures can be used i.e func(interface{}) ([]byte error) and func([]byte, interface{}) error for the encoding and decoding of the frontmatter metadata.

License

Particle is available under the MIT License.

Copyright (c) 2016 Nika Jones copyright@nikajon.es All Rights Reserved.

Documentation

Overview

Package particle implements frontmatter encoding as specified by the Jekyll specification.

Index

• Constants
• Variables
• func NewDecoder(e *Encoding, r io.Reader, v interface{}) (io.Reader, error)
• func NewEncoder(e *Encoding, w io.Writer, v interface{}) (io.Writer, error)
• type Encoding
  • func NewEncoding(options ...EncodingOptionFunc) *Encoding
  • func (e *Encoding) Decode(dst, src []byte, v interface{}) (int, error)
  • func (e *Encoding) DecodeReader(r io.Reader, v interface{}) ([]byte, error)
  • func (e *Encoding) DecodeString(src string, v interface{}) ([]byte, error)
  • func (e *Encoding) Encode(dst, src []byte, v interface{})
  • func (e *Encoding) EncodeLen(src []byte, v interface{}) int
  • func (e *Encoding) EncodeToString(src []byte, v interface{}) string
• type EncodingOptionFunc
  • func WithDelimiter(s string) EncodingOptionFunc
  • func WithIncludeDelimiter() EncodingOptionFunc
  • func WithMarshalFunc(fn MarshalFunc) EncodingOptionFunc
  • func WithSplitFunc(fn SplitFunc) EncodingOptionFunc
  • func WithUnmarshalFunc(fn UnmarshalFunc) EncodingOptionFunc
• type MarshalFunc
• type SplitFunc
• type Splitter
  • func SingleTokenDelimiter(delim string) Splitter
  • func SpaceSeparatedTokenDelimiters(delim string) Splitter
• type UnmarshalFunc

Examples

• Encoding.DecodeString
• Encoding.EncodeToString
• NewDecoder
• NewEncoder

Constants

const (
	YAMLDelimiter     = "---"
	TOMLDelimiter     = "+++"
	JSONDelimiterPair = "{ }"
)

Variables

var JSONEncoding = NewEncoding(
	WithDelimiter(JSONDelimiterPair),
	WithMarshalFunc(jsonMarshal),
	WithUnmarshalFunc(json.Unmarshal),
	WithSplitFunc(SpaceSeparatedTokenDelimiters),
	WithIncludeDelimiter(),
)

JSONEncoding is the encoding for frontmatter files that use JSON as the metadata format, note there is no delimiter, just use a single open and close curly bracket on a line to designate the JSON frontmatter metadata block.

var TOMLEncoding = NewEncoding(
	WithDelimiter(TOMLDelimiter),
	WithMarshalFunc(tomlMarshal),
	WithUnmarshalFunc(toml.Unmarshal),
)

TOMLEncoding is the encoding for frontmatter files that use TOML as the metadata format.

var YAMLEncoding = NewEncoding(
	WithDelimiter(YAMLDelimiter),
	WithMarshalFunc(yaml.Marshal),
	WithUnmarshalFunc(yaml.Unmarshal),
)

YAMLEncoding is the encoding for standard frontmatter files that use YAML as the metadata format.

Functions

func NewDecoder

func NewDecoder(e *Encoding, r io.Reader, v interface{}) (io.Reader, error)

NewDecoder constructs a new frontmatter stream decoder, adding the marshaled frontmatter metadata to interface v.

Example

// Setup the struct and reader...
v := struct{ Name string }{}
r := strings.NewReader(`---
name: A NewDecoder Example
---

Content...`)

// Do the decoding...
output, err := NewDecoder(YAMLEncoding, r, &v)
if err != nil {
	// handle errors here
	fmt.Println(err)
}

// Read the content to a buffer so we can see it...
content := new(bytes.Buffer)
content.ReadFrom(output)

fmt.Printf("yaml: %+v\ncontent: %s", v, content)

Output:

yaml: {Name:A NewDecoder Example}
content: Content...

func NewEncoder

func NewEncoder(e *Encoding, w io.Writer, v interface{}) (io.Writer, error)

NewEncoder returns a new frontmatter stream encoder. Data written to the returned writer will be prefixed with the encoded frontmatter metadata using e and then written to w.

Example

// Setup the struct and reader...
v := struct{ Name string }{Name: "A NewEncoder Example"}
w := new(bytes.Buffer)

// Do the encoding...
out, err := NewEncoder(YAMLEncoding, w, v)
if err != nil {
	// handle errors here
	fmt.Println(err)
}

// Writing to the writer that we got back from the NewEncoder function
out.Write([]byte("Content..."))

// view the raw bytes
fmt.Printf("content: % x", w.String())

Output:

content: 2d 2d 2d 0a 6e 61 6d 65 3a 20 41 20 4e 65 77 45 6e 63 6f 64 65 72 20 45 78 61 6d 70 6c 65 0a 2d 2d 2d 0a 0a 43 6f 6e 74 65 6e 74 2e 2e 2e

Types

type Encoding

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

Encoding is the set of options that determine the marshaling and unmarshaling encoding specifications of frontmatter metadata.

func NewEncoding

func NewEncoding(options ...EncodingOptionFunc) *Encoding

NewEncoding returns a new Encoding defined by the any passed in options. All options can be changed by passing in the appropriate EncodingOptionFunc option.

func (*Encoding) Decode

func (e *Encoding) Decode(dst, src []byte, v interface{}) (int, error)

Decode decodes src using the encoding e. It writes bytes to dst and returns the number of bytes written. If src contains invalid unmarshaled data, it will return the number of bytes successfully written along with an error.

func (*Encoding) DecodeReader

func (e *Encoding) DecodeReader(r io.Reader, v interface{}) ([]byte, error)

DecodeReader returns the bytes representing the data collected from reader r without frontmatter metadata. The interface v will contain the decoded frontmatter metadata.

func (*Encoding) DecodeString

func (e *Encoding) DecodeString(src string, v interface{}) ([]byte, error)

DecodeString returns the bytes representing the string data of src without the frontmatter. The interface v will contain the decoded frontmatter metadata. It returns an error if the underlining marshaler returns an error.

Example

// Setup the struct and reader...
v := struct{ Name string }{}
src := `+++
name = "A DecodeString Example"
+++

Content...`

// Do the decoding...
b, err := TOMLEncoding.DecodeString(src, &v)
if err != nil {
	// handle errors here
	fmt.Println(err)
}

// Read the content to a buffer so we can see it...
content := string(b)

fmt.Printf("toml: %+v\ncontent: %s", v, content)

Output:

toml: {Name:A DecodeString Example}
content: Content...

func (*Encoding) Encode

func (e *Encoding) Encode(dst, src []byte, v interface{})

Encode encodes src using the encoding e, writing EncodedLen(len(encoded frontmatter)+len(src)) bytes to dst.

func (*Encoding) EncodeLen

func (e *Encoding) EncodeLen(src []byte, v interface{}) int

EncodedLen returns the length in bytes of the frontmatter encoding of an input buffer and frontmatter metadata of interface i of length n.

func (*Encoding) EncodeToString

func (e *Encoding) EncodeToString(src []byte, v interface{}) string

EncodeToString returns the frontmatter encoding of type e Encoding before the data bytes of src populated with the data of interface v.

Example

// Setup the struct and reader...
v := struct{ Name string }{Name: "A EncodeToString Example"}
src := []byte("Content...")

// Do the decoding...
content := JSONEncoding.EncodeToString(src, &v)

// view the raw bytes
fmt.Printf("content: % x", content)

Output:

content: 7b 0a 09 22 4e 61 6d 65 22 3a 20 22 41 20 45 6e 63 6f 64 65 54 6f 53 74 72 69 6e 67 20 45 78 61 6d 70 6c 65 22 0a 7d 0a 0a 43 6f 6e 74 65 6e 74 2e 2e 2e

type EncodingOptionFunc

type EncodingOptionFunc func(*Encoding) error

The EncodingOptionFunc type the function signature for adding encoding options to the formatter.

func WithDelimiter

func WithDelimiter(s string) EncodingOptionFunc

WithDelimiter adds the string delimiter to designate frontmatter encoded metadata section to *Encoding

func WithIncludeDelimiter

func WithIncludeDelimiter() EncodingOptionFunc

WithIncludeDelimiter is a bool that includes the delimiter in the frontmatter metadata for *Encoding

func WithMarshalFunc

func WithMarshalFunc(fn MarshalFunc) EncodingOptionFunc

WithMarshalFunc adds the MarshalFunc function that will marshal a struct or map to frontmatter encoded metadata string *Encoding

func WithSplitFunc

func WithSplitFunc(fn SplitFunc) EncodingOptionFunc

WithSplitFunc adds the SplitFunc function to *Encoding

func WithUnmarshalFunc

func WithUnmarshalFunc(fn UnmarshalFunc) EncodingOptionFunc

WithUnmarshalFunc adds the UnmarshalFunc function that will unmarshal the frontmatter encoded metadata to a struct or map to *Encoding

type MarshalFunc

type MarshalFunc func(interface{}) ([]byte, error)

The MarshalFunc type is the standard unmarshal function that maps a struct or map to frontmatter encoded byte string.

type SplitFunc

type SplitFunc func(string) Splitter

The SplitFunc type returns the open and close delimiters, along with a bufio.SplitFunc that will be used to parse the frontmatter file.

type Splitter

type Splitter struct {
	Start, End string
	SplitFunc  bufio.SplitFunc
}

Splitter holds the start and end delimiter used for splitting out frontmatter encoded metadata from a stream. It holds the bufio.SplitFunc to scan over the input. The baseSplitter default function should be enough for most use cases.

func SingleTokenDelimiter

func SingleTokenDelimiter(delim string) Splitter

SingleTokenDelimiter returns the start and end delimiter as delim.

func SpaceSeparatedTokenDelimiters

func SpaceSeparatedTokenDelimiters(delim string) Splitter

SpaceSeparatedTokenDelimiters returns the start and end delimiter which is split on a space from delim.

type UnmarshalFunc

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

The UnmarshalFunc type is the standard marshal function that maps frontmatter encoded metadata to a struct or map.