File: C:/Ruby27-x64/share/doc/ruby/html/CSV.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class CSV - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#class-CSV-label-Specialized+Methods">Specialized Methods</a>
<li><a href="#class-CSV-label-Reading">Reading</a>
<li><a href="#class-CSV-label-Writing">Writing</a>
<li><a href="#class-CSV-label-Shortcuts">Shortcuts</a>
<li><a href="#class-CSV-label-Data+Conversion">Data Conversion</a>
<li><a href="#class-CSV-label-CSV+with+headers">CSV with headers</a>
<li><a href="#class-CSV-label-Typed+data+reading">Typed data reading</a>
<li><a href="#class-CSV-label-CSV+and+Character+Encodings+-28M17n+or+Multilingualization-29">CSV and Character Encodings (M17n or Multilingualization)</a>
</ul>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="Object.html">Object</a>
</div>
<div id="includes-section" class="nav-section">
<h3>Included Modules</h3>
<ul class="link-list">
<li><a class="include" href="Enumerable.html">Enumerable</a>
</ul>
</div>
<div id="extends-section" class="nav-section">
<h3>Extended With Modules</h3>
<ul class="link-list">
<li><a class="extend" href="Forwardable.html">Forwardable</a>
</ul>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-filter">::filter</a>
<li ><a href="#method-c-foreach">::foreach</a>
<li ><a href="#method-c-generate">::generate</a>
<li ><a href="#method-c-generate_line">::generate_line</a>
<li ><a href="#method-c-instance">::instance</a>
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-c-open">::open</a>
<li ><a href="#method-c-parse">::parse</a>
<li ><a href="#method-c-parse_line">::parse_line</a>
<li ><a href="#method-c-read">::read</a>
<li ><a href="#method-c-readlines">::readlines</a>
<li ><a href="#method-c-table">::table</a>
<li ><a href="#method-i-3C-3C">#<<</a>
<li ><a href="#method-i-add_row">#add_row</a>
<li ><a href="#method-i-binmode-3F">#binmode?</a>
<li ><a href="#method-i-build_fields_converter">#build_fields_converter</a>
<li ><a href="#method-i-build_header_fields_converter">#build_header_fields_converter</a>
<li ><a href="#method-i-build_parser_fields_converter">#build_parser_fields_converter</a>
<li ><a href="#method-i-build_writer_fields_converter">#build_writer_fields_converter</a>
<li ><a href="#method-i-col_sep">#col_sep</a>
<li ><a href="#method-i-convert">#convert</a>
<li ><a href="#method-i-convert_fields">#convert_fields</a>
<li ><a href="#method-i-converters">#converters</a>
<li ><a href="#method-i-determine_encoding">#determine_encoding</a>
<li ><a href="#method-i-each">#each</a>
<li ><a href="#method-i-eof">#eof</a>
<li ><a href="#method-i-eof-3F">#eof?</a>
<li ><a href="#method-i-field_size_limit">#field_size_limit</a>
<li ><a href="#method-i-flock">#flock</a>
<li ><a href="#method-i-force_quotes-3F">#force_quotes?</a>
<li ><a href="#method-i-gets">#gets</a>
<li ><a href="#method-i-header_convert">#header_convert</a>
<li ><a href="#method-i-header_converters">#header_converters</a>
<li ><a href="#method-i-header_fields_converter">#header_fields_converter</a>
<li ><a href="#method-i-header_row-3F">#header_row?</a>
<li ><a href="#method-i-headers">#headers</a>
<li ><a href="#method-i-inspect">#inspect</a>
<li ><a href="#method-i-ioctl">#ioctl</a>
<li ><a href="#method-i-liberal_parsing-3F">#liberal_parsing?</a>
<li ><a href="#method-i-line">#line</a>
<li ><a href="#method-i-lineno">#lineno</a>
<li ><a href="#method-i-normalize_converters">#normalize_converters</a>
<li ><a href="#method-i-parser">#parser</a>
<li ><a href="#method-i-parser_enumerator">#parser_enumerator</a>
<li ><a href="#method-i-parser_fields_converter">#parser_fields_converter</a>
<li ><a href="#method-i-parser_options">#parser_options</a>
<li ><a href="#method-i-path">#path</a>
<li ><a href="#method-i-puts">#puts</a>
<li ><a href="#method-i-quote_char">#quote_char</a>
<li ><a href="#method-i-raw_encoding">#raw_encoding</a>
<li ><a href="#method-i-read">#read</a>
<li ><a href="#method-i-readline">#readline</a>
<li ><a href="#method-i-readlines">#readlines</a>
<li ><a href="#method-i-return_headers-3F">#return_headers?</a>
<li ><a href="#method-i-rewind">#rewind</a>
<li ><a href="#method-i-row_sep">#row_sep</a>
<li ><a href="#method-i-shift">#shift</a>
<li ><a href="#method-i-skip_blanks-3F">#skip_blanks?</a>
<li ><a href="#method-i-skip_lines">#skip_lines</a>
<li ><a href="#method-i-stat">#stat</a>
<li ><a href="#method-i-to_i">#to_i</a>
<li ><a href="#method-i-to_io">#to_io</a>
<li ><a href="#method-i-unconverted_fields-3F">#unconverted_fields?</a>
<li ><a href="#method-i-write_headers-3F">#write_headers?</a>
<li ><a href="#method-i-writer">#writer</a>
<li ><a href="#method-i-writer_fields_converter">#writer_fields_converter</a>
<li ><a href="#method-i-writer_options">#writer_options</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-CSV">
<h1 id="class-CSV" class="class">
class CSV
</h1>
<section class="description">
<p>This class provides a complete interface to <a href="CSV.html"><code>CSV</code></a> files and data. It offers tools to enable you to read and write to and from Strings or <a href="IO.html"><code>IO</code></a> objects, as needed.</p>
<p>The most generic interface of the library is:</p>
<pre class="ruby"><span class="ruby-identifier">csv</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">string_or_io</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># Reading: IO object should be open for read</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># => array of rows</span>
<span class="ruby-comment"># or</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">row</span><span class="ruby-operator">|</span>
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># or</span>
<span class="ruby-identifier">row</span> = <span class="ruby-identifier">csv</span>.<span class="ruby-identifier">shift</span>
<span class="ruby-comment"># Writing: IO object should be open for write</span>
<span class="ruby-identifier">csv</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">row</span>
</pre>
<p>There are several specialized class methods for one-statement reading or writing, described in the Specialized Methods section.</p>
<p>If a <a href="String.html"><code>String</code></a> is passed into <a href="CSV.html#method-c-new"><code>::new</code></a>, it is internally wrapped into a <a href="StringIO.html"><code>StringIO</code></a> object.</p>
<p><code>options</code> can be used for specifying the particular <a href="CSV.html"><code>CSV</code></a> flavor (column separators, row separators, value quoting and so on), and for data conversion, see <a href="Data.html"><code>Data</code></a> Conversion section for the description of the latter.</p>
<h2 id="class-CSV-label-Specialized+Methods">Specialized Methods<span><a href="#class-CSV-label-Specialized+Methods">¶</a> <a href="#top">↑</a></span></h2>
<h3 id="class-CSV-label-Reading">Reading<span><a href="#class-CSV-label-Reading">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-comment"># From a file: all at once</span>
<span class="ruby-identifier">arr_of_rows</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"path/to/file.csv"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># iterator-style:</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">"path/to/file.csv"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">row</span><span class="ruby-operator">|</span>
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># From a string</span>
<span class="ruby-identifier">arr_of_rows</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">"CSV,data,String"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># or</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">"CSV,data,String"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">row</span><span class="ruby-operator">|</span>
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
</pre>
<h3 id="class-CSV-label-Writing">Writing<span><a href="#class-CSV-label-Writing">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-comment"># To a file</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"path/to/file.csv"</span>, <span class="ruby-string">"wb"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">csv</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">csv</span> <span class="ruby-operator"><<</span> [<span class="ruby-string">"row"</span>, <span class="ruby-string">"of"</span>, <span class="ruby-string">"CSV"</span>, <span class="ruby-string">"data"</span>]
<span class="ruby-identifier">csv</span> <span class="ruby-operator"><<</span> [<span class="ruby-string">"another"</span>, <span class="ruby-string">"row"</span>]
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># To a String</span>
<span class="ruby-identifier">csv_string</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">generate</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">csv</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">csv</span> <span class="ruby-operator"><<</span> [<span class="ruby-string">"row"</span>, <span class="ruby-string">"of"</span>, <span class="ruby-string">"CSV"</span>, <span class="ruby-string">"data"</span>]
<span class="ruby-identifier">csv</span> <span class="ruby-operator"><<</span> [<span class="ruby-string">"another"</span>, <span class="ruby-string">"row"</span>]
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
</pre>
<h3 id="class-CSV-label-Shortcuts">Shortcuts<span><a href="#class-CSV-label-Shortcuts">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-comment"># Core extensions for converting one line</span>
<span class="ruby-identifier">csv_string</span> = [<span class="ruby-string">"CSV"</span>, <span class="ruby-string">"data"</span>].<span class="ruby-identifier">to_csv</span> <span class="ruby-comment"># to CSV</span>
<span class="ruby-identifier">csv_array</span> = <span class="ruby-string">"CSV,String"</span>.<span class="ruby-identifier">parse_csv</span> <span class="ruby-comment"># from CSV</span>
<span class="ruby-comment"># CSV() method</span>
<span class="ruby-constant">CSV</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">csv_out</span><span class="ruby-operator">|</span> <span class="ruby-identifier">csv_out</span> <span class="ruby-operator"><<</span> <span class="ruby-node">%w{my data here}</span> } <span class="ruby-comment"># to $stdout</span>
<span class="ruby-constant">CSV</span>(<span class="ruby-identifier">csv</span> = <span class="ruby-string">""</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">csv_str</span><span class="ruby-operator">|</span> <span class="ruby-identifier">csv_str</span> <span class="ruby-operator"><<</span> <span class="ruby-node">%w{my data here}</span> } <span class="ruby-comment"># to a String</span>
<span class="ruby-constant">CSV</span>(<span class="ruby-identifier">$stderr</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">csv_err</span><span class="ruby-operator">|</span> <span class="ruby-identifier">csv_err</span> <span class="ruby-operator"><<</span> <span class="ruby-node">%w{my data here}</span> } <span class="ruby-comment"># to $stderr</span>
<span class="ruby-constant">CSV</span>(<span class="ruby-identifier">$stdin</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">csv_in</span><span class="ruby-operator">|</span> <span class="ruby-identifier">csv_in</span>.<span class="ruby-identifier">each</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">row</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">row</span> } } <span class="ruby-comment"># from $stdin</span>
</pre>
<h2 id="class-CSV-label-Data+Conversion"><a href="Data.html"><code>Data</code></a> Conversion<span><a href="#class-CSV-label-Data+Conversion">¶</a> <a href="#top">↑</a></span></h2>
<h3 id="class-CSV-label-CSV+with+headers"><a href="CSV.html"><code>CSV</code></a> with headers<span><a href="#class-CSV-label-CSV+with+headers">¶</a> <a href="#top">↑</a></span></h3>
<p><a href="CSV.html"><code>CSV</code></a> allows to specify column names of <a href="CSV.html"><code>CSV</code></a> file, whether they are in data, or provided separately. If headers are specified, reading methods return an instance of <a href="CSV/Table.html"><code>CSV::Table</code></a>, consisting of <a href="CSV/Row.html"><code>CSV::Row</code></a>.</p>
<pre class="ruby"><span class="ruby-comment"># Headers are part of data</span>
<span class="ruby-identifier">data</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-identifier"><<~ROWS</span>, <span class="ruby-value">headers:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-value"> Name,Department,Salary
Bob,Engineering,1000
Jane,Sales,2000
John,Management,5000
</span><span class="ruby-identifier">ROWS</span>
<span class="ruby-identifier">data</span>.<span class="ruby-identifier">class</span> <span class="ruby-comment">#=> CSV::Table</span>
<span class="ruby-identifier">data</span>.<span class="ruby-identifier">first</span> <span class="ruby-comment">#=> #<CSV::Row "Name":"Bob" "Department":"Engineering" "Salary":"1000"></span>
<span class="ruby-identifier">data</span>.<span class="ruby-identifier">first</span>.<span class="ruby-identifier">to_h</span> <span class="ruby-comment">#=> {"Name"=>"Bob", "Department"=>"Engineering", "Salary"=>"1000"}</span>
<span class="ruby-comment"># Headers provided by developer</span>
<span class="ruby-identifier">data</span> = <span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">'Bob,Engineering,1000'</span>, <span class="ruby-value">headers:</span> <span class="ruby-node">%i[name department salary]</span>)
<span class="ruby-identifier">data</span>.<span class="ruby-identifier">first</span> <span class="ruby-comment">#=> #<CSV::Row name:"Bob" department:"Engineering" salary:"1000"></span>
</pre>
<h3 id="class-CSV-label-Typed+data+reading">Typed data reading<span><a href="#class-CSV-label-Typed+data+reading">¶</a> <a href="#top">↑</a></span></h3>
<p><a href="CSV.html"><code>CSV</code></a> allows to provide a set of data <em>converters</em> e.g. transformations to try on input data. Converter could be a symbol from <a href="CSV.html#Converters"><code>CSV::Converters</code></a> constant's keys, or lambda.</p>
<pre class="ruby"><span class="ruby-comment"># Without any converters:</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">'Bob,2018-03-01,100'</span>)
<span class="ruby-comment">#=> [["Bob", "2018-03-01", "100"]]</span>
<span class="ruby-comment"># With built-in converters:</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">'Bob,2018-03-01,100'</span>, <span class="ruby-value">converters:</span> <span class="ruby-node">%i[numeric date]</span>)
<span class="ruby-comment">#=> [["Bob", #<Date: 2018-03-01>, 100]]</span>
<span class="ruby-comment"># With custom converters:</span>
<span class="ruby-constant">CSV</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-string">'Bob,2018-03-01,100'</span>, <span class="ruby-value">converters:</span> [<span class="ruby-operator">-></span>(<span class="ruby-identifier">v</span>) { <span class="ruby-constant">Time</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-identifier">v</span>) <span class="ruby-keyword">rescue</span> <span class="ruby-identifier">v</span> }])
<span class="ruby-comment">#=> [["Bob", 2018-03-01 00:00:00 +0200, "100"]]</span>
</pre>
<h2 id="class-CSV-label-CSV+and+Character+Encodings+-28M17n+or+Multilingualization-29"><a href="CSV.html"><code>CSV</code></a> and Character Encodings (M17n or Multilingualization)<span><a href="#class-CSV-label-CSV+and+Character+Encodings+-28M17n+or+Multilingualization-29">¶</a> <a href="#top">↑</a></span></h2>
<p>This new <a href="CSV.html"><code>CSV</code></a> parser is m17n savvy. The parser works in the <a href="Encoding.html"><code>Encoding</code></a> of the <a href="IO.html"><code>IO</code></a> or <a href="String.html"><code>String</code></a> object being read from or written to. Your data is never transcoded (unless you ask Ruby to transcode it for you) and will literally be parsed in the <a href="Encoding.html"><code>Encoding</code></a> it is in. Thus <a href="CSV.html"><code>CSV</code></a> will return Arrays or Rows of Strings in the <a href="Encoding.html"><code>Encoding</code></a> of your data. This is accomplished by transcoding the parser itself into your <a href="Encoding.html"><code>Encoding</code></a>.</p>
<p>Some transcoding must take place, of course, to accomplish this multiencoding support. For example, <code>:col_sep</code>, <code>:row_sep</code>, and <code>:quote_char</code> must be transcoded to match your data. Hopefully this makes the entire process feel transparent, since CSV's defaults should just magically work for your data. However, you can set these values manually in the target <a href="Encoding.html"><code>Encoding</code></a> to avoid the translation.</p>
<p>It's also important to note that while all of CSV's core parser is now <a href="Encoding.html"><code>Encoding</code></a> agnostic, some features are not. For example, the built-in converters will try to transcode data to UTF-8 before making conversions. Again, you can provide custom converters that are aware of your Encodings to avoid this translation. It's just too hard for me to support native conversions in all of Ruby's Encodings.</p>
<p>Anyway, the practical side of this is simple: make sure <a href="IO.html"><code>IO</code></a> and <a href="String.html"><code>String</code></a> objects passed into <a href="CSV.html"><code>CSV</code></a> have the proper <a href="Encoding.html"><code>Encoding</code></a> set and everything should just work. <a href="CSV.html"><code>CSV</code></a> methods that allow you to open <a href="IO.html"><code>IO</code></a> objects (<a href="CSV.html#method-c-foreach"><code>CSV::foreach()</code></a>, <a href="CSV.html#method-c-open"><code>CSV::open()</code></a>, <a href="CSV.html#method-c-read"><code>CSV::read()</code></a>, and <a href="CSV.html#method-c-readlines"><code>CSV::readlines()</code></a>) do allow you to specify the <a href="Encoding.html"><code>Encoding</code></a>.</p>
<p>One minor exception comes when generating <a href="CSV.html"><code>CSV</code></a> into a <a href="String.html"><code>String</code></a> with an <a href="Encoding.html"><code>Encoding</code></a> that is not ASCII compatible. There's no existing data for <a href="CSV.html"><code>CSV</code></a> to use to prepare itself and thus you will probably need to manually specify the desired <a href="Encoding.html"><code>Encoding</code></a> for most of those cases. It will try to guess using the fields in a row of output though, when using <a href="CSV.html#method-c-generate_line"><code>CSV::generate_line()</code></a> or Array#to_csv().</p>
<p>I try to point out any other <a href="Encoding.html"><code>Encoding</code></a> issues in the documentation of methods as they come up.</p>
<p>This has been tested to the best of my ability with all non-“dummy” Encodings Ruby ships with. However, it is brave new code and may have some bugs. Please feel free to <a href="mailto:james@grayproductions.net">report</a> any issues you find with it.</p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="ConverterEncoding">ConverterEncoding
<dd><p>The encoding used by all converters.</p>
<dt id="Converters">Converters
<dd><p>This <a href="Hash.html"><code>Hash</code></a> holds the built-in converters of <a href="CSV.html"><code>CSV</code></a> that can be accessed by name. You can select <a href="CSV.html#Converters"><code>Converters</code></a> with <a href="CSV.html#method-i-convert"><code>CSV.convert()</code></a> or through the <code>options</code> <a href="Hash.html"><code>Hash</code></a> passed to <a href="CSV.html#method-c-new"><code>CSV::new()</code></a>.</p>
<dl class="rdoc-list note-list"><dt><strong><code>:integer</code></strong>
<dd>
<p>Converts any field Integer() accepts.</p>
</dd><dt><strong><code>:float</code></strong>
<dd>
<p>Converts any field Float() accepts.</p>
</dd><dt><strong><code>:numeric</code></strong>
<dd>
<p>A combination of <code>:integer</code> and <code>:float</code>.</p>
</dd><dt><strong><code>:date</code></strong>
<dd>
<p>Converts any field <a href="Date.html#method-c-parse"><code>Date::parse()</code></a> accepts.</p>
</dd><dt><strong><code>:date_time</code></strong>
<dd>
<p>Converts any field <a href="DateTime.html#method-c-parse"><code>DateTime::parse()</code></a> accepts.</p>
</dd><dt><strong><code>:all</code></strong>
<dd>
<p>All built-in converters. A combination of <code>:date_time</code> and <code>:numeric</code>.</p>
</dd></dl>
<p>All built-in converters transcode field data to UTF-8 before attempting a conversion. If your data cannot be transcoded to UTF-8 the conversion will fail and the field will remain unchanged.</p>
<p>This <a href="Hash.html"><code>Hash</code></a> is intentionally left unfrozen and users should feel free to add values to it that can be accessed by all <a href="CSV.html"><code>CSV</code></a> objects.</p>
<p>To add a combo field, the value should be an <a href="Array.html"><code>Array</code></a> of names. Combo fields can be nested with other combo fields.</p>
<dt id="DEFAULT_OPTIONS">DEFAULT_OPTIONS
<dd><p>The options used when no overrides are given by calling code. They are:</p>
<dl class="rdoc-list note-list"><dt><strong><code>:col_sep</code></strong>
<dd>
<p><code>","</code></p>
</dd><dt><strong><code>:row_sep</code></strong>
<dd>
<p><code>:auto</code></p>
</dd><dt><strong><code>:quote_char</code></strong>
<dd>
<p><code>'"'</code></p>
</dd><dt><strong><code>:field_size_limit</code></strong>
<dd>
<p><code>nil</code></p>
</dd><dt><strong><code>:converters</code></strong>
<dd>
<p><code>nil</code></p>
</dd><dt><strong><code>:unconverted_fields</code></strong>
<dd>
<p><code>nil</code></p>
</dd><dt><strong><code>:headers</code></strong>
<dd>
<p><code>false</code></p>
</dd><dt><strong><code>:return_headers</code></strong>
<dd>
<p><code>false</code></p>
</dd><dt><strong><code>:header_converters</code></strong>
<dd>
<p><code>nil</code></p>
</dd><dt><strong><code>:skip_blanks</code></strong>
<dd>
<p><code>false</code></p>
</dd><dt><strong><code>:force_quotes</code></strong>
<dd>
<p><code>false</code></p>
</dd><dt><strong><code>:skip_lines</code></strong>
<dd>
<p><code>nil</code></p>
</dd><dt><strong><code>:liberal_parsing</code></strong>
<dd>
<p><code>false</code></p>
</dd><dt><strong><code>:quote_empty</code></strong>
<dd>
<p><code>true</code></p>
</dd></dl>
<dt id="DateMatcher">DateMatcher
<dd><p>A <a href="Regexp.html"><code>Regexp</code></a> used to find and convert some common <a href="Date.html"><code>Date</code></a> formats.</p>
<dt id="DateTimeMatcher">DateTimeMatcher
<dd><p>A <a href="Regexp.html"><code>Regexp</code></a> used to find and convert some common <a href="DateTime.html"><code>DateTime</code></a> formats.</p>
<dt id="FieldInfo">FieldInfo
<dd><p>A <a href="CSV.html#FieldInfo"><code>FieldInfo</code></a> <a href="Struct.html"><code>Struct</code></a> contains details about a field's position in the data source it was read from. <a href="CSV.html"><code>CSV</code></a> will pass this <a href="Struct.html"><code>Struct</code></a> to some blocks that make decisions based on field structure. See <a href="CSV.html#method-i-convert_fields"><code>CSV.convert_fields()</code></a> for an example.</p>
<dl class="rdoc-list note-list"><dt><strong><code>index</code></strong>
<dd>
<p>The zero-based index of the field in its row.</p>
</dd><dt><strong><code>line</code></strong>
<dd>
<p>The line of the data source this row is from.</p>
</dd><dt><strong><code>header</code></strong>
<dd>
<p>The header for the column, when available.</p>
</dd></dl>
<dt id="HeaderConverters">HeaderConverters
<dd><p>This <a href="Hash.html"><code>Hash</code></a> holds the built-in header converters of <a href="CSV.html"><code>CSV</code></a> that can be accessed by name. You can select <a href="CSV.html#HeaderConverters"><code>HeaderConverters</code></a> with <a href="CSV.html#method-i-header_convert"><code>CSV.header_convert()</code></a> or through the <code>options</code> <a href="Hash.html"><code>Hash</code></a> passed to <a href="CSV.html#method-c-new"><code>CSV::new()</code></a>.</p>
<dl class="rdoc-list note-list"><dt><strong><code>:downcase</code></strong>
<dd>
<p>Calls downcase() on the header <a href="String.html"><code>String</code></a>.</p>
</dd><dt><strong><code>:symbol</code></strong>
<dd>
<p>Leading/trailing spaces are dropped, string is downcased, remaining spaces are replaced with underscores, non-word characters are dropped, and finally to_sym() is called.</p>
</dd></dl>
<p>All built-in header converters transcode header data to UTF-8 before attempting a conversion. If your data cannot be transcoded to UTF-8 the conversion will fail and the header will remain unchanged.</p>
<p>This <a href="Hash.html"><code>Hash</code></a> is intentionally left unfrozen and users should feel free to add values to it that can be accessed by all <a href="CSV.html"><code>CSV</code></a> objects.</p>
<p>To add a combo field, the value should be an <a href="Array.html"><code>Array</code></a> of names. Combo fields can be nested with other combo fields.</p>
<dt id="VERSION">VERSION
<dd><p>The version of the installed library.</p>
</dl>
</section>
<section class="attribute-method-details" class="method-section">
<header>
<h3>Attributes</h3>
</header>
<div id="attribute-i-encoding" class="method-detail">
<div class="method-heading attribute-method-heading">
<span class="method-name">encoding</span><span
class="attribute-access-type">[R]</span>
</div>
<div class="method-description">
<p>The <a href="Encoding.html"><code>Encoding</code></a> <a href="CSV.html"><code>CSV</code></a> is parsing or writing in. This will be the <a href="Encoding.html"><code>Encoding</code></a> you receive parsed data in and/or the <a href="Encoding.html"><code>Encoding</code></a> data will be written in.</p>
</div>
</div>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-filter" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
filter( **options ) { |row| ... }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
filter( input, **options ) { |row| ... }
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
filter( input, output, **options ) { |row| ... }
</span>
</div>
<div class="method-description">
<p>This method is a convenience for building Unix-like filters for <a href="CSV.html"><code>CSV</code></a> data. Each row is yielded to the provided block which can alter it as needed. After the block returns, the row is appended to <code>output</code> altered or not.</p>
<p>The <code>input</code> and <code>output</code> arguments can be anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> accepts (generally <a href="String.html"><code>String</code></a> or <a href="IO.html"><code>IO</code></a> objects). If not given, they default to <code>ARGF</code> and <code>$stdout</code>.</p>
<p>The <code>options</code> parameter is also filtered down to <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> after some clever key parsing. Any key beginning with <code>:in_</code> or <code>:input_</code> will have that leading identifier stripped and will only be used in the <code>options</code> <a href="Hash.html"><code>Hash</code></a> for the <code>input</code> object. Keys starting with <code>:out_</code> or <code>:output_</code> affect only <code>output</code>. All other keys are assigned to both objects.</p>
<p>The <code>:output_row_sep</code> <code>option</code> defaults to <code>$INPUT_RECORD_SEPARATOR</code> (<code>$/</code>).</p>
<div class="method-source-code" id="filter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 469</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">filter</span>(<span class="ruby-identifier">input</span>=<span class="ruby-keyword">nil</span>, <span class="ruby-identifier">output</span>=<span class="ruby-keyword">nil</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># parse options for input, output, or both</span>
<span class="ruby-identifier">in_options</span>, <span class="ruby-identifier">out_options</span> = <span class="ruby-constant">Hash</span>.<span class="ruby-identifier">new</span>, {<span class="ruby-value">row_sep:</span> <span class="ruby-identifier">$INPUT_RECORD_SEPARATOR</span>}
<span class="ruby-identifier">options</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">key</span>, <span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">case</span> <span class="ruby-identifier">key</span>.<span class="ruby-identifier">to_s</span>
<span class="ruby-keyword">when</span> <span class="ruby-regexp">/\Ain(?:put)?_(.+)\Z/</span>
<span class="ruby-identifier">in_options</span>[<span class="ruby-node">$1</span>.<span class="ruby-identifier">to_sym</span>] = <span class="ruby-identifier">value</span>
<span class="ruby-keyword">when</span> <span class="ruby-regexp">/\Aout(?:put)?_(.+)\Z/</span>
<span class="ruby-identifier">out_options</span>[<span class="ruby-node">$1</span>.<span class="ruby-identifier">to_sym</span>] = <span class="ruby-identifier">value</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">in_options</span>[<span class="ruby-identifier">key</span>] = <span class="ruby-identifier">value</span>
<span class="ruby-identifier">out_options</span>[<span class="ruby-identifier">key</span>] = <span class="ruby-identifier">value</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># build input and output wrappers</span>
<span class="ruby-identifier">input</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">input</span> <span class="ruby-operator">||</span> <span class="ruby-constant">ARGF</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">in_options</span>)
<span class="ruby-identifier">output</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">output</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">$stdout</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">out_options</span>)
<span class="ruby-comment"># read, yield, write</span>
<span class="ruby-identifier">input</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">row</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">row</span>
<span class="ruby-identifier">output</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">row</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-foreach" class="method-detail ">
<div class="method-heading">
<span class="method-name">foreach</span><span
class="method-args">(path, mode="r", **options, &block)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method is intended as the primary interface for reading <a href="CSV.html"><code>CSV</code></a> files. You pass a <code>path</code> and any <code>options</code> you wish to set for the read. Each row of file will be passed to the provided <code>block</code> in turn.</p>
<p>The <code>options</code> parameter can be anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands. This method also understands an additional <code>:encoding</code> parameter that you can use to specify the <a href="Encoding.html"><code>Encoding</code></a> of the data in the file to be read. You must provide this unless your data is in <a href="Encoding.html#method-c-default_external"><code>Encoding::default_external()</code></a>. <a href="CSV.html"><code>CSV</code></a> will use this to determine how to parse the data. You may provide a second <a href="Encoding.html"><code>Encoding</code></a> to have the data transcoded as it is read. For example, <code>encoding: "UTF-32BE:UTF-8"</code> would read UTF-32BE data from the file but transcode it to UTF-8 before <a href="CSV.html"><code>CSV</code></a> parses it.</p>
<div class="method-source-code" id="foreach-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 508</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foreach</span>(<span class="ruby-identifier">path</span>, <span class="ruby-identifier">mode</span>=<span class="ruby-string">"r"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-keyword">return</span> <span class="ruby-identifier">to_enum</span>(<span class="ruby-identifier">__method__</span>, <span class="ruby-identifier">path</span>, <span class="ruby-identifier">mode</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">block_given?</span>
<span class="ruby-identifier">open</span>(<span class="ruby-identifier">path</span>, <span class="ruby-identifier">mode</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">csv</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">each</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-generate" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
generate( str, **options ) { |csv| ... }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
generate( **options ) { |csv| ... }
</span>
</div>
<div class="method-description">
<p>This method wraps a <a href="String.html"><code>String</code></a> you provide, or an empty default <a href="String.html"><code>String</code></a>, in a <a href="CSV.html"><code>CSV</code></a> object which is passed to the provided block. You can use the block to append <a href="CSV.html"><code>CSV</code></a> rows to the <a href="String.html"><code>String</code></a> and when the block exits, the final <a href="String.html"><code>String</code></a> will be returned.</p>
<p>Note that a passed <a href="String.html"><code>String</code></a> <strong>is</strong> modified by this method. Call dup() before passing if you need a new <a href="String.html"><code>String</code></a>.</p>
<p>The <code>options</code> parameter can be anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands. This method understands an additional <code>:encoding</code> parameter when not passed a <a href="String.html"><code>String</code></a> to set the base <a href="Encoding.html"><code>Encoding</code></a> for the output. <a href="CSV.html"><code>CSV</code></a> needs this hint if you plan to output non-ASCII compatible data.</p>
<div class="method-source-code" id="generate-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 533</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">generate</span>(<span class="ruby-identifier">str</span>=<span class="ruby-keyword">nil</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># add a default empty String, if none was given</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">str</span>
<span class="ruby-identifier">str</span> = <span class="ruby-constant">StringIO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">str</span>)
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">SEEK_END</span>)
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">encoding</span> = <span class="ruby-identifier">options</span>[<span class="ruby-value">:encoding</span>]
<span class="ruby-identifier">str</span> = <span class="ruby-string">+""</span>
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">force_encoding</span>(<span class="ruby-identifier">encoding</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">encoding</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">csv</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">str</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-comment"># wrap</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">csv</span> <span class="ruby-comment"># yield for appending</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">string</span> <span class="ruby-comment"># return final String</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-generate_line" class="method-detail ">
<div class="method-heading">
<span class="method-name">generate_line</span><span
class="method-args">(row, **options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method is a shortcut for converting a single row (<a href="Array.html"><code>Array</code></a>) into a <a href="CSV.html"><code>CSV</code></a> <a href="String.html"><code>String</code></a>.</p>
<p>The <code>options</code> parameter can be anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands. This method understands an additional <code>:encoding</code> parameter to set the base <a href="Encoding.html"><code>Encoding</code></a> for the output. This method will try to guess your <a href="Encoding.html"><code>Encoding</code></a> from the first non-<code>nil</code> field in <code>row</code>, if possible, but you may need to use this parameter as a backup plan.</p>
<p>The <code>:row_sep</code> <code>option</code> defaults to <code>$INPUT_RECORD_SEPARATOR</code> (<code>$/</code>) when calling this method.</p>
<div class="method-source-code" id="generate_line-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 561</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">generate_line</span>(<span class="ruby-identifier">row</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-identifier">options</span> = {<span class="ruby-value">row_sep:</span> <span class="ruby-identifier">$INPUT_RECORD_SEPARATOR</span>}.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">str</span> = <span class="ruby-string">+""</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-value">:encoding</span>]
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">force_encoding</span>(<span class="ruby-identifier">options</span>[<span class="ruby-value">:encoding</span>])
<span class="ruby-keyword">elsif</span> <span class="ruby-identifier">field</span> = <span class="ruby-identifier">row</span>.<span class="ruby-identifier">find</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">String</span>)}
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">force_encoding</span>(<span class="ruby-identifier">field</span>.<span class="ruby-identifier">encoding</span>)
<span class="ruby-keyword">end</span>
(<span class="ruby-identifier">new</span>(<span class="ruby-identifier">str</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) <span class="ruby-operator"><<</span> <span class="ruby-identifier">row</span>).<span class="ruby-identifier">string</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-instance" class="method-detail ">
<div class="method-heading">
<span class="method-name">instance</span><span
class="method-args">(data = $stdout, **options) { |instance| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method will return a <a href="CSV.html"><code>CSV</code></a> instance, just like <a href="CSV.html#method-c-new"><code>CSV::new()</code></a>, but the instance will be cached and returned for all future calls to this method for the same <code>data</code> object (tested by <a href="Object.html#method-i-object_id"><code>Object#object_id()</code></a>) with the same <code>options</code>.</p>
<p>If a block is given, the instance is passed to the block and the return value becomes the return value of the block.</p>
<div class="method-source-code" id="instance-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 429</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">instance</span>(<span class="ruby-identifier">data</span> = <span class="ruby-identifier">$stdout</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># create a _signature_ for this method call, data object and options</span>
<span class="ruby-identifier">sig</span> = [<span class="ruby-identifier">data</span>.<span class="ruby-identifier">object_id</span>] <span class="ruby-operator">+</span>
<span class="ruby-identifier">options</span>.<span class="ruby-identifier">values_at</span>(<span class="ruby-operator">*</span><span class="ruby-constant">DEFAULT_OPTIONS</span>.<span class="ruby-identifier">keys</span>.<span class="ruby-identifier">sort_by</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">sym</span><span class="ruby-operator">|</span> <span class="ruby-identifier">sym</span>.<span class="ruby-identifier">to_s</span> })
<span class="ruby-comment"># fetch or create the instance for this signature</span>
<span class="ruby-identifier">@@instances</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">Hash</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">instance</span> = (<span class="ruby-identifier">@@instances</span>[<span class="ruby-identifier">sig</span>] <span class="ruby-operator">||=</span> <span class="ruby-identifier">new</span>(<span class="ruby-identifier">data</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>))
<span class="ruby-keyword">if</span> <span class="ruby-identifier">block_given?</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">instance</span> <span class="ruby-comment"># run block, if given, returning result</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">instance</span> <span class="ruby-comment"># or return the instance</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-name">new</span><span
class="method-args">(data, col_sep: ",", row_sep: :auto, quote_char: '"', field_size_limit: nil, converters: nil, unconverted_fields: nil, headers: false, return_headers: false, write_headers: nil, header_converters: nil, skip_blanks: false, force_quotes: false, skip_lines: nil, liberal_parsing: false, internal_encoding: nil, external_encoding: nil, encoding: nil, nil_value: nil, empty_value: "", quote_empty: true, write_converters: nil, write_nil_value: nil, write_empty_value: "", strip: false)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This constructor will wrap either a <a href="String.html"><code>String</code></a> or <a href="IO.html"><code>IO</code></a> object passed in <code>data</code> for reading and/or writing. In addition to the <a href="CSV.html"><code>CSV</code></a> instance methods, several <a href="IO.html"><code>IO</code></a> methods are delegated. (See <a href="CSV.html#method-c-open"><code>CSV::open()</code></a> for a complete list.) If you pass a <a href="String.html"><code>String</code></a> for <code>data</code>, you can later retrieve it (after writing to it, for example) with CSV.string().</p>
<p>Note that a wrapped <a href="String.html"><code>String</code></a> will be positioned at the beginning (for reading). If you want it at the end (for writing), use <a href="CSV.html#method-c-generate"><code>CSV::generate()</code></a>. If you want any other positioning, pass a preset <a href="StringIO.html"><code>StringIO</code></a> object instead.</p>
<p>You may set any reading and/or writing preferences in the <code>options</code> <a href="Hash.html"><code>Hash</code></a>. Available options are:</p>
<dl class="rdoc-list note-list"><dt><strong><code>:col_sep</code></strong>
<dd>
<p>The <a href="String.html"><code>String</code></a> placed between each field. This <a href="String.html"><code>String</code></a> will be transcoded into the data's <a href="Encoding.html"><code>Encoding</code></a> before parsing.</p>
</dd><dt><strong><code>:row_sep</code></strong>
<dd>
<p>The <a href="String.html"><code>String</code></a> appended to the end of each row. This can be set to the special <code>:auto</code> setting, which requests that <a href="CSV.html"><code>CSV</code></a> automatically discover this from the data. Auto-discovery reads ahead in the data looking for the next <code>"\r\n"</code>, <code>"\n"</code>, or <code>"\r"</code> sequence. A sequence will be selected even if it occurs in a quoted field, assuming that you would have the same line endings there. If none of those sequences is found, <code>data</code> is <code>ARGF</code>, <code>STDIN</code>, <code>STDOUT</code>, or <code>STDERR</code>, or the stream is only available for output, the default <code>$INPUT_RECORD_SEPARATOR</code> (<code>$/</code>) is used. Obviously, discovery takes a little time. <a href="Set.html"><code>Set</code></a> manually if speed is important. Also note that <a href="IO.html"><code>IO</code></a> objects should be opened in binary mode on Windows if this feature will be used as the line-ending translation can cause problems with resetting the document position to where it was before the read ahead. This <a href="String.html"><code>String</code></a> will be transcoded into the data's <a href="Encoding.html"><code>Encoding</code></a> before parsing.</p>
</dd><dt><strong><code>:quote_char</code></strong>
<dd>
<p>The character used to quote fields. This has to be a single character <a href="String.html"><code>String</code></a>. This is useful for application that incorrectly use <code>'</code> as the quote character instead of the correct <code>"</code>. <a href="CSV.html"><code>CSV</code></a> will always consider a double sequence of this character to be an escaped quote. This <a href="String.html"><code>String</code></a> will be transcoded into the data's <a href="Encoding.html"><code>Encoding</code></a> before parsing.</p>
</dd><dt><strong><code>:field_size_limit</code></strong>
<dd>
<p>This is a maximum size <a href="CSV.html"><code>CSV</code></a> will read ahead looking for the closing quote for a field. (In truth, it reads to the first line ending beyond this size.) If a quote cannot be found within the limit <a href="CSV.html"><code>CSV</code></a> will raise a <a href="CSV/MalformedCSVError.html"><code>MalformedCSVError</code></a>, assuming the data is faulty. You can use this limit to prevent what are effectively DoS attacks on the parser. However, this limit can cause a legitimate parse to fail and thus is set to <code>nil</code>, or off, by default.</p>
</dd><dt><strong><code>:converters</code></strong>
<dd>
<p>An <a href="Array.html"><code>Array</code></a> of names from the <a href="CSV.html#Converters"><code>Converters</code></a> <a href="Hash.html"><code>Hash</code></a> and/or lambdas that handle custom conversion. A single converter doesn't have to be in an <a href="Array.html"><code>Array</code></a>. All built-in converters try to transcode fields to UTF-8 before converting. The conversion will fail if the data cannot be transcoded, leaving the field unchanged.</p>
</dd><dt><strong><code>:unconverted_fields</code></strong>
<dd>
<p>If set to <code>true</code>, an unconverted_fields() method will be added to all returned rows (<a href="Array.html"><code>Array</code></a> or <a href="CSV/Row.html"><code>CSV::Row</code></a>) that will return the fields as they were before conversion. Note that <code>:headers</code> supplied by <a href="Array.html"><code>Array</code></a> or <a href="String.html"><code>String</code></a> were not fields of the document and thus will have an empty <a href="Array.html"><code>Array</code></a> attached.</p>
</dd><dt><strong><code>:headers</code></strong>
<dd>
<p>If set to <code>:first_row</code> or <code>true</code>, the initial row of the <a href="CSV.html"><code>CSV</code></a> file will be treated as a row of headers. If set to an <a href="Array.html"><code>Array</code></a>, the contents will be used as the headers. If set to a <a href="String.html"><code>String</code></a>, the <a href="String.html"><code>String</code></a> is run through a call of <a href="CSV.html#method-c-parse_line"><code>CSV::parse_line()</code></a> with the same <code>:col_sep</code>, <code>:row_sep</code>, and <code>:quote_char</code> as this instance to produce an <a href="Array.html"><code>Array</code></a> of headers. This setting causes <a href="CSV.html#method-i-shift"><code>CSV#shift()</code></a> to return rows as <a href="CSV/Row.html"><code>CSV::Row</code></a> objects instead of Arrays and <a href="CSV.html#method-i-read"><code>CSV#read()</code></a> to return <a href="CSV/Table.html"><code>CSV::Table</code></a> objects instead of an <a href="Array.html"><code>Array</code></a> of Arrays.</p>
</dd><dt><strong><code>:return_headers</code></strong>
<dd>
<p>When <code>false</code>, header rows are silently swallowed. If set to <code>true</code>, header rows are returned in a <a href="CSV/Row.html"><code>CSV::Row</code></a> object with identical headers and fields (save that the fields do not go through the converters).</p>
</dd><dt><strong><code>:write_headers</code></strong>
<dd>
<p>When <code>true</code> and <code>:headers</code> is set, a header row will be added to the output.</p>
</dd><dt><strong><code>:header_converters</code></strong>
<dd>
<p>Identical in functionality to <code>:converters</code> save that the conversions are only made to header rows. All built-in converters try to transcode headers to UTF-8 before converting. The conversion will fail if the data cannot be transcoded, leaving the header unchanged.</p>
</dd><dt><strong><code>:skip_blanks</code></strong>
<dd>
<p>When setting a <code>true</code> value, <a href="CSV.html"><code>CSV</code></a> will skip over any empty rows. Note that this setting will not skip rows that contain column separators, even if the rows contain no actual data. If you want to skip rows that contain separators but no content, consider using <code>:skip_lines</code>, or inspecting fields.compact.empty? on each row.</p>
</dd><dt><strong><code>:force_quotes</code></strong>
<dd>
<p>When setting a <code>true</code> value, <a href="CSV.html"><code>CSV</code></a> will quote all <a href="CSV.html"><code>CSV</code></a> fields it creates.</p>
</dd><dt><strong><code>:skip_lines</code></strong>
<dd>
<p>When setting an object responding to <code>match</code>, every line matching it is considered a comment and ignored during parsing. When set to a <a href="String.html"><code>String</code></a>, it is first converted to a <a href="Regexp.html"><code>Regexp</code></a>. When set to <code>nil</code> no line is considered a comment. If the passed object does not respond to <code>match</code>, <code>ArgumentError</code> is thrown.</p>
</dd><dt><strong><code>:liberal_parsing</code></strong>
<dd>
<p>When setting a <code>true</code> value, <a href="CSV.html"><code>CSV</code></a> will attempt to parse input not conformant with RFC 4180, such as double quotes in unquoted fields.</p>
</dd><dt><strong><code>:nil_value</code></strong>
<dd>
<p>When set an object, any values of an empty field is replaced by the set object, not nil.</p>
</dd><dt><strong><code>:empty_value</code></strong>
<dd>
<p>When setting an object, any values of a blank string field is replaced by the set object.</p>
</dd><dt><strong><code>:quote_empty</code></strong>
<dd>
<p>When setting a <code>true</code> value, <a href="CSV.html"><code>CSV</code></a> will quote empty values with double quotes. When <code>false</code>, <a href="CSV.html"><code>CSV</code></a> will emit an empty string for an empty field value.</p>
</dd><dt><strong><code>:write_converters</code></strong>
<dd>
<p>Converts values on each line with the specified <code>Proc</code> object(s), which receive a <code>String</code> value and return a <code>String</code> or <code>nil</code> value. When an array is specified, each converter will be applied in order.</p>
</dd><dt><strong><code>:write_nil_value</code></strong>
<dd>
<p>When a <code>String</code> value, <code>nil</code> value(s) on each line will be replaced with the specified value.</p>
</dd><dt><strong><code>:write_empty_value</code></strong>
<dd>
<p>When a <code>String</code> or <code>nil</code> value, empty value(s) on each line will be replaced with the specified value.</p>
</dd><dt><strong><code>:strip</code></strong>
<dd>
<p>When setting a <code>true</code> value, <a href="CSV.html"><code>CSV</code></a> will strip “trnfv” around the values. If you specify a string instead of <code>true</code>, <a href="CSV.html"><code>CSV</code></a> will strip string. The length of the string must be 1.</p>
</dd></dl>
<p>See <a href="CSV.html#DEFAULT_OPTIONS"><code>CSV::DEFAULT_OPTIONS</code></a> for the default settings.</p>
<p>Options cannot be overridden in the instance methods for performance reasons, so be sure to set what you want here.</p>
<div class="method-source-code" id="new-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 921</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">initialize</span>(<span class="ruby-identifier">data</span>,
<span class="ruby-value">col_sep:</span> <span class="ruby-string">","</span>,
<span class="ruby-value">row_sep:</span> <span class="ruby-value">:auto</span>,
<span class="ruby-value">quote_char:</span> <span class="ruby-string">'"'</span>,
<span class="ruby-value">field_size_limit:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">converters:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">unconverted_fields:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">headers:</span> <span class="ruby-keyword">false</span>,
<span class="ruby-value">return_headers:</span> <span class="ruby-keyword">false</span>,
<span class="ruby-value">write_headers:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">header_converters:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">skip_blanks:</span> <span class="ruby-keyword">false</span>,
<span class="ruby-value">force_quotes:</span> <span class="ruby-keyword">false</span>,
<span class="ruby-value">skip_lines:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">liberal_parsing:</span> <span class="ruby-keyword">false</span>,
<span class="ruby-value">internal_encoding:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">external_encoding:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">encoding:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">nil_value:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">empty_value:</span> <span class="ruby-string">""</span>,
<span class="ruby-value">quote_empty:</span> <span class="ruby-keyword">true</span>,
<span class="ruby-value">write_converters:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">write_nil_value:</span> <span class="ruby-keyword">nil</span>,
<span class="ruby-value">write_empty_value:</span> <span class="ruby-string">""</span>,
<span class="ruby-value">strip:</span> <span class="ruby-keyword">false</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"Cannot parse nil as CSV"</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">data</span>.<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">data</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">String</span>)
<span class="ruby-ivar">@io</span> = <span class="ruby-constant">StringIO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">data</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">set_encoding</span>(<span class="ruby-identifier">encoding</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">data</span>.<span class="ruby-identifier">encoding</span>)
<span class="ruby-keyword">else</span>
<span class="ruby-ivar">@io</span> = <span class="ruby-identifier">data</span>
<span class="ruby-keyword">end</span>
<span class="ruby-ivar">@encoding</span> = <span class="ruby-identifier">determine_encoding</span>(<span class="ruby-identifier">encoding</span>, <span class="ruby-identifier">internal_encoding</span>)
<span class="ruby-ivar">@base_fields_converter_options</span> = {
<span class="ruby-value">nil_value:</span> <span class="ruby-identifier">nil_value</span>,
<span class="ruby-value">empty_value:</span> <span class="ruby-identifier">empty_value</span>,
}
<span class="ruby-ivar">@write_fields_converter_options</span> = {
<span class="ruby-value">nil_value:</span> <span class="ruby-identifier">write_nil_value</span>,
<span class="ruby-value">empty_value:</span> <span class="ruby-identifier">write_empty_value</span>,
}
<span class="ruby-ivar">@initial_converters</span> = <span class="ruby-identifier">converters</span>
<span class="ruby-ivar">@initial_header_converters</span> = <span class="ruby-identifier">header_converters</span>
<span class="ruby-ivar">@initial_write_converters</span> = <span class="ruby-identifier">write_converters</span>
<span class="ruby-ivar">@parser_options</span> = {
<span class="ruby-value">column_separator:</span> <span class="ruby-identifier">col_sep</span>,
<span class="ruby-value">row_separator:</span> <span class="ruby-identifier">row_sep</span>,
<span class="ruby-value">quote_character:</span> <span class="ruby-identifier">quote_char</span>,
<span class="ruby-value">field_size_limit:</span> <span class="ruby-identifier">field_size_limit</span>,
<span class="ruby-value">unconverted_fields:</span> <span class="ruby-identifier">unconverted_fields</span>,
<span class="ruby-value">headers:</span> <span class="ruby-identifier">headers</span>,
<span class="ruby-value">return_headers:</span> <span class="ruby-identifier">return_headers</span>,
<span class="ruby-value">skip_blanks:</span> <span class="ruby-identifier">skip_blanks</span>,
<span class="ruby-value">skip_lines:</span> <span class="ruby-identifier">skip_lines</span>,
<span class="ruby-value">liberal_parsing:</span> <span class="ruby-identifier">liberal_parsing</span>,
<span class="ruby-value">encoding:</span> <span class="ruby-ivar">@encoding</span>,
<span class="ruby-value">nil_value:</span> <span class="ruby-identifier">nil_value</span>,
<span class="ruby-value">empty_value:</span> <span class="ruby-identifier">empty_value</span>,
<span class="ruby-value">strip:</span> <span class="ruby-identifier">strip</span>,
}
<span class="ruby-ivar">@parser</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@parser_enumerator</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@eof_error</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@writer_options</span> = {
<span class="ruby-value">encoding:</span> <span class="ruby-ivar">@encoding</span>,
<span class="ruby-value">force_encoding:</span> (<span class="ruby-keyword">not</span> <span class="ruby-identifier">encoding</span>.<span class="ruby-identifier">nil?</span>),
<span class="ruby-value">force_quotes:</span> <span class="ruby-identifier">force_quotes</span>,
<span class="ruby-value">headers:</span> <span class="ruby-identifier">headers</span>,
<span class="ruby-value">write_headers:</span> <span class="ruby-identifier">write_headers</span>,
<span class="ruby-value">column_separator:</span> <span class="ruby-identifier">col_sep</span>,
<span class="ruby-value">row_separator:</span> <span class="ruby-identifier">row_sep</span>,
<span class="ruby-value">quote_character:</span> <span class="ruby-identifier">quote_char</span>,
<span class="ruby-value">quote_empty:</span> <span class="ruby-identifier">quote_empty</span>,
}
<span class="ruby-ivar">@writer</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-identifier">writer</span> <span class="ruby-keyword">if</span> <span class="ruby-ivar">@writer_options</span>[<span class="ruby-value">:write_headers</span>]
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-open" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
open( filename, mode = "rb", **options ) { |faster_csv| ... }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
open( filename, **options ) { |faster_csv| ... }
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
open( filename, mode = "rb", **options )
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
open( filename, **options )
</span>
</div>
<div class="method-description">
<p>This method opens an <a href="IO.html"><code>IO</code></a> object, and wraps that with <a href="CSV.html"><code>CSV</code></a>. This is intended as the primary interface for writing a <a href="CSV.html"><code>CSV</code></a> file.</p>
<p>You must pass a <code>filename</code> and may optionally add a <code>mode</code> for Ruby's open(). You may also pass an optional <a href="Hash.html"><code>Hash</code></a> containing any <code>options</code> <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands as the final argument.</p>
<p>This method works like Ruby's open() call, in that it will pass a <a href="CSV.html"><code>CSV</code></a> object to a provided block and close it when the block terminates, or it will return the <a href="CSV.html"><code>CSV</code></a> object when no block is provided. (<strong>Note</strong>: This is different from the Ruby 1.8 <a href="CSV.html"><code>CSV</code></a> library which passed rows to the block. Use <a href="CSV.html#method-c-foreach"><code>CSV::foreach()</code></a> for that behavior.)</p>
<p>You must provide a <code>mode</code> with an embedded <a href="Encoding.html"><code>Encoding</code></a> designator unless your data is in <a href="Encoding.html#method-c-default_external"><code>Encoding::default_external()</code></a>. <a href="CSV.html"><code>CSV</code></a> will check the <a href="Encoding.html"><code>Encoding</code></a> of the underlying <a href="IO.html"><code>IO</code></a> object (set by the <code>mode</code> you pass) to determine how to parse the data. You may provide a second <a href="Encoding.html"><code>Encoding</code></a> to have the data transcoded as it is read just as you can with a normal call to <a href="IO.html#method-c-open"><code>IO::open()</code></a>. For example, <code>"rb:UTF-32BE:UTF-8"</code> would read UTF-32BE data from the file but transcode it to UTF-8 before <a href="CSV.html"><code>CSV</code></a> parses it.</p>
<p>An opened <a href="CSV.html"><code>CSV</code></a> object will delegate to many <a href="IO.html"><code>IO</code></a> methods for convenience. You may call:</p>
<ul><li>
<p>binmode()</p>
</li><li>
<p>binmode?()</p>
</li><li>
<p>close()</p>
</li><li>
<p>close_read()</p>
</li><li>
<p>close_write()</p>
</li><li>
<p>closed?()</p>
</li><li>
<p>eof()</p>
</li><li>
<p>eof?()</p>
</li><li>
<p>external_encoding()</p>
</li><li>
<p>fcntl()</p>
</li><li>
<p>fileno()</p>
</li><li>
<p>flock()</p>
</li><li>
<p>flush()</p>
</li><li>
<p>fsync()</p>
</li><li>
<p>internal_encoding()</p>
</li><li>
<p>ioctl()</p>
</li><li>
<p>isatty()</p>
</li><li>
<p>path()</p>
</li><li>
<p>pid()</p>
</li><li>
<p>pos()</p>
</li><li>
<p>pos=()</p>
</li><li>
<p>reopen()</p>
</li><li>
<p>seek()</p>
</li><li>
<p>stat()</p>
</li><li>
<p>sync()</p>
</li><li>
<p>sync=()</p>
</li><li>
<p>tell()</p>
</li><li>
<p><a href="CSV.html#method-i-to_i"><code>to_i</code></a>()</p>
</li><li>
<p><a href="CSV.html#method-i-to_io"><code>to_io</code></a>()</p>
</li><li>
<p>truncate()</p>
</li><li>
<p>tty?()</p>
</li></ul>
<div class="method-source-code" id="open-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 635</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">open</span>(<span class="ruby-identifier">filename</span>, <span class="ruby-identifier">mode</span>=<span class="ruby-string">"r"</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-comment"># wrap a File opened with the remaining +args+ with no newline</span>
<span class="ruby-comment"># decorator</span>
<span class="ruby-identifier">file_opts</span> = {<span class="ruby-value">universal_newline:</span> <span class="ruby-keyword">false</span>}.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">filename</span>, <span class="ruby-identifier">mode</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">file_opts</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">ArgumentError</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">e</span>
<span class="ruby-identifier">raise</span> <span class="ruby-keyword">unless</span> <span class="ruby-regexp">/needs binmode/</span>.<span class="ruby-identifier">match?</span>(<span class="ruby-identifier">e</span>.<span class="ruby-identifier">message</span>) <span class="ruby-keyword">and</span> <span class="ruby-identifier">mode</span> <span class="ruby-operator">==</span> <span class="ruby-string">"r"</span>
<span class="ruby-identifier">mode</span> = <span class="ruby-string">"rb"</span>
<span class="ruby-identifier">file_opts</span> = {<span class="ruby-value">encoding:</span> <span class="ruby-constant">Encoding</span>.<span class="ruby-identifier">default_external</span>}.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">file_opts</span>)
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">csv</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">f</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">Exception</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">raise</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># handle blocks like Ruby's open(), not like the CSV library</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">block_given?</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">csv</span>
<span class="ruby-keyword">ensure</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">csv</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-parse" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
parse( str, **options ) { |row| ... }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
parse( str, **options )
</span>
</div>
<div class="method-description">
<p>This method can be used to easily parse <a href="CSV.html"><code>CSV</code></a> out of a <a href="String.html"><code>String</code></a>. You may either provide a <code>block</code> which will be called with each row of the <a href="String.html"><code>String</code></a> in turn, or just use the returned <a href="Array.html"><code>Array</code></a> of Arrays (when no <code>block</code> is given).</p>
<p>You pass your <code>str</code> to read from, and an optional <code>options</code> containing anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands.</p>
<div class="method-source-code" id="parse-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 679</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parse</span>(<span class="ruby-identifier">str</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-identifier">csv</span> = <span class="ruby-identifier">new</span>(<span class="ruby-identifier">str</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-keyword">return</span> <span class="ruby-identifier">csv</span>.<span class="ruby-identifier">each</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">block</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">block_given?</span>
<span class="ruby-comment"># slurp contents, if no block is given</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">read</span>
<span class="ruby-keyword">ensure</span>
<span class="ruby-identifier">csv</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-parse_line" class="method-detail ">
<div class="method-heading">
<span class="method-name">parse_line</span><span
class="method-args">(line, **options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method is a shortcut for converting a single line of a <a href="CSV.html"><code>CSV</code></a> <a href="String.html"><code>String</code></a> into an <a href="Array.html"><code>Array</code></a>. Note that if <code>line</code> contains multiple rows, anything beyond the first row is ignored.</p>
<p>The <code>options</code> parameter can be anything <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands.</p>
<div class="method-source-code" id="parse_line-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 699</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parse_line</span>(<span class="ruby-identifier">line</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-identifier">new</span>(<span class="ruby-identifier">line</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>).<span class="ruby-identifier">shift</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-read" class="method-detail ">
<div class="method-heading">
<span class="method-name">read</span><span
class="method-args">(path, **options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Use to slurp a <a href="CSV.html"><code>CSV</code></a> file into an <a href="Array.html"><code>Array</code></a> of Arrays. Pass the <code>path</code> to the file and any <code>options</code> <a href="CSV.html#method-c-new"><code>CSV::new()</code></a> understands. This method also understands an additional <code>:encoding</code> parameter that you can use to specify the <a href="Encoding.html"><code>Encoding</code></a> of the data in the file to be read. You must provide this unless your data is in <a href="Encoding.html#method-c-default_external"><code>Encoding::default_external()</code></a>. <a href="CSV.html"><code>CSV</code></a> will use this to determine how to parse the data. You may provide a second <a href="Encoding.html"><code>Encoding</code></a> to have the data transcoded as it is read. For example, <code>encoding: "UTF-32BE:UTF-8"</code> would read UTF-32BE data from the file but transcode it to UTF-8 before <a href="CSV.html"><code>CSV</code></a> parses it.</p>
<div class="method-source-code" id="read-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 714</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">read</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-identifier">open</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">csv</span><span class="ruby-operator">|</span> <span class="ruby-identifier">csv</span>.<span class="ruby-identifier">read</span> }
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-readlines" class="method-detail ">
<div class="method-heading">
<span class="method-name">readlines</span><span
class="method-args">(path, **options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Alias for <a href="CSV.html#method-c-read"><code>CSV::read()</code></a>.</p>
<div class="method-source-code" id="readlines-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 719</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">readlines</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-identifier">read</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-table" class="method-detail ">
<div class="method-heading">
<span class="method-name">table</span><span
class="method-args">(path, **options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>A shortcut for:</p>
<pre class="ruby"><span class="ruby-constant">CSV</span>.<span class="ruby-identifier">read</span>( <span class="ruby-identifier">path</span>, { <span class="ruby-value">headers:</span> <span class="ruby-keyword">true</span>,
<span class="ruby-value">converters:</span> <span class="ruby-value">:numeric</span>,
<span class="ruby-value">header_converters:</span> <span class="ruby-value">:symbol</span> }.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">options</span>) )
</pre>
<div class="method-source-code" id="table-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 730</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">table</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-identifier">default_options</span> = {
<span class="ruby-value">headers:</span> <span class="ruby-keyword">true</span>,
<span class="ruby-value">converters:</span> <span class="ruby-value">:numeric</span>,
<span class="ruby-value">header_converters:</span> <span class="ruby-value">:symbol</span>,
}
<span class="ruby-identifier">options</span> = <span class="ruby-identifier">default_options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">read</span>(<span class="ruby-identifier">path</span>, <span class="ruby-operator">**</span><span class="ruby-identifier">options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-3C-3C" class="method-detail ">
<div class="method-heading">
<span class="method-name"><<</span><span
class="method-args">(row)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The primary write method for wrapped Strings and IOs, <code>row</code> (an <a href="Array.html"><code>Array</code></a> or <a href="CSV/Row.html"><code>CSV::Row</code></a>) is converted to <a href="CSV.html"><code>CSV</code></a> and appended to the data source. When a <a href="CSV/Row.html"><code>CSV::Row</code></a> is passed, only the row's fields() are appended to the output.</p>
<p>The data source must be open for writing.</p>
<div class="method-source-code" id="3C-3C-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1229</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title"><<</span>(<span class="ruby-identifier">row</span>)
<span class="ruby-identifier">writer</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">row</span>
<span class="ruby-keyword">self</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="CSV.html#method-i-add_row">add_row</a>, <a href="CSV.html#method-i-puts">puts</a>
</div>
</div>
<div id="method-i-add_row" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">add_row</span><span
class="method-args">(row)</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-3C-3C"><<</a>
</div>
</div>
<div id="method-i-binmode-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">binmode?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="binmode-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1161</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">binmode?</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:binmode?</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">binmode?</span>
<span class="ruby-keyword">else</span>
<span class="ruby-keyword">false</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-col_sep" class="method-detail ">
<div class="method-heading">
<span class="method-name">col_sep</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The encoded <code>:col_sep</code> used in parsing and writing. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="col_sep-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1008</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">col_sep</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">column_separator</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-convert" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
convert( name )
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
convert { |field| ... }
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
convert { |field, field_info| ... }
</span>
</div>
<div class="method-description">
<p>You can use this method to install a <a href="CSV.html#Converters"><code>CSV::Converters</code></a> built-in, or provide a block that handles a custom conversion.</p>
<p>If you provide a block that takes one argument, it will be passed the field and is expected to return the converted value or the field itself. If your block takes two arguments, it will also be passed a <a href="CSV.html#FieldInfo"><code>CSV::FieldInfo</code></a> <a href="Struct.html"><code>Struct</code></a>, containing details about the field. Again, the block should return a converted field or the field itself.</p>
<div class="method-source-code" id="convert-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1251</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">convert</span>(<span class="ruby-identifier">name</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">converter</span>)
<span class="ruby-identifier">parser_fields_converter</span>.<span class="ruby-identifier">add_converter</span>(<span class="ruby-identifier">name</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">converter</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-converters" class="method-detail ">
<div class="method-heading">
<span class="method-name">converters</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the current list of converters in effect. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details. Built-in converters will be returned by name, while others will be returned as is.</p>
<div class="method-source-code" id="converters-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1049</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">converters</span>
<span class="ruby-identifier">parser_fields_converter</span>.<span class="ruby-identifier">map</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">converter</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">name</span> = <span class="ruby-constant">Converters</span>.<span class="ruby-identifier">rassoc</span>(<span class="ruby-identifier">converter</span>)
<span class="ruby-identifier">name</span> <span class="ruby-operator">?</span> <span class="ruby-identifier">name</span>.<span class="ruby-identifier">first</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">converter</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-each" class="method-detail ">
<div class="method-heading">
<span class="method-name">each</span><span
class="method-args">(&block)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Yields each row of the data source in turn.</p>
<p>Support for <a href="Enumerable.html"><code>Enumerable</code></a>.</p>
<p>The data source must be open for reading.</p>
<div class="method-source-code" id="each-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1279</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">each</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-identifier">parser_enumerator</span>.<span class="ruby-identifier">each</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">block</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-eof" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">eof</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-eof-3F">eof?</a>
</div>
</div>
<div id="method-i-eof-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">eof?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="eof-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1197</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">eof?</span>
<span class="ruby-keyword">return</span> <span class="ruby-keyword">false</span> <span class="ruby-keyword">if</span> <span class="ruby-ivar">@eof_error</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">parser_enumerator</span>.<span class="ruby-identifier">peek</span>
<span class="ruby-keyword">false</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">MalformedCSVError</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">error</span>
<span class="ruby-ivar">@eof_error</span> = <span class="ruby-identifier">error</span>
<span class="ruby-keyword">false</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">StopIteration</span>
<span class="ruby-keyword">true</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="CSV.html#method-i-eof">eof</a>
</div>
</div>
<div id="method-i-field_size_limit" class="method-detail ">
<div class="method-heading">
<span class="method-name">field_size_limit</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The limit for field size, if any. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="field_size_limit-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1032</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">field_size_limit</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">field_size_limit</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-flock" class="method-detail ">
<div class="method-heading">
<span class="method-name">flock</span><span
class="method-args">(*args)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="flock-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1169</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">flock</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">NotImplementedError</span> <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:flock</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">flock</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-force_quotes-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">force_quotes?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if all output fields are quoted. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="force_quotes-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1117</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">force_quotes?</span>
<span class="ruby-ivar">@writer_options</span>[<span class="ruby-value">:force_quotes</span>]
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-gets" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">gets</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-shift">shift</a>
</div>
</div>
<div id="method-i-header_convert" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
header_convert( name )
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
header_convert { |field| ... }
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
header_convert { |field, field_info| ... }
</span>
</div>
<div class="method-description">
<p>Identical to <a href="CSV.html#method-i-convert"><code>CSV#convert()</code></a>, but for header rows.</p>
<p>Note that this method must be called before header rows are read to have any effect.</p>
<div class="method-source-code" id="header_convert-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1266</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">header_convert</span>(<span class="ruby-identifier">name</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">converter</span>)
<span class="ruby-identifier">header_fields_converter</span>.<span class="ruby-identifier">add_converter</span>(<span class="ruby-identifier">name</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">converter</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-header_converters" class="method-detail ">
<div class="method-heading">
<span class="method-name">header_converters</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the current list of converters in effect for headers. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details. Built-in converters will be returned by name, while others will be returned as is.</p>
<div class="method-source-code" id="header_converters-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1101</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">header_converters</span>
<span class="ruby-identifier">header_fields_converter</span>.<span class="ruby-identifier">map</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">converter</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">name</span> = <span class="ruby-constant">HeaderConverters</span>.<span class="ruby-identifier">rassoc</span>(<span class="ruby-identifier">converter</span>)
<span class="ruby-identifier">name</span> <span class="ruby-operator">?</span> <span class="ruby-identifier">name</span>.<span class="ruby-identifier">first</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">converter</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-header_row-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">header_row?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if the next row read will be a header row.</p>
<div class="method-source-code" id="header_row-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1299</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">header_row?</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">header_row?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-headers" class="method-detail ">
<div class="method-heading">
<span class="method-name">headers</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>nil</code> if headers will not be used, <code>true</code> if they will but have not yet been read, or the actual headers after they have been read. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="headers-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1069</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">headers</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@writer</span>
<span class="ruby-ivar">@writer</span>.<span class="ruby-identifier">headers</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">parsed_headers</span> = <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">headers</span>
<span class="ruby-keyword">return</span> <span class="ruby-identifier">parsed_headers</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">parsed_headers</span>
<span class="ruby-identifier">raw_headers</span> = <span class="ruby-ivar">@parser_options</span>[<span class="ruby-value">:headers</span>]
<span class="ruby-identifier">raw_headers</span> = <span class="ruby-keyword">nil</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">raw_headers</span> <span class="ruby-operator">==</span> <span class="ruby-keyword">false</span>
<span class="ruby-identifier">raw_headers</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-inspect" class="method-detail ">
<div class="method-heading">
<span class="method-name">inspect</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a simplified description of the key <a href="CSV.html"><code>CSV</code></a> attributes in an ASCII compatible <a href="String.html"><code>String</code></a>.</p>
<div class="method-source-code" id="inspect-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1328</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">inspect</span>
<span class="ruby-identifier">str</span> = [<span class="ruby-string">"#<"</span>, <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">to_s</span>, <span class="ruby-string">" io_type:"</span>]
<span class="ruby-comment"># show type of wrapped IO</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@io</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">$stdout</span> <span class="ruby-keyword">then</span> <span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"$stdout"</span>
<span class="ruby-keyword">elsif</span> <span class="ruby-ivar">@io</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">$stdin</span> <span class="ruby-keyword">then</span> <span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"$stdin"</span>
<span class="ruby-keyword">elsif</span> <span class="ruby-ivar">@io</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">$stderr</span> <span class="ruby-keyword">then</span> <span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"$stderr"</span>
<span class="ruby-keyword">else</span> <span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">to_s</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># show IO.path(), if available</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:path</span>) <span class="ruby-keyword">and</span> (<span class="ruby-identifier">p</span> = <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">path</span>)
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">" io_path:"</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">p</span>.<span class="ruby-identifier">inspect</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># show encoding</span>
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">" encoding:"</span> <span class="ruby-operator"><<</span> <span class="ruby-ivar">@encoding</span>.<span class="ruby-identifier">name</span>
<span class="ruby-comment"># show other attributes</span>
[<span class="ruby-string">"lineno"</span>, <span class="ruby-string">"col_sep"</span>, <span class="ruby-string">"row_sep"</span>, <span class="ruby-string">"quote_char"</span>].<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attr_name</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">a</span> = <span class="ruby-identifier">__send__</span>(<span class="ruby-identifier">attr_name</span>)
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">" "</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">attr_name</span> <span class="ruby-operator"><<</span> <span class="ruby-string">":"</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">a</span>.<span class="ruby-identifier">inspect</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
[<span class="ruby-string">"skip_blanks"</span>, <span class="ruby-string">"liberal_parsing"</span>].<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attr_name</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">a</span> = <span class="ruby-identifier">__send__</span>(<span class="ruby-node">"#{attr_name}?"</span>)
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">" "</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">attr_name</span> <span class="ruby-operator"><<</span> <span class="ruby-string">":"</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">a</span>.<span class="ruby-identifier">inspect</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">_headers</span> = <span class="ruby-identifier">headers</span>
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">" headers:"</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">_headers</span>.<span class="ruby-identifier">inspect</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">_headers</span>
<span class="ruby-identifier">str</span> <span class="ruby-operator"><<</span> <span class="ruby-string">">"</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">join</span>(<span class="ruby-string">''</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-comment"># any encoding error</span>
<span class="ruby-identifier">str</span>.<span class="ruby-identifier">map</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">s</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">e</span> = <span class="ruby-constant">Encoding</span><span class="ruby-operator">::</span><span class="ruby-constant">Converter</span>.<span class="ruby-identifier">asciicompat_encoding</span>(<span class="ruby-identifier">s</span>.<span class="ruby-identifier">encoding</span>)
<span class="ruby-identifier">e</span> <span class="ruby-operator">?</span> <span class="ruby-identifier">s</span>.<span class="ruby-identifier">encode</span>(<span class="ruby-identifier">e</span>) <span class="ruby-operator">:</span> <span class="ruby-identifier">s</span>.<span class="ruby-identifier">force_encoding</span>(<span class="ruby-string">"ASCII-8BIT"</span>)
<span class="ruby-keyword">end</span>.<span class="ruby-identifier">join</span>(<span class="ruby-string">''</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-ioctl" class="method-detail ">
<div class="method-heading">
<span class="method-name">ioctl</span><span
class="method-args">(*args)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="ioctl-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1174</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">ioctl</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">NotImplementedError</span> <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:ioctl</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">ioctl</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-liberal_parsing-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">liberal_parsing?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if illegal input is handled. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="liberal_parsing-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1122</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">liberal_parsing?</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">liberal_parsing?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-line" class="method-detail ">
<div class="method-heading">
<span class="method-name">line</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The last row read from this file.</p>
<div class="method-source-code" id="line-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1147</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">line</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">line</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-lineno" class="method-detail ">
<div class="method-heading">
<span class="method-name">lineno</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The line number of the last row read from this file. Fields with nested line-end characters will not affect this count.</p>
<div class="method-source-code" id="lineno-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1136</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">lineno</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@writer</span>
<span class="ruby-ivar">@writer</span>.<span class="ruby-identifier">lineno</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">lineno</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-path" class="method-detail ">
<div class="method-heading">
<span class="method-name">path</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="path-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1179</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">path</span>
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">path</span> <span class="ruby-keyword">if</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:path</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-puts" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">puts</span><span
class="method-args">(row)</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-3C-3C"><<</a>
</div>
</div>
<div id="method-i-quote_char" class="method-detail ">
<div class="method-heading">
<span class="method-name">quote_char</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The encoded <code>:quote_char</code> used in parsing and writing. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="quote_char-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1024</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">quote_char</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">quote_character</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-read" class="method-detail ">
<div class="method-heading">
<span class="method-name">read</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Slurps the remaining rows and returns an <a href="Array.html"><code>Array</code></a> of Arrays.</p>
<p>The data source must be open for reading.</p>
<div class="method-source-code" id="read-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1288</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">read</span>
<span class="ruby-identifier">rows</span> = <span class="ruby-identifier">to_a</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">use_headers?</span>
<span class="ruby-constant">Table</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">rows</span>, <span class="ruby-value">headers:</span> <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">headers</span>)
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">rows</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="CSV.html#method-i-readlines">readlines</a>
</div>
</div>
<div id="method-i-readline" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">readline</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-shift">shift</a>
</div>
</div>
<div id="method-i-readlines" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">readlines</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="CSV.html#method-i-read">read</a>
</div>
</div>
<div id="method-i-return_headers-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">return_headers?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if headers will be returned as a row of results. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="return_headers-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1084</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">return_headers?</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">return_headers?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-rewind" class="method-detail ">
<div class="method-heading">
<span class="method-name">rewind</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Rewinds the underlying <a href="IO.html"><code>IO</code></a> object and resets CSV's lineno() counter.</p>
<div class="method-source-code" id="rewind-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1212</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">rewind</span>
<span class="ruby-ivar">@parser</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@parser_enumerator</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@eof_error</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@writer</span>.<span class="ruby-identifier">rewind</span> <span class="ruby-keyword">if</span> <span class="ruby-ivar">@writer</span>
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-row_sep" class="method-detail ">
<div class="method-heading">
<span class="method-name">row_sep</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The encoded <code>:row_sep</code> used in parsing and writing. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="row_sep-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1016</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">row_sep</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">row_separator</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-shift" class="method-detail ">
<div class="method-heading">
<span class="method-name">shift</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The primary read method for wrapped Strings and IOs, a single row is pulled from the data source, parsed and returned as an <a href="Array.html"><code>Array</code></a> of fields (if header rows are not used) or a <a href="CSV/Row.html"><code>CSV::Row</code></a> (when header rows are used).</p>
<p>The data source must be open for reading.</p>
<div class="method-source-code" id="shift-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1310</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">shift</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@eof_error</span>
<span class="ruby-identifier">eof_error</span>, <span class="ruby-ivar">@eof_error</span> = <span class="ruby-ivar">@eof_error</span>, <span class="ruby-keyword">nil</span>
<span class="ruby-identifier">raise</span> <span class="ruby-identifier">eof_error</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">parser_enumerator</span>.<span class="ruby-identifier">next</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">StopIteration</span>
<span class="ruby-keyword">nil</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="CSV.html#method-i-gets">gets</a>, <a href="CSV.html#method-i-readline">readline</a>
</div>
</div>
<div id="method-i-skip_blanks-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">skip_blanks?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> blank lines are skipped by the parser. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="skip_blanks-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1112</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">skip_blanks?</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">skip_blanks?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-skip_lines" class="method-detail ">
<div class="method-heading">
<span class="method-name">skip_lines</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>The regex marking a line as a comment. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="skip_lines-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1040</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">skip_lines</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">skip_lines</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-stat" class="method-detail ">
<div class="method-heading">
<span class="method-name">stat</span><span
class="method-args">(*args)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="stat-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1183</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">stat</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">NotImplementedError</span> <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:stat</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">stat</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-to_i" class="method-detail ">
<div class="method-heading">
<span class="method-name">to_i</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="to_i-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1188</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">to_i</span>
<span class="ruby-identifier">raise</span> <span class="ruby-constant">NotImplementedError</span> <span class="ruby-keyword">unless</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:to_i</span>)
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">to_i</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-to_io" class="method-detail ">
<div class="method-heading">
<span class="method-name">to_io</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="to_io-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1193</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">to_io</span>
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:to_io</span>) <span class="ruby-operator">?</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">to_io</span> <span class="ruby-operator">:</span> <span class="ruby-ivar">@io</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-unconverted_fields-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">unconverted_fields?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if unconverted_fields() to parsed results. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="unconverted_fields-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1060</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">unconverted_fields?</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">unconverted_fields?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-write_headers-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">write_headers?</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if headers are written in output. See <a href="CSV.html#method-c-new"><code>CSV::new</code></a> for details.</p>
<div class="method-source-code" id="write_headers-3F-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1092</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">write_headers?</span>
<span class="ruby-ivar">@writer_options</span>[<span class="ruby-value">:write_headers</span>]
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="private-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Private Instance Methods</h3>
</header>
<div id="method-i-build_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">build_fields_converter</span><span
class="method-args">(initial_converters, options)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="build_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1460</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">build_fields_converter</span>(<span class="ruby-identifier">initial_converters</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">fields_converter</span> = <span class="ruby-constant">FieldsConverter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">options</span>)
<span class="ruby-identifier">normalize_converters</span>(<span class="ruby-identifier">initial_converters</span>).<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">name</span>, <span class="ruby-identifier">converter</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">fields_converter</span>.<span class="ruby-identifier">add_converter</span>(<span class="ruby-identifier">name</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">converter</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">fields_converter</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-build_header_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">build_header_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="build_header_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1442</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">build_header_fields_converter</span>
<span class="ruby-identifier">specific_options</span> = {
<span class="ruby-value">builtin_converters:</span> <span class="ruby-constant">HeaderConverters</span>,
<span class="ruby-value">accept_nil:</span> <span class="ruby-keyword">true</span>,
}
<span class="ruby-identifier">options</span> = <span class="ruby-ivar">@base_fields_converter_options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">specific_options</span>)
<span class="ruby-identifier">build_fields_converter</span>(<span class="ruby-ivar">@initial_header_converters</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-build_parser_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">build_parser_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="build_parser_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1430</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">build_parser_fields_converter</span>
<span class="ruby-identifier">specific_options</span> = {
<span class="ruby-value">builtin_converters:</span> <span class="ruby-constant">Converters</span>,
}
<span class="ruby-identifier">options</span> = <span class="ruby-ivar">@base_fields_converter_options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">specific_options</span>)
<span class="ruby-identifier">build_fields_converter</span>(<span class="ruby-ivar">@initial_converters</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-build_writer_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">build_writer_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="build_writer_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1455</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">build_writer_fields_converter</span>
<span class="ruby-identifier">build_fields_converter</span>(<span class="ruby-ivar">@initial_write_converters</span>,
<span class="ruby-ivar">@write_fields_converter_options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-convert_fields" class="method-detail ">
<div class="method-heading">
<span class="method-name">convert_fields</span><span
class="method-args">(fields, headers = false)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Processes <code>fields</code> with <code>@converters</code>, or <code>@header_converters</code> if <code>headers</code> is passed as <code>true</code>, returning the converted field set. Any converter that changes the field into something other than a <a href="String.html"><code>String</code></a> halts the pipeline of conversion for that field. This is primarily an efficiency shortcut.</p>
<div class="method-source-code" id="convert_fields-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1405</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">convert_fields</span>(<span class="ruby-identifier">fields</span>, <span class="ruby-identifier">headers</span> = <span class="ruby-keyword">false</span>)
<span class="ruby-keyword">if</span> <span class="ruby-identifier">headers</span>
<span class="ruby-identifier">header_fields_converter</span>.<span class="ruby-identifier">convert</span>(<span class="ruby-identifier">fields</span>, <span class="ruby-keyword">nil</span>, <span class="ruby-value">0</span>)
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">parser_fields_converter</span>.<span class="ruby-identifier">convert</span>(<span class="ruby-identifier">fields</span>, <span class="ruby-ivar">@headers</span>, <span class="ruby-identifier">lineno</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-determine_encoding" class="method-detail ">
<div class="method-heading">
<span class="method-name">determine_encoding</span><span
class="method-args">(encoding, internal_encoding)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="determine_encoding-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1368</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">determine_encoding</span>(<span class="ruby-identifier">encoding</span>, <span class="ruby-identifier">internal_encoding</span>)
<span class="ruby-comment"># honor the IO encoding if we can, otherwise default to ASCII-8BIT</span>
<span class="ruby-identifier">io_encoding</span> = <span class="ruby-identifier">raw_encoding</span>
<span class="ruby-keyword">return</span> <span class="ruby-identifier">io_encoding</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">io_encoding</span>
<span class="ruby-keyword">return</span> <span class="ruby-constant">Encoding</span>.<span class="ruby-identifier">find</span>(<span class="ruby-identifier">internal_encoding</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">internal_encoding</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">encoding</span>
<span class="ruby-identifier">encoding</span>, = <span class="ruby-identifier">encoding</span>.<span class="ruby-identifier">split</span>(<span class="ruby-string">":"</span>, <span class="ruby-value">2</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">encoding</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">String</span>)
<span class="ruby-keyword">return</span> <span class="ruby-constant">Encoding</span>.<span class="ruby-identifier">find</span>(<span class="ruby-identifier">encoding</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-constant">Encoding</span>.<span class="ruby-identifier">default_internal</span> <span class="ruby-operator">||</span> <span class="ruby-constant">Encoding</span>.<span class="ruby-identifier">default_external</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-header_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">header_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="header_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1438</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">header_fields_converter</span>
<span class="ruby-ivar">@header_fields_converter</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">build_header_fields_converter</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-normalize_converters" class="method-detail ">
<div class="method-heading">
<span class="method-name">normalize_converters</span><span
class="method-args">(converters)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="normalize_converters-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1383</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">normalize_converters</span>(<span class="ruby-identifier">converters</span>)
<span class="ruby-identifier">converters</span> <span class="ruby-operator">||=</span> []
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">converters</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Array</span>)
<span class="ruby-identifier">converters</span> = [<span class="ruby-identifier">converters</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">converters</span>.<span class="ruby-identifier">collect</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">converter</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">case</span> <span class="ruby-identifier">converter</span>
<span class="ruby-keyword">when</span> <span class="ruby-constant">Proc</span> <span class="ruby-comment"># custom code block</span>
[<span class="ruby-keyword">nil</span>, <span class="ruby-identifier">converter</span>]
<span class="ruby-keyword">else</span> <span class="ruby-comment"># by name</span>
[<span class="ruby-identifier">converter</span>, <span class="ruby-keyword">nil</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-parser" class="method-detail ">
<div class="method-heading">
<span class="method-name">parser</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="parser-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1468</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parser</span>
<span class="ruby-ivar">@parser</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">Parser</span>.<span class="ruby-identifier">new</span>(<span class="ruby-ivar">@io</span>, <span class="ruby-identifier">parser_options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-parser_enumerator" class="method-detail ">
<div class="method-heading">
<span class="method-name">parser_enumerator</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="parser_enumerator-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1477</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parser_enumerator</span>
<span class="ruby-ivar">@parser_enumerator</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-parser_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">parser_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="parser_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1426</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parser_fields_converter</span>
<span class="ruby-ivar">@parser_fields_converter</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">build_parser_fields_converter</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-parser_options" class="method-detail ">
<div class="method-heading">
<span class="method-name">parser_options</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="parser_options-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1472</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">parser_options</span>
<span class="ruby-ivar">@parser_options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-value">header_fields_converter:</span> <span class="ruby-identifier">header_fields_converter</span>,
<span class="ruby-value">fields_converter:</span> <span class="ruby-identifier">parser_fields_converter</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-raw_encoding" class="method-detail ">
<div class="method-heading">
<span class="method-name">raw_encoding</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the encoding of the internal <a href="IO.html"><code>IO</code></a> object.</p>
<div class="method-source-code" id="raw_encoding-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1416</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">raw_encoding</span>
<span class="ruby-keyword">if</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span> <span class="ruby-value">:internal_encoding</span>
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">internal_encoding</span> <span class="ruby-operator">||</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">external_encoding</span>
<span class="ruby-keyword">elsif</span> <span class="ruby-ivar">@io</span>.<span class="ruby-identifier">respond_to?</span> <span class="ruby-value">:encoding</span>
<span class="ruby-ivar">@io</span>.<span class="ruby-identifier">encoding</span>
<span class="ruby-keyword">else</span>
<span class="ruby-keyword">nil</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-writer" class="method-detail ">
<div class="method-heading">
<span class="method-name">writer</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="writer-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1481</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">writer</span>
<span class="ruby-ivar">@writer</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">Writer</span>.<span class="ruby-identifier">new</span>(<span class="ruby-ivar">@io</span>, <span class="ruby-identifier">writer_options</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-writer_fields_converter" class="method-detail ">
<div class="method-heading">
<span class="method-name">writer_fields_converter</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="writer_fields_converter-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1451</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">writer_fields_converter</span>
<span class="ruby-ivar">@writer_fields_converter</span> <span class="ruby-operator">||=</span> <span class="ruby-identifier">build_writer_fields_converter</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-writer_options" class="method-detail ">
<div class="method-heading">
<span class="method-name">writer_options</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="writer_options-source">
<pre><span class="ruby-comment"># File lib/csv.rb, line 1485</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">writer_options</span>
<span class="ruby-ivar">@writer_options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-value">header_fields_converter:</span> <span class="ruby-identifier">header_fields_converter</span>,
<span class="ruby-value">fields_converter:</span> <span class="ruby-identifier">writer_fields_converter</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>