vnfmarket/src/main/webapp/vnfmarket/node_modules/utile/README.md

   1 # utile [![Build Status](https://secure.travis-ci.org/flatiron/utile.png)](http://travis-ci.org/flatiron/utile)
   2
   3 A drop-in replacement for `util` with some additional advantageous functions
   4
   5 ## Motivation
   6 Javascript is definitely a "batteries not included language" when compared to languages like Ruby or Python. Node.js has a simple utility library which exposes some basic (but important) functionality:
   7
   8 ```
   9 $ node
  10 > var util = require('util');
  11 > util.
  12 (...)
  13
  14 util.debug                 util.error                 util.exec                  util.inherits              util.inspect
  15 util.log                   util.p                     util.print                 util.pump                  util.puts
  16 ```
  17
  18 When one considers their own utility library, why ever bother requiring `util` again? That is the approach taken by this module. To compare:
  19
  20 ```
  21 $ node
  22 > var utile = require('./lib')
  23 > utile.
  24 (...)
  25
  26 utile.async                 utile.capitalize            utile.clone                 utile.cpr                   utile.createPath            utile.debug
  27 utile.each                  utile.error                 utile.exec                  utile.file                  utile.filter                utile.find
  28 utile.inherits              utile.log                   utile.mixin                 utile.mkdirp                utile.p                     utile.path
  29 utile.print                 utile.pump                  utile.puts                  utile.randomString          utile.requireDir            uile.requireDirLazy
  30 utile.rimraf
  31 ```
  32
  33 As you can see all of the original methods from `util` are there, but there are several new methods specific to `utile`. A note about implementation: _no node.js native modules are modified by utile, it simply copies those methods._
  34
  35 ## Methods
  36 The `utile` modules exposes some simple utility methods:
  37
  38 * `.each(obj, iterator)`: Iterate over the keys of an object.
  39 * `.mixin(target [source0, source1, ...])`: Copies enumerable properties from `source0 ... sourceN` onto `target` and returns the resulting object.
  40 * `.clone(obj)`: Shallow clones the specified object.
  41 * `.capitalize(str)`: Capitalizes the specified `str`.
  42 * `.randomString(length)`: randomString returns a pseudo-random ASCII string (subset) the return value is a string of length ⌈bits/6⌉ of characters from the base64 alphabet.
  43 * `.filter(obj, test)`: return an object with the properties that `test` returns true on.
  44 * `.args(arguments)`: Converts function arguments into actual array with special `callback`, `cb`, `array`, and `last` properties. Also supports *optional* argument contracts. See [the example](https://github.com/flatiron/utile/blob/master/examples/utile-args.js) for more details.
  45 * `.requireDir(directory)`: Requires all files and directories from `directory`, returning an object with keys being filenames (without trailing `.js`) and respective values being return values of `require(filename)`.
  46 * `.requireDirLazy(directory)`: Lazily requires all files and directories from `directory`, returning an object with keys being filenames (without trailing `.js`) and respective values (getters) being return values of `require(filename)`.
  47 * `.format([string] text, [array] formats, [array] replacements)`: Replace `formats` in `text` with `replacements`. This will fall back to the original `util.format` command if it is called improperly.
  48
  49 ## Packaged Dependencies
  50 In addition to the methods that are built-in, utile includes a number of commonly used dependencies to reduce the number of includes in your package.json. These modules _are not eagerly loaded to be respectful of startup time,_ but instead are lazy-loaded getters on the `utile` object
  51
  52 * `.async`: [Async utilities for node and the browser][0]
  53 * `.inflect`: [Customizable inflections for node.js][6]
  54 * `.mkdirp`: [Recursively mkdir, like mkdir -p, but in node.js][1]
  55 * `.rimraf`: [A rm -rf util for nodejs][2]
  56 * `.cpr`: [Asynchronous recursive file copying with Node.js][3]
  57
  58 ## Installation
  59
  60 ### Installing npm (node package manager)
  61 ```
  62   curl http://npmjs.org/install.sh | sh
  63 ```
  64
  65 ### Installing utile
  66 ```
  67   [sudo] npm install utile
  68 ```
  69
  70 ## Tests
  71 All tests are written with [vows][4] and should be run with [npm][5]:
  72
  73 ``` bash
  74   $ npm test
  75 ```
  76
  77 #### Author: [Nodejitsu Inc.](http://www.nodejitsu.com)
  78 #### Contributors: [Charlie Robbins](http://github.com/indexzero), [Dominic Tarr](http://github.com/dominictarr)
  79 #### License: MIT
  80
  81 [0]: https://github.com/caolan/async
  82 [1]: https://github.com/substack/node-mkdirp
  83 [2]: https://github.com/isaacs/rimraf
  84 [3]: https://github.com/avianflu/ncp
  85 [4]: https://vowsjs.org
  86 [5]: https://npmjs.org
  87 [6]: https://github.com/pksunkara/inflect