├── .gitattributes
├── .gitignore
├── .npmrc
├── bin
    └── download.js
├── completions
    └── readme.fish
├── index.js
├── package.json
└── readme.markdown


/.gitattributes:
--------------------------------------------------------------------------------
1 | bin -text
2 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | core
3 | 


--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
1 | save-prefix = ~
2 | 


--------------------------------------------------------------------------------
/bin/download.js:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env node
 2 | 
 3 | var coredocs = require('node-api-docs')
 4 | var jsonstream = require('jsonstream')
 5 | var through = require('through2')
 6 | var mkdirp = require('mkdirp')
 7 | var fs = require('fs')
 8 | var path = require('path')
 9 | 
10 | var coredir = path.join(__dirname, '../core')
11 | mkdirp.sync(coredir)
12 | 
13 | console.log('Downloading core docs for offline use...')
14 | 
15 | coredocs.json('index')
16 |   .pipe(jsonstream.parse(['desc',true,'text']))
17 |   .pipe(through.obj(function (text, enc, next) {
18 |     var m = /^\[[^\]]+\]\((\S+)\.html\)$/.exec(text)
19 |     if (!m) return next()
20 |     if (m[1] === 'documentation' || m[1] === 'synopsis') return next()
21 |     var file = m[1] + '.md'
22 |     coredocs.markdown(m[1]).pipe(fs.createWriteStream(path.join(coredir, file)))
23 |     next()
24 |   }))
25 | 
26 | // Don't abort install if this fails.
27 | process.on('uncaughtException', function (err) {
28 |   console.error(err.toString())
29 | })
30 | 


--------------------------------------------------------------------------------
/completions/readme.fish:
--------------------------------------------------------------------------------
 1 | # Fish completions for dominictarr/readme (npm install readme -g).
 2 | #
 3 | # Install: put this file to a directory listed in $fish_complete_path.
 4 | #
 5 | 
 6 | complete -c readme -xa "(ls -1 node_modules ^/dev/null)"
 7 | complete -c readme -l help -d "Show help"
 8 | complete -c readme -l version -d "Print version"
 9 | complete -c readme -l global -d "Show readme for a globally installed module"
10 | complete -c readme -l core -d "Show readme for a core module"
11 | complete -c readme -l web -d "Open project's homepage"
12 | complete -c readme -l github -d "Open project's GitHub page"
13 | complete -c readme -l color -d "Turn on colors"
14 | complete -c readme -l no-color -d "Turn off colors"
15 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
  1 | #! /usr/bin/env node
  2 | // -*- js2-strict-missing-semi-warning: nil; -*-
  3 | 
  4 | var concat             = require('concat-stream')
  5 | var duplexer           = require('duplexer2')
  6 | var findRoot           = require('find-root')
  7 | var fs                 = require('fs')
  8 | var help               = require('help-version')(usage()).help
  9 | var marked             = require('marked')
 10 | var markedTerminal     = require('marked-terminal')
 11 | var minimist           = require('minimist')
 12 | var npmPrefix          = require('npm-prefix')
 13 | var opener             = require('opener')
 14 | var resolve            = require('resolve')
 15 | var toUrl              = require('github-url').toUrl
 16 | var pager              = require('default-pager')
 17 | var pagerSupportsColor = require('pager-supports-color')
 18 | var path               = require('path')
 19 | var through            = require('through2')
 20 | var readmeFilenames    = require('readme-filenames')
 21 | var iscore             = require('is-core-module')
 22 | var coredocs           = require('node-api-docs')
 23 | var fallbackStream     = require('fallback-stream')
 24 | var spawnSync          = require('child_process').spawnSync
 25 | 
 26 | 
 27 | function usage() {
 28 |   return [
 29 |     'Usage:  readme [<option>] [<name>]',
 30 |     '',
 31 |     'With no <name>, display current module\'s readme.',
 32 |     '',
 33 |     'Options:',
 34 |     '  --global, -g    Show readme for a globally installed module.',
 35 |     '  --core, -c      Show readme for a core module.',
 36 |     '  --web           Open project\'s homepage.',
 37 |     '  --github, --gh  Open project\'s GitHub page.',
 38 |     '  --[no-]color    Turn on/off colors.'
 39 |   ].join('\n')
 40 | }
 41 | 
 42 | 
 43 | var basedir = function (opts) {
 44 |   if (!opts.global) {
 45 |     return process.cwd()
 46 |   }
 47 |   return path.join(npmPrefix(), 'lib')
 48 | }
 49 | 
 50 | var coredir = path.join(__dirname, 'core')
 51 | 
 52 | var packageFile = function (name, opts) {
 53 |   return resolve.sync(path.join(name, 'package.json'),
 54 |                       { basedir: basedir(opts) })
 55 | }
 56 | 
 57 | 
 58 | var currentPackageFile = function (opts) {
 59 |   return path.join(findRoot(basedir(opts)), 'package.json')
 60 | }
 61 | 
 62 | 
 63 | var packageReadme = function (pkgDir) {
 64 |   var readmes = fs.readdirSync(pkgDir).filter(function (filename) {
 65 |     return readmeFilenames.indexOf(filename) >= 0
 66 |   })
 67 |   if (!readmes.length) {
 68 |     throw new Error('Readme not found in ' + pkgDir)
 69 |   }
 70 |   return fs.createReadStream(path.join(pkgDir, readmes[0]))
 71 | }
 72 | 
 73 | 
 74 | var packageUrl = function (pkg, webUrl) {
 75 |   var repoUrl = toUrl(pkg.repository)
 76 |   return webUrl
 77 |     ? pkg.homepage || repoUrl || 'https://npm.im/' + pkg.name
 78 |     : repoUrl
 79 | }
 80 | 
 81 | 
 82 | var coreReadme = function (name) {
 83 |   return fallbackStream([
 84 |     fs.createReadStream(path.join(coredir, name + '.md')),
 85 |     coredocs.markdown(name)
 86 |   ])
 87 | }
 88 | 
 89 | 
 90 | var colorize = function () {
 91 |   marked.setOptions({
 92 |     renderer: new markedTerminal()
 93 |   })
 94 | 
 95 |   var input = through(), output = through()
 96 | 
 97 |   input.pipe(concat({ encoding: 'string' }, function (md) {
 98 |     output.end(marked(md))
 99 |   }))
100 | 
101 |   return duplexer(input, output)
102 | }
103 | 
104 | 
105 | try {
106 |   var opts = minimist(process.argv.slice(2), {
107 |     boolean: ['global', 'core', 'web', 'github', 'color'],
108 |     alias: {
109 |       global: 'g',
110 |       core: 'c',
111 |       github: 'gh'
112 |     },
113 |     default: {
114 |       color: pagerSupportsColor()
115 |     }
116 |   })
117 | 
118 |   if (opts._.length > 1) {
119 |     help(1)
120 |   }
121 | 
122 |   var name = String(opts._.shift() || '')
123 |   var readme
124 | 
125 |   if (opts.core) {
126 |     readme = coreReadme(name)
127 |   } else if (opts.github || opts.web) {
128 |     var pkg = require(packageFile(name, opts))
129 |     opener(packageUrl(pkg, opts.web))
130 |   } else if (name) {
131 |     var pkgFile
132 |     try {
133 |       pkgFile = packageFile(name, opts)
134 |     } catch (e) {
135 |       var error = e
136 |       opts.global = true
137 |       try {
138 |         pkgFile = packageFile(name, opts)
139 |       } catch (e) {
140 |         if (iscore(name)) {
141 |           readme = coreReadme(name)
142 |         } else {
143 |           var res = spawnSync('npm', ['info', name, 'readme'])
144 |           if (res.status !== 0) throw new Error('Could not find module "' + name + '"')
145 |           readme = through()
146 |           readme.end(res.stdout)
147 |         }
148 |       }
149 |     }
150 |     if (!readme) readme = packageReadme(path.dirname(pkgFile))
151 |   } else {
152 |     try {
153 |       readme = packageReadme(path.dirname(currentPackageFile(opts)))
154 |     } catch (e) {
155 |       readme = packageReadme(process.cwd())
156 |     }
157 |   }
158 | 
159 |   if (readme) {
160 |     if (opts.color) {
161 |       readme.pipe(colorize()).pipe(pager())
162 |     }
163 |     else {
164 |       readme.pipe(pager())
165 |     }
166 |   }
167 | } catch (e) {
168 |   console.error(e.message)
169 |   process.exit(1)
170 | }
171 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "readme",
 3 |   "version": "0.7.0",
 4 |   "description": "display a module's readme in the terminal",
 5 |   "main": "index.js",
 6 |   "dependencies": {
 7 |     "concat-stream": "~1.5.0",
 8 |     "default-pager": "~1.0.1",
 9 |     "duplexer2": "~0.1.4",
10 |     "fallback-stream": "~1.1.0",
11 |     "find-root": "~0.1.1",
12 |     "github-url": "~1.2.0",
13 |     "help-version": "~1.1.0",
14 |     "is-core-module": "~1.0.2",
15 |     "jsonstream": "~1.0.3",
16 |     "marked": "~0.3.3",
17 |     "marked-terminal": "~1.6.1",
18 |     "minimist": "~1.2.0",
19 |     "mkdirp": "~0.5.1",
20 |     "node-api-docs": "~0.3.0",
21 |     "npm-prefix": "~1.1.0",
22 |     "opener": "~1.4.1",
23 |     "pager-supports-color": "~0.1.0",
24 |     "readme-filenames": "~1.0.0",
25 |     "resolve": "~1.1.6",
26 |     "through2": "~2.0.0"
27 |   },
28 |   "scripts": {
29 |     "test": "echo \"Error: no test specified\" && exit 1",
30 |     "postinstall": "node bin/download.js"
31 |   },
32 |   "bin": {
33 |     "readme": "./index.js"
34 |   },
35 |   "files": [
36 |     "index.js",
37 |     "bin/"
38 |   ],
39 |   "repository": {
40 |     "type": "git",
41 |     "url": "git://github.com/dominictarr/readme.git"
42 |   },
43 |   "keywords": [
44 |     "man",
45 |     "npm",
46 |     "readme",
47 |     "pager",
48 |     "less"
49 |   ],
50 |   "author": "Dominic Tarr <dominic.tarr@gmail.com> (dominictarr.com)",
51 |   "license": "BSD-2-Clause"
52 | }
53 | 


--------------------------------------------------------------------------------
/readme.markdown:
--------------------------------------------------------------------------------
 1 | # readme
 2 | 
 3 | Retrieve a node module's readme from the command line, and pipe it into `less`.
 4 | 
 5 | ## Installation
 6 | 
 7 | ```
 8 | > npm install readme -g
 9 | ```
10 | 
11 | ## Usage
12 | 
13 | Show the readme for a node module.
14 | 
15 | readme resolves your module in the same way as `require()`
16 | 
17 | ```
18 | > readme          # for the current module.
19 | 
20 | > readme optimist # for a locally installed module
21 | 
22 | > readme readme -g # for a globally installed module.
23 | 
24 | > readme -c http   # for a core module
25 | 
26 | > readme readme --web # open the project's webpage
27 | 
28 | > readme readme --gh # open the projects github page
29 | ```
30 | 
31 | ## Shell completions
32 | 
33 | `readme` comes with completions for the Fish shell (completions for other shells welcome).
34 | 
35 | To install completions, put `completions/readme.fish` file to a directory listed in `$fish_complete_path`.
36 | 
37 | ```
38 | $ curl -L https://raw.github.com/dominictarr/readme/master/completions/readme.fish >~/.config/fish/completions/readme.fish
39 | ```
40 | 
41 | ## License
42 | 
43 | [BSD](http://opensource.org/licenses/BSD-2-Clause)
44 | 


--------------------------------------------------------------------------------