From d9749b4715168ccce020dd43b4815e365881f73e Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Wed, 15 Jul 2020 15:37:17 -0500 Subject: [ruby/csv] RDoc for converters (#157) * More on RDoc for converters * More on RDoc for converters * Fix indent Co-authored-by: Sutou Kouhei https://github.com/ruby/csv/commit/6044976160 --- doc/csv/options/generating/write_converters.rdoc | 14 +++++---- doc/csv/options/parsing/converters.rdoc | 37 +++++++++++----------- doc/csv/options/parsing/header_converters.rdoc | 40 +++++++++++++++--------- 3 files changed, 53 insertions(+), 38 deletions(-) (limited to 'doc/csv') diff --git a/doc/csv/options/generating/write_converters.rdoc b/doc/csv/options/generating/write_converters.rdoc index c7367b96fd..6e5fae5fda 100644 --- a/doc/csv/options/generating/write_converters.rdoc +++ b/doc/csv/options/generating/write_converters.rdoc @@ -1,7 +1,7 @@ ====== Option +write_converters+ -Specifies the \Proc or \Array of Procs that are to be called -for converting each output field. +Specifies converters to be used in generating fields. +See {Write Converters}[#class-CSV-label-Write+Converters] Default value: CSV::DEFAULT_OPTIONS.fetch(:write_converters) # => nil @@ -11,21 +11,23 @@ With no write converter: str # => "\"\na\n\",\tb\t, c \n" With a write converter: - strip_converter = lambda {|field| field.strip } + strip_converter = proc {|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 } + upcase_converter = proc {|field| field.upcase } + downcase_converter = proc {|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" +See also {Write Converters}[#class-CSV-label-Write+Converters] + --- Raises an exception if the converter returns a value that is neither +nil+ nor \String-convertible: - bad_converter = lambda {|field| BasicObject.new } + bad_converter = proc {|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/options/parsing/converters.rdoc b/doc/csv/options/parsing/converters.rdoc index 993803c5d0..211fa48de6 100644 --- a/doc/csv/options/parsing/converters.rdoc +++ b/doc/csv/options/parsing/converters.rdoc @@ -1,41 +1,42 @@ ====== Option +converters+ -Specifies a single field converter name or \Proc, -or an \Array of field converter names and Procs. - +Specifies converters to be used in parsing fields. 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: +The value may be a field converter name +(see {Stored Converters}[#class-CSV-label-Stored+Converters]): str = '1,2,3' # Without a converter - ary = CSV.parse_line(str) - ary # => ["1", "2", "3"] + array = CSV.parse_line(str) + array # => ["1", "2", "3"] # With built-in converter :integer - ary = CSV.parse_line(str, converters: :integer) - ary # => [1, 2, 3] + array = CSV.parse_line(str, converters: :integer) + array # => [1, 2, 3] -The value may be an \Array of field converter names: +The value may be a converter list +(see {Converter Lists}[#class-CSV-label-Converter+Lists]): str = '1,3.14159' # Without converters - ary = CSV.parse_line(str) - ary # => ["1", "3.14159"] + array = CSV.parse_line(str) + array # => ["1", "3.14159"] # With built-in converters - ary = CSV.parse_line(str, converters: [:integer, :float]) - ary # => [1, 3.14159] + array = CSV.parse_line(str, converters: [:integer, :float]) + array # => [1, 3.14159] The value may be a \Proc custom converter: +(see {Custom Field Converters}[#class-CSV-label-Custom+Field+Converters]): str = ' foo , bar , baz ' # Without a converter - ary = CSV.parse_line(str) - ary # => [" foo ", " bar ", " baz "] + array = CSV.parse_line(str) + array # => [" foo ", " bar ", " baz "] # With a custom converter - ary = CSV.parse_line(str, converters: proc {|field| field.strip }) - ary # => ["foo", "bar", "baz"] + array = CSV.parse_line(str, converters: proc {|field| field.strip }) + array # => ["foo", "bar", "baz"] -See also {Custom Converters}[#class-CSV-label-Custom+Converters] +See also {Custom Field Converters}[#class-CSV-label-Custom+Field+Converters] --- diff --git a/doc/csv/options/parsing/header_converters.rdoc b/doc/csv/options/parsing/header_converters.rdoc index 329d96a897..309180805f 100644 --- a/doc/csv/options/parsing/header_converters.rdoc +++ b/doc/csv/options/parsing/header_converters.rdoc @@ -1,6 +1,7 @@ ====== Option +header_converters+ -Specifies a \String converter name or an \Array of converter names. +Specifies converters to be used in parsing headers. +See {Header Converters}[#class-CSV-label-Header+Converters] Default value: CSV::DEFAULT_OPTIONS.fetch(:header_converters) # => nil @@ -10,22 +11,33 @@ except that: - The converters apply only to the header row. - The built-in header converters are +:downcase+ and +:symbol+. -Examples: +This section assumes prior execution of: str = <<-EOT + Name,Value 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] + table = CSV.parse(str, headers: true) + table.headers # => ["Name", "Value"] + +The value may be a header converter name +(see {Stored Converters}[#class-CSV-label-Stored+Converters]): + table = CSV.parse(str, headers: true, header_converters: :downcase) + table.headers # => ["name", "value"] + +The value may be a converter list +(see {Converter Lists}[#class-CSV-label-Converter+Lists]): + header_converters = [:downcase, :symbol] + table = CSV.parse(str, headers: true, header_converters: header_converters) + table.headers # => [:name, :value] + +The value may be a \Proc custom converter +(see {Custom Header Converters}[#class-CSV-label-Custom+Header+Converters]): + upcase_converter = proc {|field| field.upcase } + table = CSV.parse(str, headers: true, header_converters: upcase_converter) + table.headers # => ["NAME", "VALUE"] + +See also {Custom Header Converters}[#class-CSV-label-Custom+Header+Converters] + -- cgit v1.2.3