fileio

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 47 Imported by: 0

Documentation

Overview

Package fileio moves data between sheets and other file formats: CSV and TSV, Excel workbooks, SQLite databases, Parquet files and Lotus 1-2-3 worksheets. Everything is pure Go. The sheet package knows none of these formats: importers build a sheet through its public API (Load, LoadColWidth, RecalcAll) and exporters read a Snapshot of one. Each format is a row of the table in formats.go and a file of its own.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnsupported = errors.New("not a format 012 can import")

ErrUnsupported is returned for a file whose extension isn't known.

Functions

func CellValue added in v0.3.0

func CellValue(c SnapCell) nuon.Value

CellValue is a cell as a NUON value, typed by its format as a table written as NUON or JSON types it: what 012 get writes for one cell.

func HTMLChart added in v0.4.0

func HTMLChart(c SnapChart) string

HTMLChart draws one chart alone, in its frame.

func HTMLDocument added in v0.4.0

func HTMLDocument(title, body, extra string) string

HTMLDocument is a whole page: title, style sheet, body and script, with extra added to the script (the MCP view's messages).

func HTMLGrid added in v0.4.0

func HTMLGrid(snap *Snapshot) (string, string)

HTMLGrid draws the snapshot as 012's grid: column letters and row numbers, the cells as they show with their styles, borders and the looks of rules, and the charts over them. It returns the fragment and a note when rows were left out.

func HTMLPanel added in v0.4.0

func HTMLPanel(title, name, where string) string

HTMLPanel is the control panel's three lines: the title with the mode indicator, the name box (holding name until a cell is pointed at) and formula bar, and the context line saying what the page shows.

func HTMLStyle added in v0.4.0

func HTMLStyle() string

HTMLStyle is the style sheet of 012's HTML pages, for a page built around HTMLGrid or HTMLChart; the root element takes the class dark or light to choose a palette over the reader's preference.

func NUONCell added in v0.3.0

func NUONCell(v nuon.Value) sheet.LiveCell

NUONCell is the cell a NUON value makes: its value, text as the value's own, and its format (a file size's Size, a date's Date time, in the local time zone), as importing it would store it.

func TableName

func TableName(s string) string

TableName makes a table name from a file or sheet name: letters, digits and underscores, not starting with a digit.

func WriteHTML added in v0.4.0

func WriteHTML(w io.Writer, p HTMLPage) (note string, err error)

WriteHTML writes p as a page. The note, when there is one, says what the page left out.

Types

type Dialect

type Dialect struct {
	Comma    rune
	Encoding string // "UTF-8", "UTF-16" or "Windows-1252"
}

Dialect is how a delimited file is written.

type ErrNeedTable

type ErrNeedTable struct{ Tables []TableInfo }

ErrNeedTable is returned for a SQLite database with several tables when Options names neither a table nor a query; Tables lists them.

func (*ErrNeedTable) Error

func (e *ErrNeedTable) Error() string

type ExportOptions

type ExportOptions struct {
	Table string // SQLite: the table to write; replaced if it exists
}

ExportOptions tune an export.

type ExportResult

type ExportResult struct {
	Rows  int
	Notes []string
}

ExportResult says what an export wrote and what it couldn't keep.

func Encode added in v0.3.0

func Encode(w io.Writer, k Kind, snap *Snapshot) (*ExportResult, error)

Encode writes a snapshot to w in the text format k (see Kind.IsText): what 012 --pipe writes to standard output.

func Export

func Export(ctx context.Context, name string, k Kind, snap *Snapshot, opt ExportOptions) (*ExportResult, error)

Export writes a snapshot of a sheet to name in format k.

type HTMLPage added in v0.4.0

type HTMLPage struct {
	Title string    // the page's title, and the first line's
	Snap  *Snapshot // the cells, when Chart is nil
	Chart *SnapChart
}

HTMLPage is what an HTML page shows: a sheet or range, or one chart.

type Kind

type Kind int

Kind is an external file format.

const (
	CSV Kind = iota + 1
	TSV
	XLSX
	SQLite
	Parquet
	WK1
	JSON
	NUON
	HTML
)

func ExportKindOf added in v0.4.0

func ExportKindOf(name string) (Kind, bool)

ExportKindOf recognizes a file's format by its extension, including formats 012 only writes (HTML).

func KindNamed added in v0.3.0

func KindNamed(name string) (Kind, bool)

KindNamed finds a kind by its short name, ignoring case: "nuon".

func KindOf

func KindOf(name string) (Kind, bool)

KindOf recognizes a file 012 imports by its extension.

func Kinds

func Kinds() []Kind

Kinds lists every format, in menu order.

func (Kind) About

func (k Kind) About() string

About says what downloading in this format writes; empty for formats that can't be exported.

func (Kind) CanExport

func (k Kind) CanExport() bool

CanExport reports whether sheets can be written in this format.

func (Kind) CanImport added in v0.4.0

func (k Kind) CanImport() bool

CanImport reports whether 012 reads files of this kind.

func (Kind) Ext

func (k Kind) Ext() string

Ext is the extension written for this kind, e.g. ".xlsx".

func (Kind) Grows added in v0.3.0

func (k Kind) Grows() bool

Grows reports whether a file of kind k can be followed as it grows, its new rows read without reading it again: text tables, which Tail reads.

func (Kind) HasTables

func (k Kind) HasTables() bool

HasTables reports whether a file of this kind is a database of tables: importing picks one (see Tables), and a download writes the sheet or the selection as a named table (ExportOptions.Table).

func (Kind) HoldsSheets

func (k Kind) HoldsSheets() bool

HoldsSheets reports whether a file of this kind holds several named sheets, so a download writes the whole workbook (see SnapBook).

func (Kind) IsText added in v0.3.0

func (k Kind) IsText() bool

IsText reports whether this kind is text Encode writes to a stream: CSV, TSV, JSON or NUON.

func (Kind) Label

func (k Kind) Label() string

Label says what a file of this kind is, e.g. "Excel workbook".

func (Kind) MenuTitle

func (k Kind) MenuTitle() string

MenuTitle is the format's entry in the Download menu, e.g. "Microsoft Excel (.xlsx)"; empty for formats that can't be exported.

func (Kind) Noun

func (k Kind) Noun() string

Noun is what the format is called in a sentence, e.g. "Excel" in "Import a CSV, TSV, Excel ... file".

func (Kind) String

func (k Kind) String() string

String is the format's short name, e.g. "XLSX".

type LineFormat

type LineFormat struct {
	Format sheet.Format
	Style  sheet.Style
}

LineFormat is the format and style of a whole column or row.

type Options

type Options struct {
	// Table is the SQLite table to import, or Query a SELECT to run.
	// With neither, a database with one table imports it.
	Table, Query string
	Progress     *Progress
	// MaxCells is the most cells to keep, whole rows at a time; 0 is the
	// max-cells setting (sheet.MaxCells). WK1 files keep their own limits.
	MaxCells int
	// Locale is what CSV and TSV fields are read in (see numberLocale);
	// nil is en-US.
	Locale *locale.Locale
}

Options tune an import.

type Progress

type Progress struct {
	// contains filtered or unexported fields
}

Progress reports how far an import has got. The importer updates it from its goroutine; the UI reads it on a timer.

func NewProgress

func NewProgress() *Progress

NewProgress returns a progress with an unknown total.

func (*Progress) Get

func (p *Progress) Get() (rows int, frac float64)

Get returns the rows read so far and the fraction done, which is negative while unknown.

func (*Progress) Report

func (p *Progress) Report(rows int, done, total int64)

Report sets the rows read and, with a positive total, the fraction done; importers call it, and tests of progress displays.

type Result

type Result struct {
	Sheet *sheet.Sheet
	Kind  Kind
	Rows  int // rows of the file that were read, including a header
	Notes []string
}

Result is an imported sheet and what the import had to leave out or change, in sentences for the context line.

func Import

func Import(ctx context.Context, name string, opt Options) (*Result, error)

Import reads the file name into a new sheet. It checks ctx between rows, so a long import can be cancelled.

func ImportReader added in v0.3.0

func ImportReader(ctx context.Context, name string, r io.Reader, opt Options) (*Result, error)

ImportReader reads a table from r into a new sheet named name (as a file's sheet is named after the file), telling its format from the text; Result.Kind is NUON, JSON, CSV or TSV. It checks ctx between rows and updates opt.Progress.

type SnapCell

type SnapCell struct {
	Input   string
	Value   sheet.Value
	Format  sheet.Format // as displayed, including one inferred from a formula
	Own     sheet.Format // the cell's own format
	Style   sheet.Style
	Formula bool
	Sheets  []string // the sheets a formula names, as written
	Tables  []string // the tables a formula reads, as written
}

SnapCell is one non-blank cell of a snapshot.

func (SnapCell) Text

func (c SnapCell) Text() string

Text is the cell as displayed, without a width limit.

type SnapChart added in v0.4.0

type SnapChart struct {
	sheet.Chart
	Values sheet.ChartData
}

SnapChart is a chart with the values it draws, read when the snapshot is taken.

func ChartSnap added in v0.4.0

func ChartSnap(s *sheet.Sheet, i int) (SnapChart, bool)

ChartSnap is chart i of s with the values it draws, for a page of its own.

type SnapName

type SnapName struct {
	Name, Sheet string
	Range       sheet.Rect
}

SnapName is a named range: its name, and the range on the sheet named Sheet.

type Snapshot

type Snapshot struct {
	// Range is what's exported. Whole-sheet exports start at A1, as
	// Sheets' downloads do, so cells keep their addresses.
	Range  sheet.Rect
	Cells  map[sheet.Addr]SnapCell
	Widths map[int]int // non-default column widths
	Name   string      // what to call the data: a sheet or table name
	// Locale is the sheet's, which text formats (CSV) are written in.
	Locale *locale.Locale

	// ColFormats and RowFormats are the formats of whole columns and
	// rows, for formats that keep them (XLSX).
	ColFormats, RowFormats map[int]LineFormat

	// Sheets are every sheet of the workbook, in order, for formats that
	// hold several (XLSX); the snapshot itself is one of them, the one
	// shown. Nil exports just this snapshot. Names are the workbook's
	// named ranges.
	Sheets []*Snapshot
	Names  []SnapName
	Hidden bool // a hidden sheet of Sheets, written hidden

	// FrozenRows and FrozenCols are the frozen panes; Filter is the
	// sheet's filter, if any, and HiddenRows the rows of Range it hides,
	// for formats that keep them (XLSX).
	FrozenRows, FrozenCols int
	Filter                 *sheet.Filter
	HiddenRows             map[int]bool

	// Spills are the cells each formula whose array spills covers, by
	// the formula's cell, for formats that keep formulas (XLSX).
	Spills map[sheet.Addr]sheet.Rect

	// CondFormats and Validations are the sheet's rules, for formats
	// that keep them (XLSX).
	CondFormats []sheet.CondFormat
	Validations []sheet.Validation
	// Notes are the cells' notes in the range, for formats that keep
	// them (XLSX, as comments). A note may be on a cell with no contents.
	Notes map[sheet.Addr]string

	// Heights are the rows' heights set by hand, in lines, and Merges
	// the merged cells in the range, for formats that keep them (XLSX).
	Heights map[int]int
	Merges  []sheet.Rect

	// Tables are the tables wholly in the range, for formats that keep
	// them (XLSX).
	Tables []sheet.Table

	// Looks are how the sheet's rules draw the range's cells, and Charts
	// the charts whose top-left cell is in it, for formats that show
	// what the screen shows (HTML); see snapdrawn.go.
	Looks  map[sheet.Addr]sheet.Look
	Charts []SnapChart
}

Snapshot is a copy of the part of a sheet being exported, taken on the UI goroutine so the file can be written in the background while the sheet keeps changing.

func Snap

func Snap(s *sheet.Sheet, r sheet.Rect, name string) *Snapshot

Snap copies the cells of s in r. A zero r means the whole sheet, from A1 to the last cell with contents; any other r is trimmed to its last row and column with contents, so exporting whole columns writes their data rather than a million blank lines.

func SnapBook

func SnapBook(s *sheet.Sheet) *Snapshot

SnapBook copies every sheet of s's workbook, whole, with the named ranges, for formats that hold several sheets. The result is s's snapshot.

type TableInfo

type TableInfo struct {
	Name string
	View bool
	Rows int
	Cols []string
}

TableInfo describes a table or view in a SQLite database, for the table picker.

func Tables

func Tables(ctx context.Context, name string) ([]TableInfo, error)

Tables lists the tables and views of a SQLite database with their row counts and columns.

type Tail added in v0.3.0

type Tail struct {
	// contains filtered or unexported fields
}

A Tail reads a table of kind k from text that arrives in pieces.

func NewTail added in v0.3.0

func NewTail(k Kind, head []byte, loc *locale.Locale) (*Tail, error)

NewTail starts reading a table of kind k (see Kind.Grows). head is the start of the text, what it's sniffed by (its encoding, and a CSV file's delimiter and decimal separator), in the locale loc; the text itself comes through Feed, head included.

func (*Tail) Close added in v0.3.0

func (t *Tail) Close()

Close ends the tail's goroutine.

func (*Tail) Feed added in v0.3.0

func (t *Tail) Feed(piece []byte) (TailRows, error)

Feed reads the next piece of text and returns the rows it completed. After an error the tail reads nothing more.

type TailRows added in v0.3.0

type TailRows struct {
	// Header is the table's first row when it's new or changed: a CSV
	// file's first record, or NUON's column names as they're seen.
	Header sheet.LiveRow
	Rows   []sheet.LiveRow
}

TailRows are the rows a piece of text completed.

func NUONRows added in v0.3.0

func NUONRows(ctx context.Context, data []byte, maxCells int) (TailRows, string, error)

NUONRows reads NUON, a notebook cell's output, as a region's rows: a table's header and rows, a record as one row, a list of values that aren't records as one column named value, and any other value as that column with one row. It keeps at most maxCells cells, whole rows (0 for the max-cells setting), and says what it left out.

func Rows added in v0.3.0

func Rows(s *sheet.Sheet) TailRows

Rows reads a sheet an import made as a linked region's rows: its first row as the header and the rest under it, from column A, values with the formats they show in. A file that is read again whole when it changes (XLSX, SQLite, Parquet) is read this way.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL