examples

README

Test and Example Data

Unless correcting mistakes, do not change existing examples as this may break outside tests. (However, extending exampleInfo or updating the summary is permitted).

The Directory format is kind/format/version/collection/example_file.json.

Additional information for tests is kept in the custom meta data of the first frame in the "exampleInfo" property.

Example File Requirements:

• Must follow the directory format.
• A json file that contains an array of frames (data.Frames)
• Frames do not have a refId set.
• The first frame must have meta.custom as an object, and have the "exampleInfo" property in it.
• exampleInfo must contain:
  • "summary" (string) A description ending in a period.
  • "itemCount" (number) The number if items if a dimensional set based kind (e.g. numeric/timeseries).
  • "collectionVersion" (number) of at least 1.

When new examples are added to a collection, they should be added with the max collectionVersion number within the collection incremented by one. Existing examples should not have their collectionVersion number changed.

Documentation

Overview

Package examples provides example data dataplane contract data for testing

Index

• func SortCollectionAsc(i, j Example) (equal, less bool)
• func SortCollectionDesc(i, j Example) (equal, less bool)
• func SortCollectionVersionAsc(i, j Example) (equal, less bool)
• func SortCollectionVersionDesc(i, j Example) (equal, less bool)
• func SortFrameTypeAsc(i, j Example) (equal, less bool)
• func SortFrameTypeDesc(i, j Example) (equal, less bool)
• func SortKindAsc(i, j Example) (equal, less bool)
• func SortKindDesc(i, j Example) (equal, less bool)
• func SortPathAsc(i, j Example) (equal, less bool)
• func SortPathDesc(i, j Example) (equal, less bool)
• func SortVersionAsc(i, j Example) (equal, less bool)
• func SortVersionDesc(i, j Example) (equal, less bool)
• type Collection
  • func (c Collection) ExampleSlice() []Example
  • func (c Collection) ExamplesEqualOrLessThan(collectionVersion int) Examples
  • func (c Collection) FrameType() data.FrameType
  • func (c Collection) FrameTypeVersion() data.FrameTypeVersion
  • func (c Collection) ID() string
  • func (c Collection) MaxCollectionVersion() int
  • func (c Collection) Name() string
• type Example
  • func (e *Example) Frames(refID string) data.Frames
  • func (e *Example) Info() ExampleInfo
• type ExampleInfo
• type ExampleSortFunc
• type Examples
  • func GetExamples() (Examples, error)
  • func (e *Examples) AsSlice() []Example
  • func (e *Examples) Collections() []Collection
  • func (e *Examples) Filter(f FilterOptions) (Examples, error)
  • func (e *Examples) Sort(sorters ...ExampleSortFunc)
• type FilterOptions

Functions

func SortCollectionAsc

func SortCollectionAsc(i, j Example) (equal, less bool)

func SortCollectionDesc

func SortCollectionDesc(i, j Example) (equal, less bool)

func SortCollectionVersionAsc

func SortCollectionVersionAsc(i, j Example) (equal, less bool)

func SortCollectionVersionDesc

func SortCollectionVersionDesc(i, j Example) (equal, less bool)

func SortFrameTypeAsc

func SortFrameTypeAsc(i, j Example) (equal, less bool)

func SortFrameTypeDesc

func SortFrameTypeDesc(i, j Example) (equal, less bool)

func SortKindAsc

func SortKindAsc(i, j Example) (equal, less bool)

func SortKindDesc

func SortKindDesc(i, j Example) (equal, less bool)

func SortPathAsc

func SortPathAsc(i, j Example) (equal, less bool)

func SortPathDesc

func SortPathDesc(i, j Example) (equal, less bool)

func SortVersionAsc

func SortVersionAsc(i, j Example) (equal, less bool)

func SortVersionDesc

func SortVersionDesc(i, j Example) (equal, less bool)

Types

type Collection

type Collection Examples

func (Collection) ExampleSlice

func (c Collection) ExampleSlice() []Example

func (Collection) ExamplesEqualOrLessThan

func (c Collection) ExamplesEqualOrLessThan(collectionVersion int) Examples

func (Collection) FrameType

func (c Collection) FrameType() data.FrameType

func (Collection) FrameTypeVersion

func (c Collection) FrameTypeVersion() data.FrameTypeVersion

func (Collection) ID

func (c Collection) ID() string

ID is the unique identifier string of the collection.

func (Collection) MaxCollectionVersion

func (c Collection) MaxCollectionVersion() int

func (Collection) Name

func (c Collection) Name() string

type Example

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

Example has info about the example, and data.Frames of an example.

func (*Example) Frames

func (e *Example) Frames(refID string) data.Frames

Frames returns the example's data.Frames ([]*data.Frames) with each frame's RefID property set to refID. The frames returned may be modified without changing the example frames.

func (*Example) Info

func (e *Example) Info() ExampleInfo

Info returns the ExampleInfo from an example.

type ExampleInfo

type ExampleInfo struct {
	// Summary is a text description of data example.
	Summary string `json:"summary"`

	// ItemCount is the number of unique items in the data.
	// For example, the number of time series in a time series response.
	ItemCount int `json:"itemCount"`

	// Valid means that the example is valid according to the dataplane contract
	// and is not something that should error or warn.
	Valid bool `json:"valid"`

	// NoData means the example is a NoData example as defined in the contract.
	NoData bool `json:"noData"`

	// CollectionVersion is a unique sequence number within a collection. This allows
	// examples to be added to a collection, but consumers to be able to select not
	// to get all examples until they are ready.
	CollectionVersion int `json:"collectionVersion"`

	// This following fields are populated from areas outside the Meta.Custom["exampleInfo"] (either the frame, or containing directories)
	Type    data.FrameType        `json:"-"`
	Version data.FrameTypeVersion `json:"-"`

	// Path may change without a version change but will remain unique
	Path string `json:"-"`

	// Filename without the kind
	Name string `json:"-"`

	// Name of the collection
	CollectionName string `json:"-"`

	// ID is Type/Version/Collection/Name
	ID string
}

ExampleInfo is additional info about the example. It is a mix of info that is populated from the directories that contain the json files and from the Meta.Custom["exampleInfo"] of the first frame in each file. The Path and Summary properties should not be considered stable.

type ExampleSortFunc

type ExampleSortFunc func(i, j Example) (equal, less bool)

type Examples

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

Examples contains Examples.

func GetExamples

func GetExamples() (Examples, error)

GetExamples returns all Examples provided by this library.

func (*Examples) AsSlice

func (e *Examples) AsSlice() []Example

AsSlice returns all examples as a slice of Example ([]Example).

func (*Examples) Collections

func (e *Examples) Collections() []Collection

func (*Examples) Filter

func (e *Examples) Filter(f FilterOptions) (Examples, error)

Filter will return a new slice of Examples filtered to the Examples that match any non-zero fields in FilterOptions.

func (*Examples) Sort

func (e *Examples) Sort(sorters ...ExampleSortFunc)

type FilterOptions

type FilterOptions struct {
	Kind              data.FrameTypeKind
	Type              data.FrameType
	Version           data.FrameTypeVersion
	Collection        string
	CollectionVersion int
	Valid             *bool
	NoData            *bool
}

FilterOptions is the argument to the Examples Filter method.