corpus

Documentation

Overview

Package corpus concerns test corpora (collections of named subjects).

Index

• Variables
• func MergedName(cname, sname string) string
• func MockFailedCompile(name string) *subject.Subject
• func MockFlaggedRun(name string) *subject.Subject
• func MockRecipe(dir string) recipe.Recipe
• func MockSuccessfulCompile(cstr string, sname string) compilation.CompileResult
• func MockTimeoutRun(name string) *subject.Subject
• type Corpus
  • func Merge(corpora map[string]Corpus) (Corpus, error)
  • func Mock() Corpus
  • func New(names ...string) Corpus
  • func (c Corpus) Add(s subject.Named) error
  • func (c Corpus) Copy() Corpus
  • func (c Corpus) Each(f func(subject.Named) error) error
  • func (c Corpus) EraseCompilations()
  • func (c Corpus) FilterToNames(names ...string) Corpus
  • func (c Corpus) Map(f func(*subject.Named) error) error
  • func (c Corpus) Names() []string
  • func (c Corpus) Par(ctx context.Context, nworkers int, ...) error
  • func (c Corpus) Sample(rng *rand.Rand, want int) (Corpus, error)

Examples

• Corpus.Add
• Corpus.Each
• Corpus.FilterToNames
• Merge

Variables

var (
	// ErrCorpusDup occurs when we try to Add a subject into a corpus under a name that is already taken.
	ErrCorpusDup = errors.New("duplicate corpus entry")

	// ErrMapRename occurs when we try to change the name of an entry inside a Map.
	ErrMapRename = errors.New("tried to rename a corpus entry")

	// ErrSmall occurs when the viable test corpus is smaller than that requested by the user.
	ErrSmall = errors.New("test corpus too small")

	// ErrNone is a variant of ErrSmall that occurs when the viable test corpus is empty.
	ErrNone = fmt.Errorf("%w: no corpus given", ErrSmall)
)

Functions

func MergedName

func MergedName(cname, sname string) string

MergedName is the name that sname will appear under in a merged corpus where the original corpus name was cname.

func MockFailedCompile

func MockFailedCompile(name string) *subject.Subject

MockFailedCompile expands to a realistic looking subject that contains a failed compilation.

func MockFlaggedRun

func MockFlaggedRun(name string) *subject.Subject

MockFlaggedRun expands to a realistic looking subject that contains some flagged runs.

func MockRecipe

func MockRecipe(dir string) recipe.Recipe

MockRecipe constructs a mock recipe at dir.

func MockSuccessfulCompile

func MockSuccessfulCompile(cstr string, sname string) compilation.CompileResult

MockSuccessfulCompile generates a mock CompileResult for a successful compile of subject sname with compiler cstr.

func MockTimeoutRun

func MockTimeoutRun(name string) *subject.Subject

MockTimeoutRun expands to a realistic looking subject that contains some timed-out runs.

Types

type Corpus

type Corpus map[string]subject.Subject

Corpus is the type of test corpora (groups of test subjects).

func Merge

func Merge(corpora map[string]Corpus) (Corpus, error)

Merge merges corpora into a single corpus. If corpora is empty or nil, it returns nil. If there is only one corpus in corpora, it just deep-copies that corpus. Otherwise, it produces a new corpus with each subject's name prefixed by its corpus's name in corpora.

Example

ExampleMerge is a testable example for Merge.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/subject/corpus"
)

func main() {
	c1 := corpus.New("foo", "bar", "baz")
	c2 := corpus.New("foo", "bar", "baz")

	// Empty merge
	c3, _ := corpus.Merge(map[string]corpus.Corpus{})
	for n := range c3 {
		fmt.Println("empty>", n)
	}

	// Single merge
	c4, _ := corpus.Merge(map[string]corpus.Corpus{"c1": c1})
	for n := range c4 {
		fmt.Println("single>", n)
	}

	// Multi merge
	c5, _ := corpus.Merge(map[string]corpus.Corpus{"c1": c1, "c2": c2})
	for n := range c5 {
		fmt.Println("multi>", n)
	}

}

Output:

single> foo
single> bar
single> baz
multi> c1/foo
multi> c1/bar
multi> c1/baz
multi> c2/foo
multi> c2/bar
multi> c2/baz

func Mock

func Mock() Corpus

Mock produces a representative corpus including the following features: - a subject with a failed compilation; - a subject with a flagged observation.

func New

func New(names ...string) Corpus

New creates a blank Corpus from a list of names.

func (Corpus) Add

func (c Corpus) Add(s subject.Named) error

Add tries to add s to the corpus. It fails if the corpus already has a subject with the given name.

Example

ExampleCorpus_Add is a runnable example for Add.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/model/litmus"

	"github.com/c4-project/c4t/internal/subject/corpus"

	"github.com/c4-project/c4t/internal/subject"
)

func main() {
	c := make(corpus.Corpus)
	_ = c.Add(*subject.NewOrPanic(litmus.NewOrPanic("bar/baz.litmus")).AddName("foo"))
	fmt.Println(c["foo"].Source.Path)

	// We can't add duplicates to a corpus.
	err := c.Add(*subject.NewOrPanic(litmus.NewOrPanic("bar/baz2.litmus")).AddName("foo"))
	fmt.Println(err)

}

Output:

bar/baz.litmus
duplicate corpus entry: foo

func (Corpus) Copy

func (c Corpus) Copy() Corpus

Copy makes a deep copy of this corpus.

func (Corpus) Each

func (c Corpus) Each(f func(subject.Named) error) error

Each applies f to each subject in the corpus. It fails if any invocation of f fails.

Example

ExampleCorpus_Each is a runnable example for Each.

package main

import (
	"fmt"
	"sort"

	"github.com/c4-project/c4t/internal/subject"
	"github.com/c4-project/c4t/internal/subject/corpus"
)

func main() {
	// A perhaps less efficient version of c.Names():

	c := corpus.New("foo", "bar", "baz", "barbaz")
	names := make([]string, 0, len(c))

	_ = c.Each(func(s subject.Named) error {
		names = append(names, s.Name)
		return nil
	})

	sort.Strings(names)
	for _, n := range names {
		fmt.Println(n)
	}

}

Output:

bar
barbaz
baz
foo

func (Corpus) EraseCompilations

func (c Corpus) EraseCompilations()

EraseCompilations deletes the compilation entries for each subject in c.

func (Corpus) FilterToNames

func (c Corpus) FilterToNames(names ...string) Corpus

FilterToNames filters c to contain only subjects whose names are contained within names.

Example

ExampleCorpus_FilterToNames is a runnable example for Corpus.FilterToNames.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/subject/corpus"
)

func main() {
	c := corpus.Mock()

	for _, n := range c.Names() {
		fmt.Println(n, "is in c")
	}

	c2 := c.FilterToNames("foo", "bar")
	for _, n := range c2.Names() {
		fmt.Println(n, "is in c2")
	}

	c3 := c.FilterToNames()
	for _, n := range c3.Names() {
		fmt.Println(n, "is in c3")
	}

}

Output:

bar is in c
barbaz is in c
baz is in c
foo is in c
bar is in c2
foo is in c2

func (Corpus) Map

func (c Corpus) Map(f func(*subject.Named) error) error

Map sequentially maps f over the subjects in this corpus. It passes each invocation of f a pointer to a copy of a subject, but propagates any changes made to that copy back to the corpus. It does not permit making changes to the name.

func (Corpus) Names

func (c Corpus) Names() []string

Names returns a sorted list of this corpus's subject names.

func (Corpus) Par

func (c Corpus) Par(ctx context.Context, nworkers int, f func(context.Context, subject.Named) error, aux ...func(context.Context) error) error

Par runs f for every subject in the plan's corpus, with a degree of parallelism. It threads through a context that will terminate each machine if an error occurs on some other machine. It also takes zero or more 'auxiliary' funcs to launch within the same context.

func (Corpus) Sample

func (c Corpus) Sample(rng *rand.Rand, want int) (Corpus, error)

Sample tries to select a sample of size want from this corpus. If want is non-positive, or the corpus is smaller than want, no sampling occurs.