<p>
This actor reads a file or URL, one line at a time, and outputs each line
except the first as a record. The first line of the file gives
the names of the fields of the output records.
The remaining lines give the values of the fields.
The output is an ordered
record token, which means that the order defined in the
first line is preserved.
</p><p>
<b>NOTE:</b> By default, this actor imposes no type constraints
on its output. To use it in a model, you must either enable
backward type inference (a parameter at the top level of the model),
or explicitly declare the output type (by selecting Configure-Ports
in the context menu). If you use backward type inference, then the
constraints are inferred from how you use the output. For example,
if you extract a record field of a particular type, then the output
will be constrained to be a record that contains that field.
If you declare output types specifically, then every line read
from the file must conform.
For example, if you set the output the type
constraint to "[x = int, y = double]" then the output will be an
ordered record where the first field is named "x" and has type int,
and the second field is named "y" and has type double.
If any line in the file violates this typing, then an exception
will be thrown.
</p><p>
If any line has more values than
the first line, then the trailing values will be ignored.
If any line has fewer values than the first line, then the
field values will be an empty string.
</p><p>
By default, the separator between field names and values is a comma,
so the file format is the standard CSV (comma-separated value) format.
The <i>separator</i> parameter enables changing the separator to
tabs or semicolons.
</p><p>
The file or URL is specified using any form acceptable
to FileParameter.
</p><p>
Before an end of file is reached, the <i>endOfFile</i>
output produces <i>false</i>. In the iteration where the last line
of the file is read and produced on the <i>output</i> port, this actor
produces <i>true</i> on the <i>endOfFile</i> port. In that iteration,
postfire() returns false. If the actor is iterated again, after the end
of file, then prefire() and postfire() will both return false, <i>output</i>
will produce the string "EOF", and <i>endOfFile</i> will produce <i>true</i>.
</p><p>
In some domains (such as SDF), returning false in postfire()
causes the model to cease executing.
In other domains (such as DE), this causes the director to avoid
further firings of this actor. So usually, the actor will not be
invoked again after the end of file is reached.
</p><p>
This actor reads ahead in the file so that it can produce an output
<i>true</i> on <i>endOfFile</i> in the same iteration where it outputs
the last line. It reads the first two lines in preinitialize(), and
subsequently reads a new line in each invocation of postfire(). The
data type of the output is also set in preinitialize(), after reading
the first line, which defines the structure of the record.
line read is produced on the <i>output</i> in the next iteration
after it is read.
</p>
Edward A. Lee
$Id: CSVReader.java 70402 2014-10-23 00:52:20Z cxh $
Ptolemy II 10.0
Yellow (eal)
Red (cxh)
A specification of the separator between items in the table.
The default is "comma", which results in assuming that fields
are separated by commas. If the value is changed to "tab", then
a tab separator will be used. If the value is "semicolon", then
a semicolon separator will be used. If the value is anything
else, then the value of the parameter, whatever it is, will
be the separator.
If true, then trim spaces around each field name and value.
This is a boolean that defaults to true. If you change it
to false, then all spaces in the field names and values are
preserved. Note that if there are spaces in the field names,
then the value of the record cannot be read by the
expression evaluator, so spaces in field names are not
recommended.