csvstruct

Import multiply-typed structured data from CSV to Go types.

Import spreadsheets:

Into Go types:

type Info struct {
  Name string
  Class string
}

type Attributes struct {
  HP int
  Damage int
}

type Prefab struct {
  Info *Info
  Attributes *Attributes
}

Get typed data:

Prefab{Info{"Alex", "Fighter"}, Attributes{100, 10}}
Prefab{Info{"Mary", "Queen"}, nil}
Prefab{Info{"Jayden", "Wizard"}, Attributes{90, 20}}

When working with Google Sheets or Microsoft Excel, export data to CSV and import it to your program using the csvstruct library.

Example

Let's assume the following CSS file:

Info.Name,Info.Class,Attributes.HP,Attributes.Damage
Alex,Fighter,100,10
Jayden,Wizard,90,20
Mary,Queen,,
...

The following program uses csvstruct library to import the data above:

type Info struct {
    Name  string
    Class string
}

type Attributes struct {
    HP     int
    Damage int
}

type Prefab struct {
    Info       *Info
    Attributes *Attributes
}

reader := csvstruct.NewReader[Prefab](csv.NewReader(strings.NewReader(testData)))

var prefab Prefab
for {
    err := reader.Read(&prefab)
    if err == io.EOF {
        break
    }
    if err != nil {
        panic(err)
    }

    fmt.Printf("%v\n", prefab.Info)
    fmt.Printf("%v\n", prefab.Attributes)
}

Format

The CSV data must have the following format:

Header

The first row of the CSV data is the header and it must be present.

Each header column contains the name of a component followed by a period . and an optional field name, e.g., MyComponent.MyField.

The MyComponent.MyField must be valid, i.e., MyComponent must be a valid field name of the type T passed to NewReader, and MyField must be a valid field of MyComponent.

If a cell is not given, then it's field is default initialized according to the default initialization of Go. For example, pointers are default initialized to nil and value types are default initialized to 0, empty structs, empty arrays, etc.

It's not required to put in the CSV header all the fields of MyComponent. Rather, only the fields that should be imported by those CSV data are present.

Data rows

The rows that follow a CSV header are data rows.

The CSV data can contain 0 or more data rows.

The data rows must contain in each cell data that is compatible with the type of the field specified in the CSV header.

For example, a field of type string can contain either an empty or non-empty cell (without quotes) since that is compatible with the string type.

A field of type Int can either an empty or non-empty cell containing a numerical value.

Empty cells default initialize fields according to Go semantics.

Multiple tables in the same CSV

It's possible to have multiple "tables" in the same CSV file. Tables are separate by CSV header rows. The library caller must be able to determine when a new CSV header is about to come up as the next row. In this case, the caller can use Reader.Clear to start a new table of CSV data, followed by Reader.Read to parse the new table.