|
109 | 109 | #
|
110 | 110 | # The most generic interface of the library is:
|
111 | 111 | #
|
112 |
| -# csv = CSV.new(string_or_io, **options) |
| 112 | +# csv = CSV.new(io, **options) |
113 | 113 | #
|
114 | 114 | # # Reading: IO object should be open for read
|
115 | 115 | # csv.read # => array of rows
|
@@ -809,19 +809,37 @@ def generate(str=nil, **options)
|
809 | 809 | csv.string # return final String
|
810 | 810 | end
|
811 | 811 |
|
| 812 | + # :call-seq: |
| 813 | + # CSV.generate_line(ary) |
| 814 | + # CSV.generate_line(ary, **options) |
812 | 815 | #
|
813 |
| - # This method is a shortcut for converting a single row (Array) into a CSV |
814 |
| - # String. |
| 816 | + # Returns the \String created by generating \CSV from +ary+ |
| 817 | + # using the specified +options+. |
815 | 818 | #
|
816 |
| - # See {Options for Generating}[#class-CSV-label-Options+for+Generating]. |
| 819 | + # Argument +ary+ must be an \Array. |
| 820 | + # |
| 821 | + # Special options: |
| 822 | + # * Option <tt>:row_sep</tt> defaults to <tt>$INPUT_RECORD_SEPARATOR</tt> |
| 823 | + # (<tt>$/</tt>).: |
| 824 | + # $INPUT_RECORD_SEPARATOR # => "\n" |
| 825 | + # * This method accepts an additional option, <tt>:encoding</tt>, which sets the base |
| 826 | + # Encoding for the output. This method will try to guess your Encoding from |
| 827 | + # the first non-+nil+ field in +row+, if possible, but you may need to use |
| 828 | + # this parameter as a backup plan. |
| 829 | + # |
| 830 | + # For other +options+, |
| 831 | + # see {Options for Generating}[#class-CSV-label-Options+for+Generating]. |
817 | 832 | #
|
818 |
| - # This method accepts an additional option, <tt>:encoding</tt>, which sets the base |
819 |
| - # Encoding for the output. This method will try to guess your Encoding from |
820 |
| - # the first non-+nil+ field in +row+, if possible, but you may need to use |
821 |
| - # this parameter as a backup plan. |
| 833 | + # --- |
822 | 834 | #
|
823 |
| - # The <tt>:row_sep</tt> +option+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt> |
824 |
| - # (<tt>$/</tt>) when calling this method. |
| 835 | + # Returns the \String generated from an \Array: |
| 836 | + # CSV.generate_line(['foo', '0']) # => "foo,0\n" |
| 837 | + # |
| 838 | + # --- |
| 839 | + # |
| 840 | + # Raises an exception if +ary+ is not an \Array: |
| 841 | + # # Raises NoMethodError (undefined method `find' for :foo:Symbol) |
| 842 | + # CSV.generate_line(:foo) |
825 | 843 | #
|
826 | 844 | def generate_line(row, **options)
|
827 | 845 | options = {row_sep: $INPUT_RECORD_SEPARATOR}.merge(options)
|
@@ -955,12 +973,41 @@ def parse(str, **options, &block)
|
955 | 973 | end
|
956 | 974 | end
|
957 | 975 |
|
| 976 | + # :call-seq: |
| 977 | + # CSV.parse_line(string) |
| 978 | + # CSV.parse_line(io) |
| 979 | + # CSV.parse_line(string, **options) |
| 980 | + # CSV.parse_line(io, **options) |
958 | 981 | #
|
959 |
| - # This method is a shortcut for converting a single line of a CSV String into |
960 |
| - # an Array. Note that if +line+ contains multiple rows, anything beyond the |
961 |
| - # first row is ignored. |
| 982 | + # Returns the new \Array created by parsing the first line of +string+ or +io+ |
| 983 | + # using the specified +options+. |
962 | 984 | #
|
963 |
| - # See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]. |
| 985 | + # Argument +string+ should be a \String object; |
| 986 | + # it will be put into a new \StringIO object positioned at the beginning. |
| 987 | + # |
| 988 | + # Argument +io+ should be an \IO object; it will be positioned at the beginning. |
| 989 | + # |
| 990 | + # For +options+, see {Options for Parsing}[#class-CSV-label-Options+for+Parsing]. |
| 991 | + # |
| 992 | + # --- |
| 993 | + # Returns data from the first line from a String object: |
| 994 | + # CSV.parse_line('foo,0') # => ["foo", "0"] |
| 995 | + # |
| 996 | + # Returns data from the first line from a File object: |
| 997 | + # File.write('t.csv', 'foo,0') |
| 998 | + # CSV.parse_line(File.open('t.csv')) # => ["foo", "0"] |
| 999 | + # |
| 1000 | + # Ignores lines after the first: |
| 1001 | + # CSV.parse_line("foo,0\nbar,1\nbaz,2") # => ["foo", "0"] |
| 1002 | + # |
| 1003 | + # Returns +nil+ if the argument is an empty \String: |
| 1004 | + # CSV.parse_line('') # => nil |
| 1005 | + # |
| 1006 | + # --- |
| 1007 | + # |
| 1008 | + # Raises an exception if the argument is +nil+: |
| 1009 | + # # Raises ArgumentError (Cannot parse nil as CSV): |
| 1010 | + # CSV.parse_line(nil) |
964 | 1011 | #
|
965 | 1012 | def parse_line(line, **options)
|
966 | 1013 | new(line, **options).each.first
|
@@ -1008,22 +1055,49 @@ def table(path, **options)
|
1008 | 1055 | end
|
1009 | 1056 | end
|
1010 | 1057 |
|
| 1058 | + # :call-seq: |
| 1059 | + # CSV.new(string) |
| 1060 | + # CSV.new(io) |
| 1061 | + # CSV.new(string, **options) |
| 1062 | + # CSV.new(io, **options) |
| 1063 | + # |
| 1064 | + # Returns the new \CSV object created using +string+ or +io+ |
| 1065 | + # and the specified +options+. |
| 1066 | + # |
| 1067 | + # Argument +string+ should be a \String object; |
| 1068 | + # it will be put into a new \StringIO object positioned at the beginning. |
| 1069 | + # |
| 1070 | + # Argument +io+ should be an \IO object; it will be positioned at the beginning. |
| 1071 | + # |
| 1072 | + # To position at the end, for appending, use method CSV.generate. |
| 1073 | + # For any other positioning, pass a preset StringIO object instead. |
| 1074 | + # |
| 1075 | + # In addition to the \CSV instance methods, several \IO |
| 1076 | + # methods are delegated. See CSV::open for a complete list. |
| 1077 | + # |
| 1078 | + # For +options+, see: |
| 1079 | + # * {Options for Parsing}[#class-CSV-label-Options+for+Parsing] |
| 1080 | + # * {Options for Generating}[#class-CSV-label-Options+for+Generating] |
| 1081 | + # |
| 1082 | + # For performance reasons, the options cannot be overridden |
| 1083 | + # in a \CSV object, so the options specified here will endure. |
| 1084 | + # |
| 1085 | + # --- |
1011 | 1086 | #
|
1012 |
| - # This constructor will wrap either a String or IO object passed in +data+ for |
1013 |
| - # reading and/or writing. In addition to the CSV instance methods, several IO |
1014 |
| - # methods are delegated. (See CSV::open() for a complete list.) If you pass |
1015 |
| - # a String for +data+, you can later retrieve it (after writing to it, for |
1016 |
| - # example) with CSV.string(). |
| 1087 | + # Create a \CSV object from a \String object: |
| 1088 | + # csv = CSV.new('foo,0') |
| 1089 | + # csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\""> |
1017 | 1090 | #
|
1018 |
| - # Note that a wrapped String will be positioned at the beginning (for |
1019 |
| - # reading). If you want it at the end (for writing), use CSV::generate(). |
1020 |
| - # If you want any other positioning, pass a preset StringIO object instead. |
| 1091 | + # Create a \CSV object from a \File object: |
| 1092 | + # File.write('t.csv', 'foo,0') |
| 1093 | + # csv = CSV.new(File.open('t.csv')) |
| 1094 | + # csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\""> |
1021 | 1095 | #
|
1022 |
| - # See {Options for Parsing}[#class-CSV-label-Options+for+Parsing] |
1023 |
| - # and {Options for Generating}[#class-CSV-label-Options+for+Generating]. |
| 1096 | + # --- |
1024 | 1097 | #
|
1025 |
| - # Options cannot be overridden in the instance methods for performance reasons, |
1026 |
| - # so be sure to set what you want here. |
| 1098 | + # Raises an exception if the argument is +nil+: |
| 1099 | + # # Raises ArgumentError (Cannot parse nil as CSV): |
| 1100 | + # CSV.new(nil) |
1027 | 1101 | #
|
1028 | 1102 | def initialize(data,
|
1029 | 1103 | col_sep: ",",
|
|
0 commit comments