grate

Once a sheet is opened via wb.Get(name), you can iterate through its rows using a Next() method. For each row, you can retrieve the cell contents as a slice of strings using Strings().

Always ensure you call wb.Close() when finished to release resources.

sheet, _ := wb.Get(s)        // open the sheet
for sheet.Next() {           // enumerate each row of data
    row := sheet.Strings()   // get the row's content as []string
    fmt.Println(row)
}
wb.Close()

The grate2tsv command is a highly parallel tool designed to extract tabular data from various file formats (including Excel and simple formats) and save them as .tsv files.

Output Behavior:

• Extracted files are saved into a results/ subdirectory. To maintain filesystem responsiveness, files are organized into a hierarchical structure based on the MD5 hash of the filename (e.g., results/ab/cd/filename.tsv).
• A summary log of the process (stats, errors, and row/column counts) is written to a file, which defaults to results.txt.

# Example usage (assuming the binary is compiled)
./grate2tsv file1.xlsx file2.xls data/my_spreadsheet.xlsx

Detailed logging is controlled by the grate.Debug boolean. This is determined at build time based on the loglevel variable. To enable debug logging, include the following flag in your go build command:

-ldflags="-X github.com/pbnjay/grate.loglevel=debug"

go build -ldflags="-X github.com/pbnjay/grate.loglevel=debug"

Use WrapErr to group multiple errors into a single error value. If only one error is provided, it returns that error directly. If multiple errors are provided, it returns an errx type that implements the standard error interface, allowing for error unwrapping.

err := grate.WrapErr(err1, err2, err3)

The Source interface is the entry point for interacting with a data file. It allows you to discover and retrieve specific data tables within the file.

Methods:

• List() ([]string, error): Returns a list of names for the individual data tables available in the source.
• Get(name string) (Collection, error): Retrieves a Collection for the specified table name.
• Close() error: Closes the source and releases associated memory.

tables, err := source.List()
// ...
collection, err := source.Get(tables[0])
// ...
defer source.Close()

Errors created via WrapErr can be unwrapped using the standard errors.Unwrap function. The Unwrap implementation for errx returns the second error in the original slice if multiple errors were provided, or nil if only one error was present. This allows for sequential unwrapping of a chain of errors.

err := grate.WrapErr(err1, err2)

// errors.Unwrap(err) will return err2
nextErr := errors.Unwrap(err)

// errors.Unwrap(nextErr) will return nil

Use Open(filename string) to open a tabular data file (like a spreadsheet or delimited text file). It returns a Source interface that provides access to the file's contents. The function iterates through registered format handlers and returns the first one that successfully opens the file. If no handler recognizes the file format, it returns ErrUnknownFormat.

source, err := grate.Open("data.csv")
if err != nil {
	// handle error
}
defer source.Close()

You can extend grate by registering new format handlers. Use Register(name string, priority int, opener OpenFunc) to add a new implementation.

• name: A string identifier for the format.
• priority: An integer determining the order in which Open() attempts to use this handler. Lower numbers have higher priority.
• opener: An OpenFunc which is a function with the signature func(filename string) (Source, error).

Note: The opener function should return ErrNotInFormat immediately if the filename does not match the expected file type. This allows Open() to gracefully skip to the next registered handler.

err := grate.Register("myformat", 10, func(filename string) (grate.Source, error) {
	// implementation logic
	// return ErrNotInFormat if not the right file type
	return mySource, nil
})

The following sentinel errors are exported by the grate package for error checking and comparison:

var (
	// ErrInvalidScanType is returned by Scan for invalid arguments.
	ErrInvalidScanType = errors.New("grate: Scan only supports *bool, *int, *float64, *string, *time.Time arguments")

	// ErrNotInFormat is used to auto-detect file types using the defined OpenFunc.
	// It is returned by OpenFunc when the code does not detect correct file formats.
	ErrNotInFormat = errors.New("grate: file is not in this format")

	// ErrUnknownFormat is used when grate does not know how to open a file format.
	ErrUnknownFormat = errors.New("grate: file format is not known/supported")
)

The following flags are available to control the behavior of the grate2tsv extraction process:

# Available flags:
-l filename.txt    save processing logs to `filename.txt`
-p                 pretend to output .tsv (dry run)
-i results.txt     `filename` to record stats about the process (default: results.txt)
-r                 remove embedded tabs, newlines, and condense spaces in cell contents (default: true)
-w                 trim whitespace from cell contents (default: true)
-b                 discard blank rows from the output (default: true)
--cpuprofile file  write cpu profile to file
--memprofile file  write memory profile to file