incsv 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f1fc0abb9bb7e012da9f2be37f4fa79b1b45f371
-  data.tar.gz: 7bde51d01a7db2e16f9805b45dc4391703b64792
+  metadata.gz: a48352c382c9de59e29eb0f294f75f68cc7f8de0
+  data.tar.gz: 749abf80150e9181ef61c0d85746ed685459a754
 SHA512:
-  metadata.gz: 1b23fe97b8a38cc505ddf64c795798941a21b347d882b8976c3f68e1ff768fb1b8e1acfd600172c617af78d8563a2b2877f641308f3357ac8764fde95329f1b2
-  data.tar.gz: 6dd334b65735ba34da45ac131de1bf8220081f2292521a37be4c488a017de4db697d9d2b56dc0d220a0dedba4c70ed1ebc82bd3168e28eb8457d0947c4381d96
+  metadata.gz: e9b77efaf5628776671a0c113f8082335702f33ececab4e62c9f21cd1013d65bbc12f2be5b7e8f769cad9257ec2d5387ea6655b561a1803cc142613bc44e762f
+  data.tar.gz: 909a26477f6065c4a7ff04bc54f38e74c9a6fff4d32e94d73bb15b38f841ace0f120ac483b7b3e89daa9008272a117d64a9c72c4d3452694f455e865c3830aea

data/.yardopts

@@ -0,0 +1,6 @@
+--protected
+--no-private
+--exclude /spec/
+--exclude /bin/
+-
+README.md

data/README.md

@@ -7,8 +7,8 @@ It works by loading the CSV into an [SQLite][] database and then
 dropping you into an interactive Ruby shell. You can then use the
 [Sequel][] database library to perform further exploratory analysis.
 
-[sqlite]: https://www.sqlite.org/
-[sequel]: http://sequel.jeremyevans.net/
+[SQLite]: https://www.sqlite.org/
+[Sequel]: http://sequel.jeremyevans.net/
 
 ## Installation
 
@@ -38,7 +38,7 @@ A quick example:
 	  {:name=>"enhanced targeting card"},
 	  {:name=>"Giddyup Buttercup"}]
 
-[repl]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop
+[REPL]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop
 
 ### The less-quick version
 

data/exe/incsv

@@ -8,6 +8,9 @@ require "pry"
 require "incsv"
 
 module InCSV
+  # A cut-down class, the binding of which is used for the REPL console.
+  # Any methods and instance variables defined here, therefore, are
+  # accessible from the console.
   class Console
     def initialize(db)
       @db = db
@@ -18,6 +21,7 @@ module InCSV
     end
   end
 
+  # The command-line interface to InCSV.
   class CLI < Thor
     desc "create CSV_FILE", "Creates a database file with the appropriate schema for the given CSV file, but doesn't import any data."
     method_option :force, type: :boolean, default: false

data/incsv.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.8"
 
   spec.add_runtime_dependency "thor", "~> 0.19.1"
   spec.add_runtime_dependency "pry", "~> 0.10"

data/lib/incsv/column_type.rb

@@ -1,9 +1,28 @@
 module InCSV
+  # An abstract class, inherited by all types of column. Specifies the
+  # interface that all these classes must adhere to.
   class ColumnType
+    # A symbol representation of what type of data this ColumnType
+    # represents. By default this is taken from the class name (so this
+    # class would be :columntype).
     def self.name
       self.to_s.sub(/.*::/, "").downcase.to_sym
     end
 
+    # The type of the column from the perspective of the database. By
+    # default this is the same as the class name, so a column of type
+    # String would go into the database as a :string.
+    #
+    # Possible column types can be found here:
+    #
+    # http://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html#label-Column+types
+    #
+    # This can also be a string, for database-specific features or in
+    # order to specify lengths easily. Examples might be:
+    #
+    # VARCHAR(255)
+    # DECIMAL(10, 2)
+    # BOOLEAN
     def self.for_database
       self.to_s.sub(/.*::/, "").downcase.to_sym
     end
@@ -12,14 +31,19 @@ module InCSV
       @value = value
     end
 
+    # Returns true if the given value (supplied in the constructor)
+    # is of the type represented by this column; returns false
+    # otherwise.
     def match?
       false
     end
 
+    # Returns a cleaned/preprocessed version of the given value.
     def clean_value
       self.class.clean_value(@value)
     end
 
+    # Returns a cleaned/preprocessed version of an arbitrary value.
     def self.clean_value(value)
       value
     end

data/lib/incsv/database.rb

@@ -3,6 +3,9 @@ require "sequel"
 require "pathname"
 
 module InCSV
+  # Represents a database file, handling the creation of the database
+  # and of the table within the database, as well as the importing of
+  # data from a CSV file into the database.
   class Database
     def initialize(csv)
       @csv = csv
@@ -14,29 +17,47 @@ module InCSV
 
     attr_reader :db
 
+    # Returns true if the primary database table within the database has
+    # been created.
     def table_created?
       @db.table_exists?(table_name)
     end
 
+    # Returns true if there is data in the primary table. There are
+    # perhaps more accurate ways to calculate this, but only by
+    # comparing samples from the CSV to the table; this is faster and
+    # will in practice be accurate.
     def imported?
        table_created? && @db[table_name].count > 0
     end
 
+    # Returns true if the database file exists; makes no effort to check
+    # whether it is in fact a valid SQLite database.
     def exists?
       File.exist?(db_path)
     end
 
+    # Returns the path to the database file, generated based on the
+    # filename of the CSV passed to the class. For example, a CSV called
+    # `products.csv` will be stored in a database called `products.db`
+    # in the same directory.
     def db_path
       path = Pathname(csv)
       (path.dirname + (path.basename(".csv").to_s + ".db")).to_s
     end
 
+    # Returns the table name, by default generated based on the filename
+    # of the CSV. For example, a CSV called `products.csv` will produce
+    # a table called `products`.
     def table_name
       @table_name ||= begin
         File.basename(csv, ".csv").downcase.gsub(/[^a-z_]/, "").to_sym
       end
     end
 
+    # Creates a table in the database, with one column in the database
+    # for each column in the CSV, the type of which is the best guess
+    # for the data found in that column in the CSV data.
     def create_table
       @db.create_table!(table_name) do
         primary_key :_incsv_id
@@ -49,6 +70,11 @@ module InCSV
       end
     end
 
+    # Imports data from the CSV file into the database, applying any
+    # preprocessing specified by the column type (e.g. stripping
+    # currency prefixes).
+    #
+    # Data is imported in transactions, in chunks of 200 rows at a time.
     def import
       return if imported?
 

data/lib/incsv/schema.rb

@@ -1,11 +1,15 @@
 require "csv"
 
 module InCSV
+  # Given a CSV file, samples data from it in order to establish what
+  # data types its columns are.
   class Schema
     def initialize(csv)
       @csv = csv
     end
 
+    # Returns the column types found in the CSV. Memoises the result, so
+    # can be called repeatedly.
     def columns
       @columns ||= parsed_columns
     end
@@ -14,6 +18,10 @@ module InCSV
 
     attr_reader :csv
 
+    # Returns an array with one element for each column in the CSV. The
+    # value is a Column object, which has responsibility for determining
+    # the type of the data stored in the column; a sample of 50 rows
+    # from the column is provided to the Column class for this purpose.
     def parsed_columns
       samples(50).map do |name, values|
         Column.new(name, values)

data/lib/incsv/types/currency.rb

@@ -1,16 +1,30 @@
 module InCSV
   module Types
+    # Represents a currency value, without its symbol/identifier, stored
+    # as a DECIMAL(10, 2) to avoid rounding errors.
+    #
+    # Not storing the identifier is an issue that should be resolved at
+    # some point, ideally; it's obviously an issue in files that have
+    # multiple currencies in the same column.
     class Currency < ColumnType
+      # A regular expression which matches all supported currency types.
       MATCH_EXPRESSION = /\A(\$|£)([0-9,\.]+)\z/
 
+      # What type of column to create in the database.
       def self.for_database
         "DECIMAL(10,2)"
       end
 
+      # Returns true if the given value is a supported currency type, or
+      # false otherwise.
       def match?
         value.strip.match(MATCH_EXPRESSION)
       end
 
+      # Strip the currency symbol, and remove any comma separators. This
+      # creates an issue with locales other than English, in which
+      # commas are used for decimal points, but this will work for
+      # English.
       def self.clean_value(value)
         return unless value
 

data/lib/incsv/types/date.rb

@@ -1,5 +1,7 @@
 module InCSV
   module Types
+    # Represents an ISO 8601-format date without any timestamp element,
+    # e.g. 2016-01-01.
     class Date < ColumnType
       def match?
         value.strip.match(/\A[0-9]{4}-[0-9]{2}-[0-9]{2}\z/)

data/lib/incsv/types/string.rb

@@ -1,6 +1,15 @@
 module InCSV
   module Types
+    # Represents a String, stored in the database as a VARCHAR(255).
+    # This is the fallback datatype, used for anything that doesn't
+    # match any of the other more specific types. Its matching logic is
+    # therefore simple: it matches anything. For this reason it must be
+    # matched last; this is achieved via require order.
     class String < ColumnType
+      def self.for_database
+        "TEXT"
+      end
+
       def match?
         true
       end

data/lib/incsv/version.rb

@@ -1,3 +1,3 @@
 module InCSV
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: incsv
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Rob Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-22 00:00:00.000000000 Z
+date: 2016-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +134,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -164,3 +179,4 @@ signing_key:
 specification_version: 4
 summary: A tool for interrogating CSV data using SQLite and Sequel.
 test_files: []
+has_rdoc: