dsv 0.12.4

data/Gemfile

@@ -0,0 +1,5 @@
+# Gemfile
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2006-2026 thoran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# dsv
+
+Delimiter-separated values for Ruby: CSV and its relatives, read and written with any delimiter on either side, in three small files.
+
+This began in November 2006 as `csv2to`, became `CSVFile`, then `SimpleCSV`, and was a personal library for twenty years before it was a gem. The 2011 case for it against the CSV parsers of the day was that it was smaller, cleaner, faster, and gave keyed access to a row's columns. The first, second and fourth still hold; the third is measured, not claimed, and will be reported when it is.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dsv'
+```
+
+or install it directly:
+
+```shell
+$ gem install dsv
+```
+
+
+## Usage
+
+### Reading
+
+A row is a plain Hash keyed by the header, so it merges, serialises and compares as a Hash does:
+
+```ruby
+require 'dsv'
+
+DSV.read('people.csv', headers: true)
+# => [{"name" => "Ada", "born" => "1815"}, {"name" => "Charles", "born" => "1791"}]
+```
+
+Without a header row the keys are positions:
+
+```ruby
+DSV.read("1,2,3\n4,5,6\n")
+# => [{0 => "1", 1 => "2", 2 => "3"}, {0 => "4", 1 => "5", 2 => "6"}]
+```
+
+A String that names an existing file is read as a file; any other String is read as text.
+
+### Selecting columns
+
+Name the columns wanted, by name or by position, and the rows hold only those:
+
+```ruby
+DSV.read('people.csv', 'name', headers: true)
+# => [{"name" => "Ada"}, {"name" => "Charles"}]
+
+DSV.read('people.csv', headers: true, selected_columns: ['name'])
+```
+
+### Enumerating from the class
+
+The Enumerable calls are available on a source directly, each taking the same options:
+
+```ruby
+DSV.each('people.csv', headers: true){|row| puts row['name']}
+DSV.select('people.csv', headers: true){|row| row['born'] < '1800'}
+DSV.detect('people.csv', headers: true){|row| row['name'] == 'Ada'}
+DSV.collect('people.csv', headers: true){|row| row['name'].upcase}
+```
+
+`foreach`, `map`, `find_all` and `find` are aliases.
+
+### Any delimiter
+
+The column separator is a String or a Regexp; the row separator is a String:
+
+```ruby
+DSV.read('people.tsv', headers: true, column_separator: "\t")
+DSV.read('people.txt', headers: true, column_separator: /,\s*/)
+DSV.read('people.csv', headers: true, row_separator: "\r\n")
+```
+
+`col_sep:` and `row_sep:` are accepted as spellings of those. Writing takes the same two options, so a file round-trips through whatever it was read with.
+
+### Quoting
+
+Unspecified, quoting follows RFC 4180: a quoted field may hold the separator or the row separator, a doubled quote inside it reads as one quote, and a row's quotes are read only when the row holds one. Naming a mode is faster, since each is a direct string operation on the contract it names:
+
+```ruby
+DSV.read('plain.csv', headers: true, quote: :none)    # no field is quoted; quotes are data
+DSV.read('quoted.csv', headers: true, quote: :double)  # every field is quoted, as DSV writes them
+```
+
+### Writing
+
+Set the columns, give the rows as Hashes, and write:
+
+```ruby
+DSV.open('out.csv', mode: 'w', headers: true, columns: ['name', 'born']) do |dsv|
+  dsv.rows = [{'name' => 'Ada', 'born' => 1815}]
+  dsv.write
+end
+# out.csv:
+# "name","born"
+# "Ada","1815"
+```
+
+Every field is quoted, which is the `:double` contract on the way back in, and a quote inside a value is doubled. `quote: :none` writes bare values, `:single` uses single quotes. A `nil` writes as an empty field. Rows without columns defined are written from their own keys, and if the keys are names they become the header.
+
+Under `r+` a file is read, changed and written back in place; reading never alters the file, and the first write replaces it:
+
+```ruby
+DSV.open('people.csv', mode: 'r+', headers: true) do |dsv|
+  dsv.rows = dsv.read.collect{|row| row.merge('born' => row['born'].to_i + 1)}
+  dsv.write
+end
+```
+
+### Repeated header names
+
+Where the header repeats a name, `columns` maps the name to every position and the row holds the values under that name as an Array, in position order:
+
+```ruby
+DSV.columns("a,a,b\n1,2,3\n", headers: true)  # => {"a" => [0, 1], "b" => 2}
+DSV.read("a,a,b\n1,2,3\n", headers: true)     # => [{"a" => ["1", "2"], "b" => "3"}]
+```
+
+So a value is a String, or an Array where the header repeats the name. `Array(row['a'])` reads a column that may be either, and `repeated_names` says which names those are. Writing spreads an Array back over its positions.
+
+### One line
+
+```ruby
+DSV.parse_line("1,\"2,3\",4\n")  # => ["1", "2,3", "4"]
+```
+
+
+## What it is not
+
+There are no converters, no `Row` or `Table` classes, and no encoding handling: a value is always a String, a row is always a Hash. Anything wanted beyond that is in `TODO`, in the order it is likely to arrive.
+
+
+## License
+
+MIT. See `LICENSE`.

data/Rakefile

@@ -0,0 +1,22 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+  t.warning = false
+end
+
+task default: :test
+
+desc "Run tests"
+task :spec => :test
+
+desc "Show version"
+task :version do
+  require_relative './lib/DSV/VERSION'
+  puts "dsv #{DSV::VERSION}"
+end

data/TODO

@@ -0,0 +1,24 @@
+# TODO
+
+## 0.12.x, before the gem is published
+
+1. A path is told from content by the call, not by a guess: .read, .foreach, .open and the other path-taking class methods take a path, .parse takes text, new keeps the guess with a switch to say which, and a path under a read mode that names no file raises rather than being read as text.
+2. Selection as a keyword on the calls, only: or select:, columns: being taken; the positional form kept or retired; selected_columns: renamed to match.
+3. The instance-level header_row accessor renamed headers?, the class-level header_row now being the row.
+4. << to append a row and generate to build a string, the two writing calls a CSV user reaches for first.
+
+## 0.13.0, speed
+
+5. The saved-up speed change, with the evidence in the reconciliation: two string predicates in place of four regex matches per piece in split_csv; rows built by zip.to_h; a benchmark script in the repository against stdlib CSV, and the README's speed sentence written from its output. The scanner-based parser on the branch scanner-parser is judged here, for the Regexp separator with a quoted field if for nothing else.
+
+## Features, after
+
+6. Guessing, as a mode that runs once at construction on a sample of the first rows and feeds the same chooser as an explicit option, scanner only: the column separator, the one whose count is the same on every sampled row; whether the first row is a header, its columns' types differing from the rows beneath in the same way across columns; and, where there is no header, a header made from the data, each column named for what its values look like, integer, decimal, date, email, URL, phone, with a positional fallback, column_0, for text and a suffix where two columns share a class. Names come from what values look like, not what they mean; anything more is a schema, and another library's.
+7. Templated ingestion: a template: option taking a whole-row Regexp with a capture per field, the group names being the column names, one match per row; an Array of separators as its writable special case, compiled into such a Regexp at construction and invertible for writing where a general template is not.
+8. The duplicate-header modes as an option: keep all as an Array, the default; index, a, a.1; first; last; error. All derivations of the same columns map at header time, none costing anything per row.
+9. Writing options: minimal quoting, a field quoted only where it holds a separator, a quote or a row terminator; a row terminator inside a field kept, quoted, or folded to a space; the encoding declared and a transcode offered with any loss marked.
+10. Symbols and Strings interchangeable for column names, in a selection, a columns: list and a row's keys; today a String is required.
+11. A strict: option, off by default, that raises on a row with more or fewer fields than the header; today a short row gets only the columns it has and a long row's excess lands under nil.
+12. A line number in each parse error, UnterminatedQuote first, found only when the error is raised, from the source's position at that moment; never counted as it goes, since counting costs time on every row for the sake of the rare one.
+13. Chunked processing of a large file: a bounded number of rows at a time handed to a block, so that nothing needs the whole file in memory and a partial result can be acted on before the rest is read.
+14. Checks, all of them after the above: strict: (13), column types, and whatever else proves wanted; correct and published comes first.

data/dsv.gemspec

@@ -0,0 +1,43 @@
+# dsv.gemspec
+
+require_relative './lib/DSV/VERSION'
+
+class Gem::Specification
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'dsv'
+  spec.version = DSV::VERSION
+
+  spec.summary = "Read and write delimiter-separated values."
+  spec.description = "Read and write the DSV family of files (CSV, TSV, etc.) from disk or in memory."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = "https://github.com/thoran/dsv"
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 3.2'
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    'dsv.gemspec',
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb'],
+    'CHANGELOG',
+    'Gemfile',
+    'LICENSE',
+    'Rakefile',
+    'README.md',
+    'TODO',
+  ].flatten
+
+  spec.development_dependencies = [
+    ['minitest', '~> 6.0'],
+    'minitest-mock',
+    'rake',
+  ]
+end

data/lib/DSV/File.rb

@@ -0,0 +1,35 @@
+# DSV/File.rb
+# DSV::File
+
+require_relative '../dsv'
+
+class DSV
+  class File < DSV
+
+    def initialize(filename, *args)
+      @filename = ::File.expand_path(filename)
+      @args = args
+      super(source, *args)
+    end
+
+    def source
+      @source ||= ::File.new(filename, mode, permissions)
+    end
+
+    def mode
+      @mode ||= DSV.normalised_mode(options[:mode])
+    end
+
+    # The trailing Hash of the arguments, left in place for the parent to take.
+    def options
+      @args.last.is_a?(::Hash) ? @args.last : {}
+    end
+
+    def permissions
+      @permissions ||= options[:permissions]
+    end
+
+    attr_reader :filename
+
+  end
+end

data/lib/DSV/String.rb

@@ -0,0 +1,19 @@
+# DSV/String.rb
+# DSV::String
+
+require_relative '../dsv'
+
+class DSV
+  class String < DSV
+
+    def initialize(string, *args)
+      @string = string
+      super(source, *args)
+    end
+
+    def source
+      @source ||= StringIO.new(@string)
+    end
+
+  end
+end

data/lib/DSV/VERSION.rb

@@ -0,0 +1,6 @@
+# DSV/VERSION.rb
+# DSV::VERSION
+
+class DSV
+  VERSION = '0.12.4'
+end