Name Rascal/Libraries/lang/csv/IO/readCSV

Synopsis Read a relation from a CSV (Comma Separated Values) file.

Function

1. value readCSV(loc location, bool header = true, str separator = ",", str encoding = "UTF8")
2. value readCSV(loc location, map[str,str] options)
3. &T readCSV(type[&T] result, loc location, bool header = true, str separator = ",", str encoding = "UTF8")
4. &T readCSV(type[&T] result, loc location, map[str,str] options)

Usage import lang::csv::IO;

Description Read a CSV file and return a value of a required type.

The result argument is the required type of the value that is produced by reading the CSV that is found at location. Optionally, the following arguments can be supplied:

• header = true specifies that a header is present (default).
• header = false specifies that no header is present.
• separator = "," specifies that , is the separator character between fields (default).
  
  The CSV data should conform to the specified type (if any).

If the required type is not specified, it is inferred in three steps:

Step 1: The type of each field occurrence is inferred from its contents using the following rules:

• An empty value is of type void.
• A field that contains a string that corresponds to a number is numeric.
• A field that contains true or false is of type is bool.
• In all other cases the field is of type str.

Step 2: The type of each field is inferred from the type of all of its occurrences:

• If all occurrences have a numeric type, then the smallest possible type is used.
• If the occurrences have a mixed type, i.e., numeric, non-numeric, boolean or string, then the type is str.
• If the requested type for a field is str and another type would be inferred by the preceeding two rules, its inferred type will be str.

Reading the values in fields is straightforward, except for the case that the text in the field is enclosed between double quotes ("):

• the text may include line breaks which are represented as \n in the resulting string value of the field.
• the text may contain escaped double quotes ("") which are represented as \" in the resulting string value.

Examples Given is the follwing file ex1.csv:

position;artist;title;year
1;Eagles;Hotel California;1977
2;Queen;Bohemian rhapsody;1975
3;Boudewijn de Groot;Avond;1997

We can read it in various ways:

rascal>import lang::csv::IO;
ok
rascal>R1 = readCSV(#rel[int position, str artist, str title, int year],  |courses:///Rascal/Libraries/lang/csv/ex1.csv|, separator = ";");
rel[int position,str artist,str title,int year]: {
  <1,"Eagles","Hotel California",1977>,
  <3,"Boudewijn de Groot","Avond",1997>,
  <2,"Queen","Bohemian rhapsody",1975>
}

Now we can, for instance, select one of the fields of R1:

rascal>R1.artist;
set[str]: {"Queen","Boudewijn de Groot","Eagles"}

It is also possible to infer the type:

rascal>R1 = readCSV(|courses:///Rascal/Libraries/lang/csv/ex1.csv|, separator = ";");
readCSV inferred the relation type: rel[int \position,str \artist,str \title,int \year]
value: {
  <1,"Eagles","Hotel California",1977>,
  <3,"Boudewijn de Groot","Avond",1997>,
  <2,"Queen","Bohemian rhapsody",1975>
}

[Edit] | [New Subconcept] | [Recompile Course] | [Warnings]