markstruct

README

markstruct

markstruct converts a struct's string fields from Markdown to HTML in-place.

markstruct scans a struct for tagged fields of relevant type (string, *string, []string & maps with string values), and renders the field value from Markdown to HTML in-place. That is to say the value of each field itself will be changed within the struct to be the HTML result of rendering the original value as Markdown.

markstruct uses github.com/yuin/goldmark to render Markdown, and allows for custom goldmark.Markdown objects and parse options.

Installation

go get github.com/herbygillot/markstruct

Usage

ConvertFields accepts a pointer to struct, and converts fields of relevant type (as listed above) from Markdown to HTML that are tagged with markdown:"on":

type Document struct {
  Title string                 // this field will be ignored
  Body  string `markdown:"on"` // this field will be converted
}

 doc := &Document{
     Title: "Doc *1*",
     Body:  "This is _emphasis_.",
 }

 changed, err := markstruct.ConvertFields(doc)
 ...
 fmt.Println(doc.Title) // "Doc *1*"
 fmt.Println(doc.Body)  // "<p>This is <em>emphasis</em>.</p>"

ConvertAllFields also accepts a pointer to struct, but will convert all fields of relevant type, ignoring the absence or presence of the markdown:"on" tag.

type Document struct {
  Title string                 // normally ignored, but will be converted by ConvertAllFields
  Body  string `markdown:"on"` // this field will be converted
}

 doc := &Document{
     Title: "Doc *1*",
     Body:  "This is _emphasis_.",
 }

 changed, err := markstruct.ConvertAllFields(doc)
 ...
 fmt.Println(doc.Title) // "<p>Doc <em>1</em></p>"
 fmt.Println(doc.Body)  // "<p>This is <em>emphasis</em>.</p>"

There are equivalent functions, ValidateFields and ValidateAllFields, that can be used to check if errors would occur during conversion, making no changes to the target struct. They return the exact same values as ConverFields and ConvertAllFields, respectively.

Documentation

Overview

Package markstruct converts a struct's string fields from Markdown to HTML in-place.

markstruct will take a pointer to a struct, and scan for tagged string fields, then render the value of these fields as Markdown to HTML in-place. That is to say the value of each field itself will be changed within the struct to be the HTML result of rendering the original field's value as Markdown. markstruct targets fields whose type are string, pointer to string, string slice, and maps with string values. markstruct uses `github.com/yuin/goldmark` to render Markdown, and allows for custom goldmark.Markdown objects and parse options.

Fields within a struct that should be converted should be annotated with the tag `markdown:"on"`

Example:

 type Document struct {
   Title string                 // this field will be ignored
   Body  string `markdown:"on"` // this field will be converted
 }

  doc := &Document{
	  Title: "Doc *1*",
	  Body:  "This is _emphasis_.",
  }

  changed, err := markstruct.ConvertFields(doc)
  ...
  fmt.Println(doc.Title) // "Doc *1*"
  fmt.Println(doc.Body)  // "<p>This is <em>emphasis</em>.</p>"

markstruct can optionally modify all struct string fields unequivocally, ignoring the presence of this tag.

Index

• Variables
• func ConvertAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)
• func ConvertFields(s interface{}, opts ...parser.ParseOption) (bool, error)
• func ValidateAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)
• func ValidateFields(s interface{}, opts ...parser.ParseOption) (bool, error)
• type FieldConverter
  • func WithMarkdown(md goldmark.Markdown) FieldConverter

Variables

var (
	// ErrInvalidType signifies that we have received a value of type other
	// than the expected pointer to struct.
	ErrInvalidType = errors.New("invalid type")
)

Functions

func ConvertAllFields

func ConvertAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)

ConvertAllFields does the same as ConvertFields, except it will convert all fields of relevant type within a struct, regardless of whether the field is tagged with `markdown:"on"` or not. ConvertAllFields also optionally accepts `goldmark` ParseOptions which are used to modify Markdown parsing during conversion.

Just like ConvertFields, ConvertAllFields only accepts a pointer to a struct, and returns a boolean signifying whether the struct was changed, as well as any error encountered.

Passing a value of any type other than a pointer to struct will cause ConvertAllFields to return an ErrInvalidType error.

func ConvertFields

func ConvertFields(s interface{}, opts ...parser.ParseOption) (bool, error)

ConvertFields accepts a pointer to a struct, and will modify tagged fields of relevant type within the struct by replacing each field with its contents rendered from Markdown to HTML. ConvertFields returns a boolean signifying whether changes were made to the struct or not, as well as any error encountered. If given any other type besides a pointer to a struct, ConvertFields will return an ErrInvalidType error.

ConvertFields optionally accepts ParseOptions, which are passed to `goldmark` to modify Markdown parsing during conversion.

Fields that should be converted within the struct should be tagged with `markdown:"on"`:

type Document struct {
  Title string
  Body  string `markdown:"on"`
}

ConvertFields supports struct fields of type string, *string, []string, and maps with string values.

func ValidateAllFields

func ValidateAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)

ValidateAllFields behaves like ConvertAllFields, except that it makes no changes to a struct. ValidateAllFields can be used to test for errors in a situation where ConvertAllFields would be used. ValidateAllFields returns the same return values as ConvertAllFields.

func ValidateFields

func ValidateFields(s interface{}, opts ...parser.ParseOption) (bool, error)

ValidateFields will, like ConvertFields, accept a pointer to a struct whose string fields are expected to be tagged with `markdown:"on"`. Unlike ConvertFields, ValidateFields makes no changes to the struct or its fields. ValidateFields returns the same values as ConvertFields: a boolean indicating whether fields would have been changed, as well as any error encountered.

Types

type FieldConverter

type FieldConverter interface {
	ConvertFields(s interface{}, opts ...parser.ParseOption) (bool, error)

	ConvertAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)

	ValidateFields(s interface{}, opts ...parser.ParseOption) (bool, error)

	ValidateAllFields(s interface{}, opts ...parser.ParseOption) (bool, error)
}

FieldConverter converts the content of string (and other string-related type) fields within a struct from Markdown to HTML in-place.

func WithMarkdown

func WithMarkdown(md goldmark.Markdown) FieldConverter

WithMarkdown creates a FieldConverter from a custom `goldmark.Markdown` object. Use this with `goldmark.New` to allow using markstruct with non-default `goldmark` extensions or configuration.