From 3c34cf955322689d2ad2f92279d486e46d784481 Mon Sep 17 00:00:00 2001 From: jonschlinkert Date: Sat, 19 Mar 2016 13:00:46 -0400 Subject: [PATCH] generate docs --- .verb.md | 87 ++++++++++++++++++++++++++++++++-- README.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 214 insertions(+), 11 deletions(-) diff --git a/.verb.md b/.verb.md index 4497624..9b25dd1 100644 --- a/.verb.md +++ b/.verb.md @@ -1,13 +1,13 @@ ## Usage ```js -var git = require('{%= name %}'); +var parse = require('{%= name %}'); // sync -var config = git.sync(); +var config = parse.sync(); // or async -git(function (err, config) { +parse(function (err, config) { // do stuff with err/config }); ``` @@ -15,10 +15,10 @@ git(function (err, config) { **Custom path and/or cwd** ```js -git.sync({cwd: 'foo', path: '.git/config'}); +parse.sync({cwd: 'foo', path: '.git/config'}); // async -git({cwd: 'foo', path: '.git/config'}, function (err, config) { +parse({cwd: 'foo', path: '.git/config'}, function (err, config) { // do stuff }); ``` @@ -40,3 +40,80 @@ Config object will be something like: fetch: '+refs/heads/*:refs/remotes/origin/*' }, 'branch "master"': { remote: 'origin', merge: 'refs/heads/master', ... } } ``` + +## API +{%= apidocs('index.js') %} + +### .keys examples + +Converts ini-style keys into objects: + +**Example 1** + +```js +var parse = require('parse-git-config'); +var config = { + 'foo "bar"': { doStuff: true }, + 'foo "baz"': { doStuff: true } +}; + +console.log(parse.keys(config)); +``` + +Results in: + +```js +{ + foo: { + bar: { doStuff: true }, + baz: { doStuff: true } + } +} +``` + +**Example 2** + +```js +var parse = require('parse-git-config'); +var config = { + 'remote "origin"': { + url: 'https://github.com/jonschlinkert/normalize-pkg.git', + fetch: '+refs/heads/*:refs/remotes/origin/*' + }, + 'branch "master"': { + remote: 'origin', + merge: 'refs/heads/master' + }, + 'branch "dev"': { + remote: 'origin', + merge: 'refs/heads/dev', + rebase: true + } +}; + +console.log(parse.keys(config)); +``` + +Results in: + +```js +{ + remote: { + origin: { + url: 'https://github.com/jonschlinkert/normalize-pkg.git', + fetch: '+refs/heads/*:refs/remotes/origin/*' + } + }, + branch: { + master: { + remote: 'origin', + merge: 'refs/heads/master' + }, + dev: { + remote: 'origin', + merge: 'refs/heads/dev', + rebase: true + } + } +} +``` diff --git a/README.md b/README.md index c2b0e53..6dcf8d8 100644 --- a/README.md +++ b/README.md @@ -13,13 +13,13 @@ $ npm install parse-git-config --save ## Usage ```js -var git = require('parse-git-config'); +var parse = require('parse-git-config'); // sync -var config = git.sync(); +var config = parse.sync(); // or async -git(function (err, config) { +parse(function (err, config) { // do stuff with err/config }); ``` @@ -27,10 +27,10 @@ git(function (err, config) { **Custom path and/or cwd** ```js -git.sync({cwd: 'foo', path: '.git/config'}); +parse.sync({cwd: 'foo', path: '.git/config'}); // async -git({cwd: 'foo', path: '.git/config'}, function (err, config) { +parse({cwd: 'foo', path: '.git/config'}, function (err, config) { // do stuff }); ``` @@ -53,6 +53,132 @@ Config object will be something like: 'branch "master"': { remote: 'origin', merge: 'refs/heads/master', ... } } ``` +## API + +### [parse](index.js#L30) + +Asynchronously parse a `.git/config` file. If only the callback is passed, the `.git/config` file relative to `process.cwd()` is used. + +**Params** + +* `options` **{Object|String|Function}**: Options with `cwd` or `path`, the cwd to use, or the callback function. +* `cb` **{Function}**: callback function if the first argument is options or cwd. +* `returns` **{Object}** + +**Example** + +```js +parse(function(err, config) { + if (err) throw err; + // do stuff with config +}); +``` + +### [.sync](index.js#L67) + +Synchronously parse a `.git/config` file. If no arguments are passed, the `.git/config` file relative to `process.cwd()` is used. + +**Params** + +* `options` **{Object|String}**: Options with `cwd` or `path`, or the cwd to use. +* `returns` **{Object}** + +**Example** + +```js +var config = parse.sync(); +``` + +### [.keys](index.js#L109) + +Returns an object with only the properties that had ini-style keys converted to objects (example below). + +**Params** + +* `config` **{Object}**: The parsed git config object. +* `returns` **{Object}** + +**Example** + +```js +var config = parse.sync(); +var obj = parse.keys(config); +``` + +### .keys examples + +Converts ini-style keys into objects: + +**Example 1** + +```js +var parse = require('parse-git-config'); +var config = { + 'foo "bar"': { doStuff: true }, + 'foo "baz"': { doStuff: true } +}; + +console.log(parse.keys(config)); +``` + +Results in: + +```js +{ + foo: { + bar: { doStuff: true }, + baz: { doStuff: true } + } +} +``` + +**Example 2** + +```js +var parse = require('parse-git-config'); +var config = { + 'remote "origin"': { + url: 'https://github.com/jonschlinkert/normalize-pkg.git', + fetch: '+refs/heads/*:refs/remotes/origin/*' + }, + 'branch "master"': { + remote: 'origin', + merge: 'refs/heads/master' + }, + 'branch "dev"': { + remote: 'origin', + merge: 'refs/heads/dev', + rebase: true + } +}; + +console.log(parse.keys(config)); +``` + +Results in: + +```js +{ + remote: { + origin: { + url: 'https://github.com/jonschlinkert/normalize-pkg.git', + fetch: '+refs/heads/*:refs/remotes/origin/*' + } + }, + branch: { + master: { + remote: 'origin', + merge: 'refs/heads/master' + }, + dev: { + remote: 'origin', + merge: 'refs/heads/dev', + rebase: true + } + } +} +``` + ## Related projects * [parse-author](https://www.npmjs.com/package/parse-author): Parse a string into an object with `name`, `email` and `url` properties following npm conventions.… [more](https://www.npmjs.com/package/parse-author) | [homepage](https://github.com/jonschlinkert/parse-author) @@ -100,4 +226,4 @@ Released under the [MIT license](https://github.com/jonschlinkert/parse-git-conf *** -_This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on February 26, 2016._ \ No newline at end of file +_This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on March 19, 2016._ \ No newline at end of file