Skip to main content

CSV Import

Comma-separated values (CSV) is a simple file format used to store tabular data, normally generated by programs like Microsoft Excel or Google Sheets. Easel can import CSV files and convert them to a specific schema.

This is an example of a CSV file called rings.csv which has 3 columns, separated by commas:

type,image,cost
fire,fire-ring.svg,100
ice,ice-ring.svg,200
earth,earth-ring.svg,300

Raw import​

The following example imports the data from rings.csv into a variable called RingData:

pub import RingData from @rings.csv

This is similar to constructing a constant in Easel code like this:

pub const RingData = [
    { "type" = "fire", "image" = "fire-ring.svg", "cost" = 100 },
    { "type" = "ice", "image" = "ice-ring.svg", "cost" = 200 },
    { "type" = "earth", "image" = "earth-ring.svg", "cost" = 300 },
]

This imports the raw data as-is, without any conversion. That is why the Map keys are Strings, not Symbols, which means you have to use RingData[0]["type"] instead of RingData[0].type to access a field.

Schema import​

To take advantage of the full gamut of Easel's types, you can use the as keyword to convert the imported data to a specific schema. CSVs support two types of schema: Array of Maps and Array of Arrays.

Each row is a Map​

The following schema will convert each row of the CSV file into a Map:

pub import RingData from @rings.csv as [{
    type as Symbol,
    image as Asset,
    cost as Number,
}]

This is similar to constructing a constant in Easel code like this:

pub const RingData = [
    { type = $fire, image = @fire-ring.svg, cost = 100 },
    { type = $ice, image = @ice-ring.svg, cost = 200 },
    { type = $earth, image = @earth-ring.svg, cost = 300 },
]
info

See Schemas for more information on how to define schemas.

Each row is an Array​

Let's say we have a CSV file called level1.csv which describes a 5x5 tile map for a level in a game, where 1 represents a wall and 0 represents empty space:

1,1,0,1,1
1,0,0,0,1
1,0,1,0,1
1,0,0,0,1
1,1,0,1,1

The following schema will convert each row of the CSV file into a Array:

pub import Level1TileData from Csv(@level1.csv, headers=false) as [[Number]]

This is similar to constructing a constant in Easel code like this:

pub const Level1TileData = [
    [1, 1, 0, 1, 1],
    [1, 0, 0, 0, 1],
    [1, 0, 1, 0, 1],
    [1, 0, 0, 0, 1],
    [1, 1, 0, 1, 1],
]

Parsing parameters​

You can customize how your CSV file is parsed by using the Csv() import function with additional parameters:

pub import Level1Data from Csv(@level1.csv, headers=true, delimiter=',')

  • headers (Boolean): If true, the first row of the CSV file will be treated as headers and used to determine the field names. If false, the field names will be col1, col2, etc. Defaults to true.

  • delimiter (String): Specifies the character used to separate values in the CSV file. Default is ','. Some programs use ; for example. Must be a single ASCII character.

  • quote (String or Null): Specifies the character used to quote values in the CSV file. Default is '"' which means "Peas, Pies and Potatoes" would be interpreted as a single value, not three separate values, because it is enclosed in quotes. Set to null to disable quoting.

  • quoteEscape (Boolean): If true, the quote character can be escaped by doubling it. For example, """Tomorrow, and Tomorrow, and Tomorrow"" by Gabrielle Zevin" would be interpreted as "Tomorrow, and Tomorrow, and Tomorrow" by Gabrielle Zevin. Defaults to true.

Blanks as nulls​

If a field is optional, then blank cells in the CSV ("") will be interpreted as null.

For example, here is a CSV file with some blanks:

name,age,city
Augustus,30,New York
Brutus,,Los Angeles
Cassius,25,

Here is a schema that could be used to import it. Notice it has some optional fields marked with ?:

pub import PersonData from @people.csv as [{
    name as String,
    age? as Number,
    city? as String,
}]

This is similar to constructing a constant in Easel code like this:

pub const PersonData = [
    { name = "Augustus", age = 30, city = "New York" },
    { name = "Brutus", age = null, city = "Los Angeles" },
    { name = "Cassius", age = 25, city = null },
]