csv

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package csv converts CSV and TSV files into BDF documents: one sheet view that shows the values the way Excel shows a CSV file it opens (the sheet is laid out and drawn by converter/xlsx; see xlsx.Grid).

What a file does not say is guessed, and options override each guess: its character encoding (a byte order mark, UTF-8, UTF-16, Shift_JIS, EUC-JP, ISO-2022-JP or Windows-1252), its dialect (comma, tab, semicolon or vertical bar between fields; double, single or no quotes around them; quotes doubled or escaped with a backslash), which values are numbers or dates (aligned right, as they are written), and whether the first record is a header row (then bold, frozen and marked as the column headers). See docs/design.md §3.7.

Index

Constants

View Source
const NoQuote = noQuote

NoQuote is the Quote option for files whose fields are never quoted.

Variables

This section is empty.

Functions

This section is empty.

Types

type Dialect

type Dialect struct {
	// Delimiter separates the fields: ',', '\t', ';', '|' or another
	// ASCII character.
	Delimiter rune
	// Quote encloses fields ('"' or '\”), or is 0 when fields are never
	// quoted (quotes are text).
	Quote rune
	// Escape is '\\' when a quote in a quoted field is escaped with a
	// backslash rather than doubled, else 0.
	Escape rune
}

Dialect is how a file writes its records.

type Header int

Header tells whether the first record is a header row.

const (
	// HeaderAuto guesses it from the values.
	HeaderAuto Header = iota
	// HeaderYes takes the first record as the header row.
	HeaderYes
	// HeaderNo takes every record as data.
	HeaderNo
)

type Options

type Options struct {
	// Name is the sheet name; ConvertFile names the sheet after the file,
	// as Excel does, and the default is "Sheet1".
	Name string
	// Charset is the character encoding as a WHATWG label ("utf-8",
	// "shift_jis", "euc-kr", "gb18030", "windows-1252" …); "" detects it.
	// A byte order mark overrides it.
	Charset string
	// Delimiter separates the fields (an ASCII character); 0 detects it.
	Delimiter rune
	// Quote encloses fields ('"' or '\”); 0 detects it, NoQuote reads
	// quotes as text.
	Quote rune
	// Header tells whether the first record is a header row.
	Header Header
	// TableStyle formats the values as an Excel table with a built-in
	// table style ("TableStyleMedium2" …); "" leaves them plain.
	TableStyle string
	// Title sets the document title.
	Title string
	// FontFS holds fonts that are not in the local file system; it is
	// searched before FontDirs (see converter.Options.FontFS).
	FontFS fs.FS
	// FontDirs are searched for fonts before the system font directories.
	FontDirs []string
	// NoSystemFonts restricts font lookup to FontFS and FontDirs.
	NoSystemFonts bool
	// SystemFonts refers to fonts by family name instead of embedding the
	// fonts used for layout.
	SystemFonts bool
	// NoSubset embeds whole fonts instead of the glyphs in use.
	NoSubset bool
	// NoWOFF2 stores embedded fonts as TrueType/OpenType instead of WOFF2.
	NoWOFF2 bool
	// IgnoreFSType embeds fonts whose OS/2 fsType forbids embedding or
	// subsetting. Set it only when you hold the rights to embed the fonts.
	IgnoreFSType bool
	// NoTextIndex skips building the text index part.
	NoTextIndex bool
	// Data says whether the values are stored as a table the document
	// holds beside the sheet (docs/spec.md §4.6): "" within the limits,
	// "all" whatever their size, "none" not at all.
	Data string
	// Warn receives non-fatal problems; when nil they are collected in
	// Result.Warnings.
	Warn func(msg string)
}

Options controls the conversion.

type Result

type Result struct {
	Doc           *bdf.Document
	Warnings      []string
	EmbeddedFonts int
	// Charset is the encoding the file was read in ("UTF-8", "Shift_JIS",
	// "UTF-16LE" …), and BOM whether a byte order mark told it.
	Charset string
	BOM     bool
	Dialect Dialect
	// Header reports whether the first record is the header row.
	Header bool
	// Rows and Cols are the number of records and the most fields in one.
	Rows, Cols int
}

Result is the outcome of a conversion, with what was guessed.

func Convert

func Convert(r io.ReaderAt, size int64, opts *Options) (*Result, error)

Convert converts a CSV or TSV file read from r.

func ConvertFile

func ConvertFile(path string, opts *Options) (*Result, error)

ConvertFile converts a CSV or TSV file; the sheet is named after it.

func Records added in v0.1.7

func Records(data []byte, opts *Options) ([][]string, *Result, error)

Records reads the records of a CSV or TSV file as text, without converting it: the character encoding and the dialect are found as Convert finds them (of the options, Charset, Delimiter, Quote and Header apply). The result tells what was found and whether the first record is a header row; its Doc is nil.

Jump to

Keyboard shortcuts

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