Documentation
¶
Overview ¶
Package debugger provides a way for us to capture partial geometries during geometry processing. The geometries are stored in a `spatailite` database.
The general way to use the package is with a `context.Context`
variable. The package uses context as a way to pass around
the recorders, that can easily be disabled.
An example of how this would be used in a function doing work:
func Foo(ctx context.Context, ... ) (...) {
// At the top of the package we usually
// will enhance the context
if debug {
ctx = debugger.AugmentContext(ctx, "")
defer debugger.Close(ctx)
}
... // Do things till you want to record the state for
if debug {
for i, seg := ranage segments {
debugger.Record(ctx,
seg,
"A Category",
"Description Format %v", i,
)
}
}
... // more work
}
To use the package in a test, one would do something similar. In your test function, call the `debugger.SetTestName`, with the test name. The best way to do this is via the `t.Name()` function in a `testing.T` object. The `context.Context` variable will need to be Augmented as well -- the first Augment call in a chain takes precedent, so in each of your functions you can call this with no worries.
See the following example:
func TestFoo(t *testing.T){
type tcase struct {
...
}
fn := func(ctx context.Context, tc tcase) func(*testing.T){
return func(t *testing.T){
if debug {
debugger.SetTestName(ctx, t.Name())
}
...
... = Foo(...)
...
if got != tc.expected {
// record the inputs
if debug {
debugger.Record(ctx,
got,
debugger.CategoryGot,
"got segments",
)
debugger.Record(ctx,
tc.expected,
debugger.CategoryExpected,
"expected segments",
)
debugger.Record(ctx,
tc.input,
debugger.CategoryInput,
"input polygon",
)
}
}
}
}
tests := [...]tcase{ ... }
ctx := context.Background()
if debug {
ctx = debugger.AugmentContext(ctx, "")
defer debugger.Close(ctx)
}
for _, tc := range tests {
t.Run(tc.name, fn(ctx, tc))
}
}
Index ¶
- Constants
- Variables
- func AsString(vs ...interface{}) string
- func AugmentContext(ctx context.Context, testFilename string) context.Context
- func Close(ctx context.Context)
- func CloseWait(ctx context.Context)
- func Filename(ctx context.Context) string
- func FuncFileLine(lvl uint) (string, string, int)
- func NewRecorder(dir, filename string) (rcdr.Interface, string, error)
- func Record(ctx context.Context, geom interface{}, category string, ...)
- func RecordFFLOn(rec Recorder, ffl FuncFileLineType, geom interface{}, category string, ...)
- func RecordOn(rec Recorder, geom interface{}, category string, descriptionFormat string, ...)
- func SetTestName(ctx context.Context, name string) context.Context
- type CategoryFormatter
- type CategoryJoiner
- type FuncFileLineType
- type Recorder
- func (rec Recorder) AsyncRecord(geom interface{}, ffl FuncFileLineType, desc TestDescription)
- func (rec Recorder) Close() error
- func (rec Recorder) CloseWait() error
- func (rec Recorder) Closed() bool
- func (rec Recorder) IncrementCount()
- func (rec Recorder) IsValid() bool
- func (rec Recorder) Record(geom interface{}, ffl FuncFileLineType, desc TestDescription) error
- type TestDescription
Constants ¶
const ( // CategoryGot is for got values of a testcase CategoryGot = "got" // CategoryExpected is the expected values of a testcase CategoryExpected = "expected" // CategoryInput is the input values of a testcase CategoryInput = "input" )
const ( // ContextRecorderKey the key to store the recorder in the context ContextRecorderKey = "debugger_recorder_key" // ContextRecorderKey the key to store the testname in the context ContextRecorderTestnameKey = "debugger_recorder_testname_key" )
Variables ¶
var DefaultOutputDir = os.TempDir()
DefaultOutputDir is where the system will write the debugging db/files By default this will use os.TempDir() to write to the system temp directory set this in an init function to wite elsewhere.
Functions ¶
func AsString ¶
func AsString(vs ...interface{}) string
AsString will create string contains the stringified items seperated by a ':'
func AugmentContext ¶
AugmentContext is will add and configure the recorder used to track the debugging entries into the context. A Close call should be supplied along with the AugmentContext call, this is usually done using a defer If the testFilename is "", then the function name of the calling function will be used as the filename for the database file.
func Close ¶
Close allows the recorder to release any resources it as, each AugmentContext call should have a mirroring Close call that is called at the end of the function.
func Filename ¶
Filename returns the filename of the recorder in the ctx if one exists or an empty string
func FuncFileLine ¶
FuncFileLine returns the func file and line number of the the number of callers above the caller of this function. Zero returns the immediate caller above the caller of the FuncFileLine func.
func Record ¶
func Record(ctx context.Context, geom interface{}, category string, descriptionFormat string, data ...interface{})
Record records the geom and descriptive attributes into the debugging system
func RecordFFLOn ¶
func RecordFFLOn(rec Recorder, ffl FuncFileLineType, geom interface{}, category string, descriptionFormat string, data ...interface{})
RecordFFLOn records the geom and descriptive attributes into the debugging system with the give Func File Line values
Types ¶
type CategoryFormatter ¶
type CategoryFormatter string
CategoryFormatter is a helper category that will build a category made up of a set of values given with the With function. The category should be a template of where the With values will go. For example CategoryFormatter("%v_triangle_%v").With(1,10) will result in a string of `1_triangle_10` this can be used to create common category names.
func (CategoryFormatter) String ¶
func (f CategoryFormatter) String() string
func (CategoryFormatter) With ¶
func (f CategoryFormatter) With(data ...interface{}) string
type CategoryJoiner ¶
type CategoryJoiner string
CategoryJoiner is a helper category that will build a category made up of a set of values given with the With function seperated the the last character of the category. For example CategoryJoiner("triangle:").With(1,10) will result in a string of `triangle:1:10` this can be used to create common category names.
func (CategoryJoiner) String ¶
func (f CategoryJoiner) String() string
func (CategoryJoiner) With ¶
func (f CategoryJoiner) With(data ...interface{}) string
type FuncFileLineType ¶
type FuncFileLineType = recdr.FuncFileLineType
func FFL ¶
func FFL(lvl uint) FuncFileLineType
type Recorder ¶
type Recorder struct {
// Desc is the template for the description to use when recording a
// test.
Desc TestDescription
// The filename the recording are being written to, or empty
Filename string
// contains filtered or unexported fields
}
Recorder is used to record entries into the debugging database
func AugmentRecorder ¶
AugmentRecorder is will create and configure a new recorder (if needed) to be used to track the debugging entries A Close call on the recoder should be supplied along with the AugmentRecorder call, this is usually done using a defer If the testFilename is "", then the function name of the calling function will be used as the filename for the database file.
func GetRecorderFromContext ¶
GetRecorderFromContext will return the recoder that is in the context. If there isn't a recorder, then an invalid recorder will be returned. This can be checked with the IsValid() function on the recorder.
func (Recorder) AsyncRecord ¶
func (rec Recorder) AsyncRecord(geom interface{}, ffl FuncFileLineType, desc TestDescription)
AsyncRecord will record an entry into the debugging Database asynchronously. Zero values in the desc will be replaced by their corrosponding values in the Recorder.Desc
func (Recorder) Close ¶
func (rec Recorder) Close() error
Close will allows the recorder to free up any held resources
func (Recorder) CloseWait ¶
func (rec Recorder) CloseWait() error
Close will allows the recorder to free up any held resources
func (Recorder) Closed ¶
func (rec Recorder) Closed() bool
Closed will report if the database is available for writing
func (Recorder) IncrementCount ¶
func (rec Recorder) IncrementCount()
IncrementCount used for reference counting for when to release resources; each thing holding a copy of this resource should call this if it intends to call Close()
func (Recorder) Record ¶
func (rec Recorder) Record(geom interface{}, ffl FuncFileLineType, desc TestDescription) error
Record will record an entry into the debugging Database. Zero values in the desc will be replaced by their corrosponding values in the Recorder.Desc
type TestDescription ¶
type TestDescription = recdr.TestDescription
Source Files
Directories