Start sketching on documentation and shaping up/restructuring the API where needed

Author: tobgu

aggregation/strings.go

@@ -2,6 +2,10 @@ package aggregation
 
 import "strings"
 
+// StrJoin creates a function that joins a slice of strings into
+// a single string using the provided separator.
+// It is provided as an example and can be used in aggregations
+// on string and enum columns.
 func StrJoin(sep string) func([]*string) *string {
 	return func(input []*string) *string {
 		s := make([]string, 0, len(input))

doc.go

@@ -0,0 +1,4 @@
+/*
+qframe is...
+*/
+package qframe

expression.go

@@ -10,11 +10,6 @@ import (
 	"strconv"
 )
 
-// TODO
-// - Auto cast int -> float for operations on float columns where the operand is an int?
-// - Tests
-// - Review all public QFrame functions so that they contain guards against Err execution.
-
 type functionsByArgCount struct {
 	singleArgs map[string]interface{}
 	doubleArgs map[string]interface{}
@@ -123,6 +118,7 @@ func (ctx *ExprCtx) setFunc(typ types.FunctionType, ac argCount, name string, fn
 	}
 }
 
+// TODO-C
 func (ctx *ExprCtx) SetFunc(name string, fn interface{}) error {
 	// Since there's such a flexibility in the function types that can be
 	// used and there is no static typing to support it this function
@@ -185,7 +181,7 @@ type Expression interface {
 	Err() error
 }
 
-func NewExpr(expr interface{}) Expression {
+func newExpr(expr interface{}) Expression {
 	// Try, in turn, to decode expr into a valid expression type.
 	if e, ok := expr.(Expression); ok {
 		return e
@@ -247,6 +243,7 @@ func (e colExpr) execute(qf QFrame, _ *ExprCtx) (QFrame, string) {
 	return qf, e.srcCol
 }
 
+// TODO-C
 func (e colExpr) Err() error {
 	return nil
 }
@@ -441,12 +438,12 @@ func newExprExpr(x interface{}) Expression {
 			return errorExpr{err: errors.New("newExprExpr", "invalid operation: %v", l[0])}
 		}
 
-		lhs := NewExpr(l[1])
+		lhs := newExpr(l[1])
 		if lhs.Err() != nil {
 			return errorExpr{err: errors.Propagate("newExprExpr", lhs.Err())}
 		}
 
-		rhs := NewExpr(l[2])
+		rhs := newExpr(l[2])
 		if rhs.Err() != nil {
 			return errorExpr{err: errors.Propagate("newExprExpr", rhs.Err())}
 		}
@@ -495,14 +492,17 @@ func (e errorExpr) Err() error {
 	return e.err
 }
 
+// TODO-C
 func Val(value interface{}) Expression {
-	return NewExpr(value)
+	return newExpr(value)
 }
 
+// TODO-C
 func Expr1(name, column string) Expression {
-	return NewExpr([]interface{}{name, column})
+	return newExpr([]interface{}{name, column})
 }
 
+// TODO-C
 func Expr2(name, val1, val2 interface{}) Expression {
-	return NewExpr([]interface{}{name, val1, val2})
+	return newExpr([]interface{}{name, val1, val2})
 }

filter.go

@@ -9,28 +9,35 @@ import (
 	"strings"
 )
 
+// FilterClause is an internal interface representing a filter of some kind.
 type FilterClause interface {
 	fmt.Stringer
 	filter(qf QFrame) QFrame
 	Err() error
 }
 
+// Filter is the lowest level in a filter clause.
+// It specifies the filter operation, which column to operate on and what
+// to filter/compare that column against.
 type Filter filter.Filter
 
 type comboClause struct {
 	err        error
 	subClauses []FilterClause
 }
 
+// AndClause represents the logical conjunction of multiple clauses.
 type AndClause comboClause
 
+// OrClause represents the logical disjunction of multiple clauses.
 type OrClause comboClause
 
+// OrClause represents the logical inverse of of a filter clause.
 type NotClause struct {
 	subClause FilterClause
 }
 
-// Convenience type to simplify clients when no filtering is to be done.
+// NullClause is a convenience type to simplify clients when no filtering is to be done.
 type NullClause struct{}
 
 func anyFilterErr(clauses []FilterClause) error {
@@ -42,6 +49,7 @@ func anyFilterErr(clauses []FilterClause) error {
 	return nil
 }
 
+// And returns a new AndClause that represents the conjunction of the passed filter clauses.
 func And(clauses ...FilterClause) AndClause {
 	if len(clauses) == 0 {
 		return AndClause{err: errors.New("new and clause", "zero subclauses not allowed")}
@@ -59,6 +67,7 @@ func clauseString(clauses []FilterClause) string {
 	return strings.Join(reps, ", ")
 }
 
+// String returns a textual description of the filter.
 func (c AndClause) String() string {
 	if c.Err() != nil {
 		return c.Err().Error()
@@ -84,10 +93,12 @@ func (c AndClause) filter(qf QFrame) QFrame {
 	return *filteredQf
 }
 
+// Err returns any error that may have occurred during creation of the filter
 func (c AndClause) Err() error {
 	return c.err
 }
 
+// Or returns a new OrClause that represents the disjunction of the passed filter clauses.
 func Or(clauses ...FilterClause) OrClause {
 	if len(clauses) == 0 {
 		return OrClause{err: errors.New("new or clause", "zero subclauses not allowed")}
@@ -96,6 +107,7 @@ func Or(clauses ...FilterClause) OrClause {
 	return OrClause{subClauses: clauses, err: anyFilterErr(clauses)}
 }
 
+// String returns a textual description of the filter.
 func (c OrClause) String() string {
 	if c.Err() != nil {
 		return c.Err().Error()
@@ -178,10 +190,12 @@ func (c OrClause) filter(qf QFrame) QFrame {
 	return *filteredQf
 }
 
+// Err returns any error that may have occurred during creation of the filter
 func (c OrClause) Err() error {
 	return c.err
 }
 
+// String returns a textual description of the filter.
 func (c Filter) String() string {
 	if c.Err() != nil {
 		return c.Err().Error()
@@ -194,14 +208,17 @@ func (c Filter) filter(qf QFrame) QFrame {
 	return qf.filter(filter.Filter(c))
 }
 
+// Err returns any error that may have occurred during creation of the filter
 func (c Filter) Err() error {
 	return nil
 }
 
+// Not creates a new NotClause that represents the inverse of the passed filter clause.
 func Not(c FilterClause) NotClause {
 	return NotClause{subClause: c}
 }
 
+// String returns a textual description of the filter clause.
 func (c NotClause) String() string {
 	if c.Err() != nil {
 		return c.Err().Error()
@@ -243,14 +260,17 @@ func (c NotClause) filter(qf QFrame) QFrame {
 	return qf.withIndex(newIx)
 }
 
+// Err returns any error that may have occurred during creation of the filter
 func (c NotClause) Err() error {
 	return c.subClause.Err()
 }
 
+// Null returns a new NullClause
 func Null() NullClause {
 	return NullClause{}
 }
 
+// Err for NullClause always returns an empty string.
 func (c NullClause) String() string {
 	return ""
 }
@@ -259,6 +279,7 @@ func (c NullClause) filter(qf QFrame) QFrame {
 	return qf
 }
 
+// Err for NullClause always returns nil.
 func (c NullClause) Err() error {
 	return nil
 }

qframe.go

@@ -165,7 +165,9 @@ func createColumn(name string, data interface{}, config *Config) (column.Column,
 	return localS, nil
 }
 
-func New(data map[string]interface{}, fns ...ConfigFunc) QFrame {
+// New creates a new QFrame with column content from data.
+// TODO-C Examples
+func New(data map[string]types.DataSlice, fns ...ConfigFunc) QFrame {
 	config := newConfig(fns)
 	if len(config.columnOrder) == 0 {
 		config.columnOrder = make([]string, 0, len(data))
@@ -219,11 +221,14 @@ func New(data map[string]interface{}, fns ...ConfigFunc) QFrame {
 	return QFrame{columns: s, columnsByName: sByName, index: index.NewAscending(uint32(currentLen)), Err: nil}
 }
 
+// Contains reports if a columns with colName is present in the frame.
 func (qf QFrame) Contains(colName string) bool {
 	_, ok := qf.columnsByName[colName]
 	return ok
 }
 
+// Filter filters the frame according to the filters in clause.
+// TODO-C Examples
 func (qf QFrame) Filter(clause FilterClause) QFrame {
 	if qf.Err != nil {
 		return qf
@@ -543,8 +548,9 @@ func (qf QFrame) GroupBy(configFns ...GroupByConfigFn) Grouper {
 	return g
 }
 
+// TODO-C
 type Aggregation struct {
-	Fn     interface{}
+	Fn     types.SliceFuncOrBuiltInId
 	Column string
 }
 
@@ -601,7 +607,9 @@ func fixLengthString(s string, pad string, desiredLen int) string {
 	return s
 }
 
-// Simple string representation of the table
+// String returns a simple string representation of the table.
+// Output is currently capped to 50 rows. Use Slice followed by String if you want
+// to print rows that are not among the first 50.
 func (qf QFrame) String() string {
 	// There are a lot of potential improvements to this function at the moment:
 	// - Limit output, both columns and rows
@@ -644,6 +652,8 @@ func (qf QFrame) String() string {
 	return strings.Join(result, "\n")
 }
 
+// Slice returns a new QFrame consisting of rows [start, end[.
+// Note that the underlying storage is kept. Slicing a frame will not release memory used to store the columns.
 func (qf QFrame) Slice(start, end int) QFrame {
 	if qf.Err != nil {
 		return qf
@@ -688,6 +698,7 @@ func (qf QFrame) setColumn(name string, c column.Column) QFrame {
 	return newF
 }
 
+// TODO-C
 func (qf QFrame) Copy(dstCol, srcCol string) QFrame {
 	if qf.Err != nil {
 		return qf
@@ -827,6 +838,7 @@ func (qf QFrame) apply2(fn interface{}, dstCol, srcCol1, srcCol2 string) QFrame
 	return qf.setColumn(dstCol, resultColumn)
 }
 
+// TODO-C
 type Instruction struct {
 	Fn     interface{}
 	DstCol string
@@ -836,6 +848,8 @@ type Instruction struct {
 	SrcCol2 string
 }
 
+// TODO: Should this function be made private and only rely on Eval to do this. As it is now there
+//       is redundancy in the interface.
 func (qf QFrame) Apply(instructions ...Instruction) QFrame {
 	result := qf
 	for _, a := range instructions {
@@ -870,6 +884,7 @@ func (qf QFrame) Eval(destCol string, expr Expression, ctx *ExprCtx) QFrame {
 		return qf
 	}
 
+	// TODO: Might want to change this to take use functional arguments instead...
 	if ctx == nil {
 		ctx = NewDefaultExprCtx()
 	}
@@ -1222,3 +1237,6 @@ func (qf QFrame) ByteSize() int {
 //   aggregation for example.
 // - Add different "cover types" for interface{} here and there to improve documentation?
 // - Change column package layout?
+// - Remove column based json Read/Write until someone needs it?
+// - Make config package with subpackages named after what they configure?
+// - Move Grouper to own file

types/aliases.go

@@ -0,0 +1,24 @@
+package types
+
+/*
+DataSlice can be a slice of any of the supported data types.
+
+The following types are currently supported:
+	[]bool
+	[]float64
+	[]int
+	[]string
+	[]*string
+*/
+type DataSlice = interface{}
+
+/*
+SliceFuncOrBuiltInId can be a function taking a slice of type T and returning a value of type T.
+
+For example:
+	func(x []float64) float64
+	func(x []int) int
+	func(x []*string) *string
+	func(x []bool) bool
+*/
+type SliceFuncOrBuiltInId = interface{}