snippet

Documentation

Overview

The snippet package provides functions and types for working with snippets. A snippet is a file containing a fragment of Go code suitable to be copied into a larger program. The snippet files are annotated with semantic comments to provide documentation about the correct usage of the snippet. These semantic comments can also be interpreted to provide some checking of the correct usage.

Index

• Constants
• func AltPartNames(part string) []string
• func List(w io.Writer, dirs []string, errs *errutil.ErrMap)
• func ValidParts() map[string]string
• type Cache
  • func (c *Cache) Add(snippetDirs []string, sName string) (*S, error)
  • func (c Cache) Check(em *errutil.ErrMap)
  • func (c Cache) Get(sName string) (*S, error)
• type ListCfg
  • func NewListCfg(w io.Writer, dirs []string, errs *errutil.ErrMap, opts ...ListCfgOptFunc) (*ListCfg, error)
  • func (lc *ListCfg) List()
• type ListCfgOptFunc
  • func HideIntro(val bool) ListCfgOptFunc
  • func SetConstraints(vals ...string) ListCfgOptFunc
  • func SetParts(vals ...string) ListCfgOptFunc
  • func SetTags(vals ...string) ListCfgOptFunc
• type S
  • func (s S) Docs() []string
  • func (s S) Expects() []string
  • func (s S) Follows() []string
  • func (s S) Imports() []string
  • func (s S) Matches(other S) error
  • func (s S) Name() string
  • func (s S) Path() string
  • func (s S) String() string
  • func (s S) Tags() map[string][]string
  • func (s S) Text() []string

Constants

const (
	// these are named parts of the snippet for listing
	NamePart = "name"
	PathPart = "path"
	TextPart = "text"

	DocsPart   = "note"
	ImportPart = "imports"
	ExpectPart = "expects"
	FollowPart = "follows"
	TagPart    = "tag"

	// these correspond to semantic comments in the snippet
	CommentStr = "snippet:"
	NoteStr    = DocsPart + ":"
	ImportStr  = ImportPart + ":"
	ExpectStr  = ExpectPart + ":"
	AfterStr   = FollowPart + ":"
	TagStr     = TagPart + ":"
)

Functions

func AltPartNames

func AltPartNames(part string) []string

AltPartNames returns a slice of alternative names for the given part. Note that the slice may be empty.

func List

func List(w io.Writer, dirs []string, errs *errutil.ErrMap)

List will read all of the snippet directories and show the available snippet files. Any errors are recorded in errs.

func ValidParts

func ValidParts() map[string]string

ValidParts returns a map which has an entry for all the valid parts of a snippet with a brief description of the part and how it is used.

Types

type Cache

type Cache map[string]*S

Cache holds a collection of snippets by name

func (*Cache) Add

func (c *Cache) Add(snippetDirs []string, sName string) (*S, error)

Add will check that the snippet is not already in the cache and if not it will search for the snippet file in the snippetDirs, parse the file and generate a snippet which it will then store in the cache. It returns the snippet and any error; if the error is non-nil the snippet will be nil.

func (Cache) Check

func (c Cache) Check(em *errutil.ErrMap)

Check will check that all the snippets in the Cache have all their expected snippets also in the cache

func (Cache) Get

func (c Cache) Get(sName string) (*S, error)

Get will retrieve the named snippet from the cache, returning an error if it is not present.

type ListCfg

type ListCfg struct {
	pager.Writers
	// contains filtered or unexported fields
}

ListCfg holds the configuration for controlling the listing of snippets

func NewListCfg

func NewListCfg(w io.Writer, dirs []string,
	errs *errutil.ErrMap, opts ...ListCfgOptFunc,
) (*ListCfg, error)

NewListCfg returns a new ListCfg holding the configuration for snippet listing.

func (*ListCfg) List

func (lc *ListCfg) List()

List reads the given snippet directories (or specified files and directories) and reports them recording errors as it goes.

type ListCfgOptFunc

type ListCfgOptFunc func(lc *ListCfg) error

ListCfgOptFunc is a function which sets some part of a ListCfg structure

func HideIntro

func HideIntro(val bool) ListCfgOptFunc

HideIntro returns a ListCfgOptFunc which will set up the ListCfg value to the given value. Setting it to true will suppress the printing of the snippet part names before the values.

func SetConstraints

func SetConstraints(vals ...string) ListCfgOptFunc

SetConstraints returns a ListCfgOptFunc which will set on a ListCfg value the constraints on the snippets to be shown.

func SetParts

func SetParts(vals ...string) ListCfgOptFunc

SetParts returns a ListCfgOptFunc which will set on a ListCfg value the parts of the snippets to be shown.

func SetTags

func SetTags(vals ...string) ListCfgOptFunc

SetTags returns a ListCfgOptFunc which will set on a ListCfg value the tags of the snippets to be shown.

type S

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

S records the details of the snippet

func (S) Docs

func (s S) Docs() []string

Docs returns the documentary notes for the snippet.

func (S) Expects

func (s S) Expects() []string

Expects returns the list of other snippets that are expected to be used if this snippet is used.

func (S) Follows

func (s S) Follows() []string

Follows returns the list of other snippets that this snippet should come after in any code that uses it.

func (S) Imports

func (s S) Imports() []string

Imports returns the list of packages that are expected to be imported if this snippet is used.

func (S) Matches

func (s S) Matches(other S) error

Matches returns an error if the two snippets differ, nil otherwise

func (S) Name

func (s S) Name() string

Name returns the snippet name.

func (S) Path

func (s S) Path() string

Path returns the pathname of the file containing the snippet.

func (S) String

func (s S) String() string

String returns a string representation of the snippet

func (S) Tags

func (s S) Tags() map[string][]string

Tags returns the tags of the snippet - those comments marked as tags. Any tag text will be split around the first ':' and the first part will be used as a label for the second part.

func (S) Text

func (s S) Text() []string

Text returns the text of the snippet - every line not starting with the snippet comment (// snippet:).