tableau

package module
v0.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 8, 2026 License: MIT Imports: 7 Imported by: 3

README

Tableau

Modern Configuration Converter

Release Status Testing Status Code Coverage GitHub release (latest SemVer including pre-releases) go.dev BSR GitHub

Tableau

A modern configuration converter based on Protobuf (proto3).

Prerequisites

Installation

API

Simply add the following import to your code, and then go [build|run|test] will automatically fetch the necessary dependencies:

import "github.com/tableauio/tableau"
tableauc

Install:

go install github.com/tableauio/tableau/cmd/tableauc@latest

Features

  • Convert Excel/CSV/XML/YAML to JSON/Text/Bin.
  • Use Protobuf to define the structure of Excel/CSV/XML/YAML.
  • Use Golang to develop the conversion engine.
  • Support multiple programming languages, thanks to Protobuf (proto3).

Concepts

  • Importer:
    • imports a Excel/CSV file to a in-memory book of Table sheets.
    • imports a XML/YAML file to a in-memory book of Document sheets.
  • Parsers:
    • protogen: converts Excel/CSV/XML/YAML files to Protoconf files.
    • confgen: converts Excel/CSV/XML/YAML with Protoconf files to JSON/Text/Bin files.
  • Exporter:
    • protogen: exports a tableau.Workbook to a proto file.
    • confgen: exports a protobuf message to a JSON/Text/Bin file.
  • Protoconf: a dialect of Protocol Buffers (proto3) extended with tableau options, aimed to define the structure of Excel/CSV/XML/YAML.

Design

See official document: Design.

Contribution

Requirements
Install buf
go install github.com/bufbuild/buf/cmd/buf@v1.67.0
Dev Workflow

Lint proto files:

buf lint

Build proto files (check for errors):

buf build

Generate Go code from proto files:

buf generate

Update dependencies in buf.lock:

buf dep update

Push modules to the BSR (CI only, requires BUF_TOKEN):

buf push --git-metadata --exclude-unnamed

Documentation

Index

Constants

View Source 
const (
	KeyBookName   = xerrors.KeyBookName   // workbook name
	KeySheetName  = xerrors.KeySheetName  // worksheet name
	KeyBookAlias  = xerrors.KeyBookAlias  // schema workbook alias
	KeySheetAlias = xerrors.KeySheetAlias // schema worksheet alias
	KeyMerger     = xerrors.KeyMerger     // merger sheet specifiers ([]string)
	KeyScatter    = xerrors.KeyScatter    // scatter sheet specifiers ([]string)
)

Source metadata keys for WrapKV and GetValue. Inspect maps these fields to ErrorDetail.Source.

Variables

This section is empty.

Functions

func E0005 added in v0.17.0 

func E0005(err error) error

E0005 marks custom check failures with code E0005 (custom check failed). Joined errors retain one detail per failure and their original messages. Existing codes and metadata take precedence; causes and stacks are preserved. Nil returns nil. Use Inspect at the reporting boundary for text or JSON.

func GenConf added in v0.9.6 

func GenConf(protoPackage, indir, outdir string, setters ...options.Option) error

GenConf converts Excel/CSV/XML/YAML files to different configuration files: JSON, Text, and Bin.

func GenProto added in v0.9.6 

func GenProto(protoPackage, indir, outdir string, setters ...options.Option) error

GenProto converts Excel/CSV/XML/YAML files to protoconf files.

func Generate added in v0.9.14 

func Generate(protoPackage, indir, outdir string, setters ...options.Option) error

Generate converts Excel/CSV/XML/YAML files to protoconf files and different configuration files: JSON, Text, and Bin.

func NewConfGenerator added in v0.10.6 

func NewConfGenerator(protoPackage, indir, outdir string, options ...options.Option) *confgen.Generator

NewConfGenerator creates a new conf generator.

func NewConfGeneratorWithOptions added in v0.10.6 

func NewConfGeneratorWithOptions(protoPackage, indir, outdir string, options *options.Options) *confgen.Generator

NewConfGeneratorWithOptions creates a new conf generator with options.

func NewProtoGenerator added in v0.10.6 

func NewProtoGenerator(protoPackage, indir, outdir string, options ...options.Option) *protogen.Generator

NewProtoGenerator creates a new proto generator.

func NewProtoGeneratorWithOptions added in v0.10.6 

func NewProtoGeneratorWithOptions(protoPackage, indir, outdir string, options *options.Options) *protogen.Generator

NewProtoGeneratorWithOptions creates a new proto generator with options.

func SetLang added in v0.10.6 

func SetLang(lang string) error

SetLang sets the default language. E.g: en, zh.

func WrapKV added in v0.17.0 

func WrapKV(err error, keysAndValues ...any) error

WrapKV adds metadata to err. It captures the caller's stack only when err has no stack trace. Existing metadata on each failure takes precedence over these values. Fields on an errors.Join result apply to its children; Tableau's collected errors retain their individual source scopes. Use Inspect for reporting. It preserves the cause chain and returns nil when err is nil. keysAndValues contains alternating keys and values; an odd length panics.

Types

type CellLocation added in v0.17.0 

type CellLocation = xerrors.CellLocation

CellLocation contains the source position and data of a cell. Position can also identify a node in a document input. TrimmedData is used for headers.

type Error added in v0.17.0 

type Error = xerrors.Error

Error reports one or more structured failures from Tableau. Use Inspect to obtain it from an operation's error. Details contains one entry per failure, including when only one cell fails. Error renders these details as a localized summary. JSON omits underlying errors and stack traces.

func Inspect added in v0.17.0 

func Inspect(err error) *Error

Inspect collects all failures in err into an independent *Error snapshot. Wrapped and joined errors are flattened into Details, preserving each failure's metadata. The Error method renders the details consistently, numbering multiple failures in one sequence: [1], [2], [3], ... Call Inspect once at the reporting boundary.

Editing the snapshot does not change err. Original causes remain reachable through errors.Is and errors.As. An ordinary Go error yields one detail containing its message; nil returns nil.

type ErrorDetail added in v0.17.0 

type ErrorDetail = xerrors.ErrorDetail

ErrorDetail describes one failure, independently of error wrappers and localized text formatting. Source and Field are omitted when unavailable.

type FieldLocation added in v0.17.0 

type FieldLocation = xerrors.FieldLocation

FieldLocation identifies the protobuf message and field associated with a failure. Options contains the textual Tableau field options, when available.

type SourceLocation added in v0.17.0 

type SourceLocation = xerrors.SourceLocation

SourceLocation identifies the actual source of a failure. PrimaryWorkbook and PrimaryWorksheet identify the schema's source when a shard is loaded. Aliases and merger/scatter specifiers describe that schema, independently of the actual workbook, worksheet, and cell where the failure occurred. WorksheetAlias is the protobuf message name when it differs from the schema worksheet name.

type VersionInfo added in v0.10.6 

type VersionInfo struct {
	Version         string // version of tableau
	ProtogenVersion string // version of protogen module
	ConfgenVersion  string // version of confgen module
	// VCS info
	Revision     string
	Time         string
	Experimental string
}

VersionInfo holds versions of tableau's main modules and VCS info.

func GetVersionInfo added in v0.10.6 

func GetVersionInfo() *VersionInfo

GetVersionInfo returns VersionInfo of tableau.

Source Files

View all Source files

Directories

Path Synopsis
cmd
tableauc command
internal
confgen
confgen/fieldprop
excel
importer
importer/book
importer/book/tableparser
importer/metasheet
importer/xlsx
Package xlsx reads raw cell values from selected OOXML worksheets.
 Package xlsx reads raw cell values from selected OOXML worksheets.
localizer
localizer/i18n
printer
profile
Package profile measures generator work and writes CPU and memory profiles.
 Package profile measures generator work and writes CPU and memory profiles.
protogen
strcase
Package strcase converts strings to various cases.
 Package strcase converts strings to various cases.
strcase/camelcase
Package camelcase is a micro package to split the words of a camelcase type string into a slice of words.
 Package camelcase is a micro package to split the words of a camelcase type string into a slice of words.
testutil
tools
tools/cmd/ecode command
types
x/xerrors
Package xerrors provides contextual error chains and structured error results.
 Package xerrors provides contextual error chains and structured error results.
x/xfs
x/xproto
x/xproto/protoc
Package load provides functions to load a protobuf message from different formats:
 Package load provides functions to load a protobuf message from different formats:
log
Refer:
 Refer:
core
driver
driver/defaultdriver
driver/zapdriver
proto
tableaupb
tableaupb/internalpb
tableaupb/unittestpb
Package store provides functions to store a protobuf message to different formats: json, bin, and txt.
 Package store provides functions to store a protobuf message to different formats: json, bin, and txt.
jsonparser
test
functest command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.