more tests; update changelog; rename fns

CHANGELOG.md

@@ -1,7 +1,7 @@
 Changelog
 =========
 
-# 1.2.0
+# 2.0.0
 
 > Not yet on npm
 
@@ -14,6 +14,13 @@ Changelog
   * [be5119509369aad3f1d3060ab176459be9edad06](https://github.com/mhkeller/indian-ocean/commit/be5119509369aad3f1d3060ab176459be9edad06)
 * Forthcoming: allow for parser options
   * See the `parse-options` branch for now
+* Expose parsers and formatters
+* *Breaking changes*
+  * Custom delimiters passed to `helpers.discernParser` no longer need to be in an object.
+    * Old usage `io.discernParser(null, {delimiter: '_'})`
+    * New usage `io.discernParser(null, '_')`
+  * Renamed functions
+    * `extensionMatches` -> `extMatchesStr`
 
 # 1.1.1
 

lib/index.js

@@ -128,21 +128,21 @@ helpers.discernFormat = function (fileName) {
 }
 
 /**
- * Given a `fileName`, optionally a delimiter, return a parser that can read that file as json. Parses as text if format not supported. Used internally by `.readData` and `.readDataSync`.
+ * Given a `fileName` return a parser that can read that file as json. Parses as text if format not supported by a built-in parser. If given a delimter string as the second argument, return a parser for that delimiter regardless of `fileName`. Used internally by `.readData` and `.readDataSync`.
  * @param {String} fileName the name of the file
- * @param {Object} options optionally can take a delimiter value
+ * @param {String} delimiter Alternative usage is to pass a delimiter string. Delegates to `dsv.dsvFormat`.
  * @returns {Object} a parser that can read the file
  *
  * @example
- * var parser = io.discernParser('path/to/data.csv');
- * var json = parser('path/to/data.csv');
+ * var parser = io.discernParser('path/to/data.csv')
+ * var json = parser('path/to/data.csv')
 
- * var parser = io.discernParser('path/to/data.usv', {delimiter: '_'});
- * var json = parser('path/to/data.usv');
+ * var parser = io.discernParser(null, '_')
+ * var json = parser('path/to/data.usv')
  */
-helpers.discernParser = function (fileName, opts_) {
-  if (opts_ && opts_.delimiter) {
-    return dsv.dsvFormat(opts_.delimiter).parse
+helpers.discernParser = function (fileName, delimiter) {
+  if (delimiter) {
+    return dsv.dsvFormat(delimiter).parse
   }
   var format = helpers.discernFormat(fileName)
   var parser = parsers[format]
@@ -153,14 +153,26 @@ helpers.discernParser = function (fileName, opts_) {
   return parser
 }
 
+// Our `readData` fns can take either a delimiter to parse a file, or a full blown parser
+// Determine what they passed in with this handy function
+function getParser (delimiterOrParser) {
+  var parser
+  if (typeof delimiterOrParser === 'string') {
+    parser = helpers.discernParser(null, delimiterOrParser)
+  } else if (_.isObject(delimiterOrParser) || _.isFunction(delimiterOrParser)) {
+    parser = delimiterOrParser
+  }
+  return parser
+}
+
 /**
  * Returns a formatter that will format json data to file type specified by the extension in `fileName`. Used internally by `.writeData` and `.writeDataSync`.
  * @param {String} fileName the name of the file
  * @returns {Object} a formatter that can write the file
  *
  * @example
- * var formatter = io.discernFileFormatter('path/to/data.tsv');
- * var csv = formatter(json);
+ * var formatter = io.discernFileFormatter('path/to/data.tsv')
+ * var csv = formatter(json)
  */
 helpers.discernFileFormatter = function (fileName) {
   var format = helpers.discernFormat(fileName)
@@ -254,47 +266,54 @@ helpers.makeDirectoriesSync = function (outPath) {
  * @returns {Boolean} whether The extension matched or not.
  *
  * @example
- * var matches = io.extensionMatches('path/to/data.tsv', 'tsv')
+ * var matches = io.extMatchesStr('path/to/data.tsv', 'tsv')
  * console.log(matches) // `true`
  */
-helpers.extensionMatches = function (fileName, extension) {
+helpers.extMatchesStr = function (filePath, extension) {
   // Chop '.' off extension returned by extname
-  return path.extname(fileName).slice(1) === extension
+  var ext = path.extname(filePath).slice(1)
+  return ext === extension
 }
 
 /**
- * Test whether a string matches a given Regular Expression
+ * Test whether a string matches a given Regular Expression.
  *
- * @param {String} fileName The name of the file
- * @param {RegExp} RegEx The RegEx to match with
- * @returns {Boolean} whether The string matches the RegEx
+ * @param {String} fileName The name of the file or file path.
+ * @param {RegExp} RegEx The RegEx to match with.
+ * @returns {Boolean} whether The string matches the RegEx.
  *
  * @example
- * var matches = io.matchRegExp('.gitignore', /\.gitignore/)
+ * var matches = io.matchesRegExp('.gitignore', /\.gitignore/)
+ * console.log(matches) // `true`
+ * 
+ * var matches = io.matchesRegExp('data/final-data/basic.csv', /\/final-data\//)
  * console.log(matches) // `true`
  */
-helpers.matchRegExp = function (fileName, regEx) {
-  return regEx.test(fileName)
+helpers.matchesRegExp = function (str, regEx) {
+  return regEx.test(str)
 }
 
 /**
- * Test whether a file name matches a given matcher. Delegates to {@link helpers#extensionMatches} if `matcher` is a string`, {@link helpers#matchRegExp} if Regular Expression
+ * Test whether a file name or path matches a given matcher. Delegates to {@link helpers#extMatches} if `matcher` is a string` and tests only against the file name extension. Delegates to {@link helpers#extMatchRegEx} if matcher is a Regular Expression and tests against entire string, which is usefulf or testing the full file path.
  *
- * @param {String} fileName The name of the file
- * @returns {String} matcher The string to match with
+ * @param {String} fileName The name of the file or path to the file.
+ * @returns {String} matcher The string to match with.
  *
  * @example
  * var matches = io.matches('path/to/data.tsv', 'tsv')
  * console.log(matches) // `true`
  *
  * var matches = io.matches('.gitignore', /\.gitignore/)
  * console.log(matches) // `true`
+ *
+ * var matches = io.matches('file/with/no-extention', '') // Nb. Dot files are treated as files with no extention
+ * console.log(matches) // `true`
  */
 helpers.matches = function (fileName, matcher) {
   if (typeof matcher === 'string') {
-    return helpers.extensionMatches(fileName, matcher)
+    return helpers.extMatchesStr(fileName, matcher)
   } else if (_.isRegExp(matcher)) {
-    return helpers.matchRegExp(fileName, matcher)
+    return helpers.matchesRegExp(fileName, matcher)
   } else {
     throw new Error('Matcher argument must be String or Regular Expression')
   }
@@ -465,20 +484,6 @@ function formattingPreflight (file, format) {
   return file
 }
 
-// Our `readData` fns can take either a delimiter to parse a file, or a full blown parser
-// Determine what they passed in with this handy function
-function getDelimiterOrParser (delimiterOrParser) {
-  var delimiter
-  var parser
-  if (typeof delimiterOrParser === 'string') {
-    delimiter = delimiterOrParser
-    parser = helpers.discernParser(null, delimiter)
-  } else if (_.isObject(delimiterOrParser)) {
-    parser = delimiterOrParser
-  }
-  return parser
-}
-
 /**
   * Functions to read data files.
   * @namespace
@@ -503,7 +508,7 @@ var readers = {}
  *
  * @param {String} fileName the name of the file
  * @param {Object} [options] Optional, see options below
- * @param {String|Function|Object} [options.parser] optional This can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method. Pre-version 1.1 this was called `parseWith` and to maintain support, that will still work.
+ * @param {String|Function|Object} [options.parser] optional This can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read
  *
  * @example
@@ -531,12 +536,10 @@ var readers = {}
 readers.readData = function (path, opts_, cb_) {
   var cb = arguments[arguments.length - 1]
   var parser
-  var parseWith
   var readOptions = {}
   if (arguments.length === 3) {
-    parseWith = opts_.parseWith || opts_.parser
     readOptions = opts_.readOptions
-    parser = getDelimiterOrParser(parseWith)
+    parser = getParser(opts_.parser)
   } else {
     parser = helpers.discernParser(path)
   }
@@ -559,7 +562,7 @@ readers.readData = function (path, opts_, cb_) {
  *
  * @param {String} fileName the name of the file
  * @param {Object} [options] Optional, see options below
- * @param {String|Function|Object} [options.parser] Optional, this can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method. Pre-version 1.1 this was called `parseWith` and to maintain support, that will still work.
+ * @param {String|Function|Object} [options.parser] Optional, this can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method.
  * @returns {Object} the contents of the file as JSON
  *
  * @example
@@ -582,12 +585,10 @@ readers.readData = function (path, opts_, cb_) {
  */
 readers.readDataSync = function (path, opts_) {
   var parser
-  var parseWith
   var readOptions
   if (arguments.length === 2) {
-    parseWith = opts_.parseWith || opts_.parser
     readOptions = opts_.readOptions
-    parser = getDelimiterOrParser(parseWith)
+    parser = getParser(opts_.parser)
   } else {
     parser = helpers.discernParser(path)
   }

package.json

@@ -7,7 +7,7 @@
     "coverage": "istanbul cover mocha -- -R spec",
     "docs": "documentation -g -f html -o docs -t ./docs/theme/",
     "preview-docs": "http-server -p 8080",
-    "test": "standard && mocha",
+    "test": "mocha",
     "standard-fix": "standard --fix"
   },
   "repository": {

test/data/other/basic.usv

@@ -0,0 +1,3 @@
+name_occupation_height
+jim_land surveyor_70
+francis_conductor_63