From 6ba1abd40c4610506a638246431660a32a9b1798 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 12 May 2020 16:42:45 -0500 Subject: [ruby/csv] Enhanced Rdoc for CSV (#122) https://github.com/ruby/csv/commit/cd670595d5 --- doc/csv/col_sep.rdoc | 45 ++++++++++++++++++++ doc/csv/converters.rdoc | 45 ++++++++++++++++++++ doc/csv/empty_value.rdoc | 13 ++++++ doc/csv/field_size_limit.rdoc | 39 ++++++++++++++++++ doc/csv/force_quotes.rdoc | 17 ++++++++ doc/csv/header_converters.rdoc | 31 ++++++++++++++ doc/csv/headers.rdoc | 63 ++++++++++++++++++++++++++++ doc/csv/liberal_parsing.rdoc | 19 +++++++++ doc/csv/nil_value.rdoc | 12 ++++++ doc/csv/quote_char.rdoc | 32 +++++++++++++++ doc/csv/quote_empty.rdoc | 12 ++++++ doc/csv/return_headers.rdoc | 22 ++++++++++ doc/csv/row_sep.rdoc | 91 +++++++++++++++++++++++++++++++++++++++++ doc/csv/skip_blanks.rdoc | 31 ++++++++++++++ doc/csv/skip_lines.rdoc | 37 +++++++++++++++++ doc/csv/strip.rdoc | 15 +++++++ doc/csv/unconverted_fields.rdoc | 27 ++++++++++++ doc/csv/write_converters.rdoc | 31 ++++++++++++++ doc/csv/write_empty_value.rdoc | 15 +++++++ doc/csv/write_headers.rdoc | 29 +++++++++++++ doc/csv/write_nil_value.rdoc | 14 +++++++ 21 files changed, 640 insertions(+) create mode 100644 doc/csv/col_sep.rdoc create mode 100644 doc/csv/converters.rdoc create mode 100644 doc/csv/empty_value.rdoc create mode 100644 doc/csv/field_size_limit.rdoc create mode 100644 doc/csv/force_quotes.rdoc create mode 100644 doc/csv/header_converters.rdoc create mode 100644 doc/csv/headers.rdoc create mode 100644 doc/csv/liberal_parsing.rdoc create mode 100644 doc/csv/nil_value.rdoc create mode 100644 doc/csv/quote_char.rdoc create mode 100644 doc/csv/quote_empty.rdoc create mode 100644 doc/csv/return_headers.rdoc create mode 100644 doc/csv/row_sep.rdoc create mode 100644 doc/csv/skip_blanks.rdoc create mode 100644 doc/csv/skip_lines.rdoc create mode 100644 doc/csv/strip.rdoc create mode 100644 doc/csv/unconverted_fields.rdoc create mode 100644 doc/csv/write_converters.rdoc create mode 100644 doc/csv/write_empty_value.rdoc create mode 100644 doc/csv/write_headers.rdoc create mode 100644 doc/csv/write_nil_value.rdoc (limited to 'doc') diff --git a/doc/csv/col_sep.rdoc b/doc/csv/col_sep.rdoc new file mode 100644 index 0000000000..bb4d3ce389 --- /dev/null +++ b/doc/csv/col_sep.rdoc @@ -0,0 +1,45 @@ +====== Option +col_sep+ + +Specifies the \String field separator to be used +for both parsing and generating. +The \String will be transcoded into the data's \Encoding before use. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:col_sep) # => "," (comma) + +For examples in this section: + ary = ['a', 'b', 'c'] + +Using the default: + str = CSV.generate_line(line) + str # => "a,b,c\n" + ary = CSV.parse_line(str) + ary # => ["a", "b", "c"] + +Using +:+ (colon): + col_sep = ':' + str = CSV.generate_line(ary, col_sep: col_sep) + str # => "a:b:c\n" + ary = CSV.parse_line(str, col_sep: col_sep) + ary # => [["a", "b", "c"]] + +Using +::+ (two colons): + col_sep = '::' + str = CSV.generate_line(ary, col_sep: col_sep) + str # => "a::b::c\n" + ary = CSV.parse_line(str, col_sep: col_sep) + ary # => [["a", "b", "c"]] + +--- + +Raises an exception if given the empty \String: + col_sep = '' + # Raises ArgumentError (:col_sep must be 1 or more characters: "") + CSV.parse_line("a:b:c\n", col_sep: col_sep) + +Raises an exception if the given value is not String-convertible: + col_sep = BasicObject.new + # Raises NoMethodError (undefined method `to_s' for #) + CSV.generate_line(line, col_sep: col_sep) + # Raises NoMethodError (undefined method `to_s' for #) + CSV.parse(str, col_sep: col_sep) diff --git a/doc/csv/converters.rdoc b/doc/csv/converters.rdoc new file mode 100644 index 0000000000..993803c5d0 --- /dev/null +++ b/doc/csv/converters.rdoc @@ -0,0 +1,45 @@ +====== Option +converters+ + +Specifies a single field converter name or \Proc, +or an \Array of field converter names and Procs. + +See {Field Converters}[#class-CSV-label-Field+Converters] + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:converters) # => nil + +The value may be a single field converter name: + str = '1,2,3' + # Without a converter + ary = CSV.parse_line(str) + ary # => ["1", "2", "3"] + # With built-in converter :integer + ary = CSV.parse_line(str, converters: :integer) + ary # => [1, 2, 3] + +The value may be an \Array of field converter names: + str = '1,3.14159' + # Without converters + ary = CSV.parse_line(str) + ary # => ["1", "3.14159"] + # With built-in converters + ary = CSV.parse_line(str, converters: [:integer, :float]) + ary # => [1, 3.14159] + +The value may be a \Proc custom converter: + str = ' foo , bar , baz ' + # Without a converter + ary = CSV.parse_line(str) + ary # => [" foo ", " bar ", " baz "] + # With a custom converter + ary = CSV.parse_line(str, converters: proc {|field| field.strip }) + ary # => ["foo", "bar", "baz"] + +See also {Custom Converters}[#class-CSV-label-Custom+Converters] + +--- + +Raises an exception if the converter is not a converter name or a \Proc: + str = 'foo,0' + # Raises NoMethodError (undefined method `arity' for nil:NilClass) + CSV.parse(str, converters: :foo) diff --git a/doc/csv/empty_value.rdoc b/doc/csv/empty_value.rdoc new file mode 100644 index 0000000000..7d3bcc078c --- /dev/null +++ b/doc/csv/empty_value.rdoc @@ -0,0 +1,13 @@ +====== Option +empty_value+ + +Specifies the object that is to be substituted +for each field that has an empty \String. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:empty_value) # => "" (empty string) + +With the default, "": + CSV.parse_line('a,"",b,"",c') # => ["a", "", "b", "", "c"] + +With a different object: + CSV.parse_line('a,"",b,"",c', empty_value: 'x') # => ["a", "x", "b", "x", "c"] diff --git a/doc/csv/field_size_limit.rdoc b/doc/csv/field_size_limit.rdoc new file mode 100644 index 0000000000..797c5776fc --- /dev/null +++ b/doc/csv/field_size_limit.rdoc @@ -0,0 +1,39 @@ +====== Option +field_size_limit+ + +Specifies the \Integer field size limit. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:field_size_limit) # => nil + +This is a maximum size CSV 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 CSV will raise a MalformedCSVError, +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; +therefore the default value is +nil+ (no limit). + +For the examples in this section: + str = <<~EOT + "a","b" + " + 2345 + ","" + EOT + str # => "\"a\",\"b\"\n\"\n2345\n\",\"\"\n" + +Using the default +nil+: + ary = CSV.parse(str) + ary # => [["a", "b"], ["\n2345\n", ""]] + +Using 50: + field_size_limit = 50 + ary = CSV.parse(str, field_size_limit: field_size_limit) + ary # => [["a", "b"], ["\n2345\n", ""]] + +--- + +Raises an exception if a field is too long: + big_str = "123456789\n" * 1024 + # Raises CSV::MalformedCSVError (Field size exceeded in line 1.) + CSV.parse('valid,fields,"' + big_str + '"', field_size_limit: 2048) diff --git a/doc/csv/force_quotes.rdoc b/doc/csv/force_quotes.rdoc new file mode 100644 index 0000000000..11afd1a16c --- /dev/null +++ b/doc/csv/force_quotes.rdoc @@ -0,0 +1,17 @@ +====== Option +force_quotes+ + +Specifies the boolean that determines whether each output field is to be double-quoted. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:force_quotes) # => false + +For examples in this section: + ary = ['foo', 0, nil] + +Using the default, +false+: + str = CSV.generate_line(ary) + str # => "foo,0,\n" + +Using +true+: + str = CSV.generate_line(ary, force_quotes: true) + str # => "\"foo\",\"0\",\"\"\n" diff --git a/doc/csv/header_converters.rdoc b/doc/csv/header_converters.rdoc new file mode 100644 index 0000000000..329d96a897 --- /dev/null +++ b/doc/csv/header_converters.rdoc @@ -0,0 +1,31 @@ +====== Option +header_converters+ + +Specifies a \String converter name or an \Array of converter names. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:header_converters) # => nil + +Identical in functionality to option {converters}[#class-CSV-label-Option+converters] +except that: +- The converters apply only to the header row. +- The built-in header converters are +:downcase+ and +:symbol+. + +Examples: + str = <<-EOT + foo,0 + bar,1 + baz,2 + EOT + headers = ['Name', 'Value'] + # With no header converter + csv = CSV.parse(str, headers: headers) + csv.headers # => ["Name", "Value"] + # With header converter :downcase + csv = CSV.parse(str, headers: headers, header_converters: :downcase) + csv.headers # => ["name", "value"] + # With header converter :symbol + csv = CSV.parse(str, headers: headers, header_converters: :symbol) + csv.headers # => [:name, :value] + # With both + csv = CSV.parse(str, headers: headers, header_converters: [:downcase, :symbol]) + csv.headers # => [:name, :value] diff --git a/doc/csv/headers.rdoc b/doc/csv/headers.rdoc new file mode 100644 index 0000000000..0ea151f24b --- /dev/null +++ b/doc/csv/headers.rdoc @@ -0,0 +1,63 @@ +====== Option +headers+ + +Specifies a boolean, \Symbol, \Array, or \String to be used +to define column headers. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:headers) # => false + +--- + +Without +headers+: + str = <<-EOT + Name,Count + foo,0 + bar,1 + bax,2 + EOT + csv = CSV.new(str) + csv # => # + csv.headers # => nil + csv.shift # => ["Name", "Count"] + +--- + +If set to +true+ or the \Symbol +:first_row+, +the first row of the data is treated as a row of headers: + str = <<-EOT + Name,Count + foo,0 + bar,1 + bax,2 + EOT + csv = CSV.new(str, headers: true) + csv # => # + csv.headers # => ["Name", "Count"] + csv.shift # => # + +--- + +If set to an \Array, the \Array elements are treated as headers: + str = <<-EOT + foo,0 + bar,1 + bax,2 + EOT + csv = CSV.new(str, headers: ['Name', 'Count']) + csv + csv.headers # => ["Name", "Count"] + csv.shift # => # + +--- + +If set to a \String +str+, method CSV::parse_line(str, options) is called +with the current +options+, and the returned \Array is treated as headers: + str = <<-EOT + foo,0 + bar,1 + bax,2 + EOT + csv = CSV.new(str, headers: 'Name,Count') + csv + csv.headers # => ["Name", "Count"] + csv.shift # => # diff --git a/doc/csv/liberal_parsing.rdoc b/doc/csv/liberal_parsing.rdoc new file mode 100644 index 0000000000..b8b9b00c98 --- /dev/null +++ b/doc/csv/liberal_parsing.rdoc @@ -0,0 +1,19 @@ +====== Option +liberal_parsing+ + +Specifies the boolean value that determines whether +CSV will attempt to parse input not conformant with RFC 4180, +such as double quotes in unquoted fields. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:liberal_parsing) # => false + +For examples in this section: + str = 'is,this "three, or four",fields' + +Without +liberal_parsing+: + # Raises CSV::MalformedCSVError (Illegal quoting in str 1.) + CSV.parse_line(str) + +With +liberal_parsing+: + ary = CSV.parse_line(str, liberal_parsing: true) + ary # => ["is", "this \"three", " or four\"", "fields"] diff --git a/doc/csv/nil_value.rdoc b/doc/csv/nil_value.rdoc new file mode 100644 index 0000000000..412e8795e8 --- /dev/null +++ b/doc/csv/nil_value.rdoc @@ -0,0 +1,12 @@ +====== Option +nil_value+ + +Specifies the object that is to be substituted for each null (no-text) field. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:nil_value) # => nil + +With the default, +nil+: + CSV.parse_line('a,,b,,c') # => ["a", nil, "b", nil, "c"] + +With a different object: + CSV.parse_line('a,,b,,c', nil_value: 0) # => ["a", 0, "b", 0, "c"] diff --git a/doc/csv/quote_char.rdoc b/doc/csv/quote_char.rdoc new file mode 100644 index 0000000000..eb2ad9c0c8 --- /dev/null +++ b/doc/csv/quote_char.rdoc @@ -0,0 +1,32 @@ +====== Option +quote_char+ + +Specifies the character (\String of length 1) used used to quote fields +in both parsing and generating. +This String will be transcoded into the data's \Encoding before use. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:quote_char) # => "\"" (backslash) + +This is useful for an application that incorrectly uses ' (single-quote) +to quote fields, instead of the correct " (double-quote). + +Using the default: + ary = ['a', 'b', '"c"', 'd'] + str = CSV.generate_line(ary) + str # => "a,b,\"\"\"c\"\"\",d\n" + ary = CSV.parse_line(str) + ary # => ["a", "b", "\"c\"", "d"] + +Using ' (single-quote): + quote_char = "'" + ary = ['a', 'b', '\'c\'', 'd'] + str = CSV.generate_line(ary, quote_char: quote_char) + str # => "a,b,'''c''',d\n" + ary = CSV.parse_line(str, quote_char: quote_char) + ary # => [["a", "b", "'c'", "d"]] + +--- + +Raises an exception if the \String length is greater than 1: + # Raises ArgumentError (:quote_char has to be nil or a single character String) + CSV.new('', quote_char: 'xx') diff --git a/doc/csv/quote_empty.rdoc b/doc/csv/quote_empty.rdoc new file mode 100644 index 0000000000..4c5645c662 --- /dev/null +++ b/doc/csv/quote_empty.rdoc @@ -0,0 +1,12 @@ +====== Option +quote_empty+ + +Specifies the boolean that determines whether an empty value is to be double-quoted. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:quote_empty) # => true + +With the default +true+: + CSV.generate_line(['"', ""]) # => "\"\"\"\",\"\"\n" + +With +false+: + CSV.generate_line(['"', ""], quote_empty: false) # => "\"\"\"\",\n" diff --git a/doc/csv/return_headers.rdoc b/doc/csv/return_headers.rdoc new file mode 100644 index 0000000000..45d2e3f3de --- /dev/null +++ b/doc/csv/return_headers.rdoc @@ -0,0 +1,22 @@ +====== Option +return_headers+ + +Specifies the boolean that determines whether method #shift +returns or ignores the header row. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:return_headers) # => false + +Examples: + str = <<-EOT + Name,Count + foo,0 + bar,1 + bax,2 + EOT + # Without return_headers first row is str. + csv = CSV.new(str, headers: true) + csv.shift # => # + # With return_headers first row is headers. + csv = CSV.new(str, headers: true, return_headers: true) + csv.shift # => # + diff --git a/doc/csv/row_sep.rdoc b/doc/csv/row_sep.rdoc new file mode 100644 index 0000000000..a9e2c5b2fb --- /dev/null +++ b/doc/csv/row_sep.rdoc @@ -0,0 +1,91 @@ +====== Option +row_sep+ + +Specifies the row separator, a \String or the \Symbol :auto (see below), +to be used for both parsing and generating. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:row_sep) # => :auto + +--- + +When +row_sep+ is a \String, that \String becomes the row separator. +The String will be transcoded into the data's Encoding before use. + +Using "\n": + str = CSV.generate do |csv| + csv << [:foo, 0] + csv << [:bar, 1] + csv << [:baz, 2] + end + str # => "foo,0\nbar,1\nbaz,2\n" + ary = CSV.parse(str) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +Using | (pipe): + row_sep = '|' + str = CSV.generate(row_sep: row_sep) do |csv| + csv << [:foo, 0] + csv << [:bar, 1] + csv << [:baz, 2] + end + str # => "foo,0|bar,1|baz,2|" + ary = CSV.parse(str, row_sep: row_sep) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +Using -- (two hyphens): + row_sep = '--' + str = CSV.generate(row_sep: row_sep) do |csv| + csv << [:foo, 0] + csv << [:bar, 1] + csv << [:baz, 2] + end + str # => "foo,0--bar,1--baz,2--" + ary = CSV.parse(str, row_sep: row_sep) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +Using '' (empty string): + row_sep = '' + str = CSV.generate(row_sep: row_sep) do |csv| + csv << [:foo, 0] + csv << [:bar, 1] + csv << [:baz, 2] + end + str # => "foo,0bar,1baz,2" + ary = CSV.parse(str, row_sep: row_sep) + ary # => [["foo", "0bar", "1baz", "2"]] + +--- + +When +row_sep+ is the \Symbol +:auto+ (the default), +invokes auto-discovery of the row separator. + +Auto-discovery reads ahead in the data looking for the next \r\n, +\n+, or +\r+ sequence. +The sequence will be selected even if it occurs in a quoted field, +assuming that you would have the same line endings there. + + row_sep = :auto + str = CSV.generate(row_sep: row_sep) do |csv| + csv << [:foo, 0] + csv << [:bar, 1] + csv << [:baz, 2] + end + str # => "foo,0\nbar,1\nbaz,2\n" + ary = CSV.parse(str, row_sep: row_sep) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +The default $INPUT_RECORD_SEPARATOR ($/) is used +if any of the following is true: +* None of those sequences is found. +* Data is +ARGF+, +STDIN+, +STDOUT+, or +STDERR+. +* The stream is only available for output. + +Obviously, discovery takes a little time. Set manually if speed is important. Also note that IO 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. + +--- + +Raises an exception if the given value is not String-convertible: + row_sep = BasicObject.new + # Raises NoMethodError (undefined method `to_s' for #) + CSV.generate_line(ary, row_sep: row_sep) + # Raises NoMethodError (undefined method `to_s' for #) + CSV.parse(str, row_sep: row_sep) diff --git a/doc/csv/skip_blanks.rdoc b/doc/csv/skip_blanks.rdoc new file mode 100644 index 0000000000..2c8f7b7bb8 --- /dev/null +++ b/doc/csv/skip_blanks.rdoc @@ -0,0 +1,31 @@ +====== Option +skip_blanks+ + +Specifies a boolean that determines whether blank lines in the input will be ignored; +a line that contains a column separator is not considered to be blank. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:skip_blanks) # => false + +See also option {skiplines}[#class-CSV-label-Option+skip_lines]. + +For examples in this section: + str = <<-EOT + foo,0 + + bar,1 + baz,2 + + , + EOT + +Using the default, +false+: + ary = CSV.parse(str) + ary # => [["foo", "0"], [], ["bar", "1"], ["baz", "2"], [], [nil, nil]] + +Using +true+: + ary = CSV.parse(str, skip_blanks: true) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]] + +Using a truthy value: + ary = CSV.parse(str, skip_blanks: :foo) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]] diff --git a/doc/csv/skip_lines.rdoc b/doc/csv/skip_lines.rdoc new file mode 100644 index 0000000000..1481c40a5f --- /dev/null +++ b/doc/csv/skip_lines.rdoc @@ -0,0 +1,37 @@ +====== Option +skip_lines+ + +Specifies an object to use in identifying comment lines in the input that are to be ignored: +* If a \Regexp, ignores lines that match it. +* If a \String, converts it to a \Regexp, ignores lines that match it. +* If +nil+, no lines are considered to be comments. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:skip_lines) # => nil + +For examples in this section: + str = <<-EOT + # Comment + foo,0 + bar,1 + baz,2 + # Another comment + EOT + str # => "# Comment\nfoo,0\nbar,1\nbaz,2\n# Another comment\n" + +Using the default, +nil+: + ary = CSV.parse(str) + ary # => [["# Comment"], ["foo", "0"], ["bar", "1"], ["baz", "2"], ["# Another comment"]] + +Using a \Regexp: + ary = CSV.parse(str, skip_lines: /^#/) + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +Using a \String: + ary = CSV.parse(str, skip_lines: '#') + ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +--- + +Raises an exception if given an object that is not a \Regexp, a \String, or +nil+: + # Raises ArgumentError (:skip_lines has to respond to #match: 0) + CSV.parse(str, skip_lines: 0) diff --git a/doc/csv/strip.rdoc b/doc/csv/strip.rdoc new file mode 100644 index 0000000000..56ae4310c3 --- /dev/null +++ b/doc/csv/strip.rdoc @@ -0,0 +1,15 @@ +====== Option +strip+ + +Specifies the boolean value that determines whether +whitespace is stripped from each input field. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:strip) # => false + +With default value +false+: + ary = CSV.parse_line(' a , b ') + ary # => [" a ", " b "] + +With value +true+: + ary = CSV.parse_line(' a , b ', strip: true) + ary # => ["a", "b"] diff --git a/doc/csv/unconverted_fields.rdoc b/doc/csv/unconverted_fields.rdoc new file mode 100644 index 0000000000..3e7f839d49 --- /dev/null +++ b/doc/csv/unconverted_fields.rdoc @@ -0,0 +1,27 @@ +====== Option +unconverted_fields+ + +Specifies the boolean that determines whether unconverted field values are to be available. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:unconverted_fields) # => nil + +The unconverted field values are those found in the source data, +prior to any conversions performed via option +converters+. + +When option +unconverted_fields+ is +true+, +each returned row (\Array or \CSV::Row) has an added method, ++unconverted_fields+, that returns the unconverted field values: + str = <<-EOT + foo,0 + bar,1 + baz,2 + EOT + # Without unconverted_fields + csv = CSV.parse(str, converters: :integer) + csv # => [["foo", 0], ["bar", 1], ["baz", 2]] + csv.first.respond_to?(:unconverted_fields) # => false + # With unconverted_fields + csv = CSV.parse(str, converters: :integer, unconverted_fields: true) + csv # => [["foo", 0], ["bar", 1], ["baz", 2]] + csv.first.respond_to?(:unconverted_fields) # => true + csv.first.unconverted_fields # => ["foo", "0"] diff --git a/doc/csv/write_converters.rdoc b/doc/csv/write_converters.rdoc new file mode 100644 index 0000000000..c7367b96fd --- /dev/null +++ b/doc/csv/write_converters.rdoc @@ -0,0 +1,31 @@ +====== Option +write_converters+ + +Specifies the \Proc or \Array of Procs that are to be called +for converting each output field. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:write_converters) # => nil + +With no write converter: + str = CSV.generate_line(["\na\n", "\tb\t", " c "]) + str # => "\"\na\n\",\tb\t, c \n" + +With a write converter: + strip_converter = lambda {|field| field.strip } + str = CSV.generate_line(["\na\n", "\tb\t", " c "], write_converters: strip_converter) + str # => "a,b,c\n" + +With two write converters (called in order): + upcase_converter = lambda {|field| field.upcase } + downcase_converter = lambda {|field| field.downcase } + write_converters = [upcase_converter, downcase_converter] + str = CSV.generate_line(['a', 'b', 'c'], write_converters: write_converters) + str # => "a,b,c\n" + +--- + +Raises an exception if the converter returns a value that is neither +nil+ +nor \String-convertible: + bad_converter = lambda {|field| BasicObject.new } + # Raises NoMethodError (undefined method `is_a?' for #) + CSV.generate_line(['a', 'b', 'c'], write_converters: bad_converter) \ No newline at end of file diff --git a/doc/csv/write_empty_value.rdoc b/doc/csv/write_empty_value.rdoc new file mode 100644 index 0000000000..67be5662cb --- /dev/null +++ b/doc/csv/write_empty_value.rdoc @@ -0,0 +1,15 @@ +====== Option +write_empty_value+ + +Specifies the object that is to be substituted for each field +that has an empty \String. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:write_empty_value) # => "" + +Without the option: + str = CSV.generate_line(['a', '', 'c', '']) + str # => "a,\"\",c,\"\"\n" + +With the option: + str = CSV.generate_line(['a', '', 'c', ''], write_empty_value: "x") + str # => "a,x,c,x\n" diff --git a/doc/csv/write_headers.rdoc b/doc/csv/write_headers.rdoc new file mode 100644 index 0000000000..f9faa9d438 --- /dev/null +++ b/doc/csv/write_headers.rdoc @@ -0,0 +1,29 @@ +====== Option +write_headers+ + +Specifies the boolean that determines whether a header row is included in the output; +ignored if there are no headers. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:write_headers) # => nil + +Without +write_headers+: + file_path = 't.csv' + CSV.open(file_path,'w', + :headers => ['Name','Value'] + ) do |csv| + csv << ['foo', '0'] + end + CSV.open(file_path) do |csv| + csv.shift + end # => ["foo", "0"] + +With +write_headers+": + CSV.open(file_path,'w', + :write_headers=> true, + :headers => ['Name','Value'] + ) do |csv| + csv << ['foo', '0'] + end + CSV.open(file_path) do |csv| + csv.shift + end # => ["Name", "Value"] diff --git a/doc/csv/write_nil_value.rdoc b/doc/csv/write_nil_value.rdoc new file mode 100644 index 0000000000..8560f644b3 --- /dev/null +++ b/doc/csv/write_nil_value.rdoc @@ -0,0 +1,14 @@ +====== Option +write_nil_value+ + +Specifies the object that is to be substituted for each +nil+ field. + +Default value: + CSV::DEFAULT_OPTIONS.fetch(:write_nil_value) # => nil + +Without the option: + str = CSV.generate_line(['a', nil, 'c', nil]) + str # => "a,,c,\n" + +With the option: + str = CSV.generate_line(['a', nil, 'c', nil], write_nil_value: "x") + str # => "a,x,c,x\n" -- cgit v1.2.3