public/bower_components/lodash/lib/fp/template/doc/wiki.jst

   1 ## lodash/fp
   2
   3 The `lodash/fp` module is an instance of `lodash` with its methods wrapped to
   4 produce immutable auto-curried iteratee-first data-last methods.
   5
   6 ## Installation
   7
   8 In a browser:
   9 ```html
  10 <script src='path/to/lodash.js'></script>
  11 <script src='path/to/lodash.fp.js'></script>
  12 ```
  13
  14 In Node.js:
  15 ```js
  16 // Load the fp build.
  17 var _ = require('lodash/fp');
  18
  19 // Load a method category.
  20 var object = require('lodash/fp/object');
  21
  22 // Load a single method for smaller builds with browserify/rollup/webpack.
  23 var extend = require('lodash/fp/extend');
  24 ```
  25
  26 ## Convert
  27
  28 Although `lodash/fp` & its method modules come pre-converted there are times when
  29 you may want to convert another lodash package or create a customized conversion.
  30 That’s when the `convert` module comes in handy.
  31
  32 ```js
  33 var convert = require('lodash/fp/convert');
  34
  35 // Convert by name.
  36 var assign = convert('assign', require('lodash.assign'));
  37
  38 // Convert by object.
  39 var fp = convert({
  40   'assign': require('lodash.assign'),
  41   'chunk': require('lodash.chunk')
  42 });
  43
  44 // Convert by `lodash` instance.
  45 var fp = convert(lodash.runInContext());
  46 ```
  47
  48 It’s even customizable.
  49 ```js
  50 // Every option is `true` by default.
  51 var filter = convert('filter', _.filter, {
  52   // Specify capping iteratee arguments.
  53   'cap': true,
  54   // Specify currying.
  55   'curry': true,
  56   // Specify fixed arity.
  57   'fixed': true,
  58   // Specify immutable operations.
  59   'immutable': true,
  60   // Specify rearranging arguments.
  61   'rearg': true
  62 });
  63
  64 // Specify `cap` of `false` to create a function that doesn’t cap iteratee arguments.
  65 var filter = convert('filter', _.filter, { 'cap': false });
  66
  67 filter(function(value, index) {
  68   return index % 2 == 0;
  69 })(['a', 'b', 'c']);
  70 // => ['a', 'c']
  71 ```
  72
  73 ## Mapping
  74
  75 Immutable auto-curried iteratee-first data-last methods sound great, but what’s
  76 that really mean for each method? Below is a breakdown of the mapping used to
  77 convert each method.
  78
  79 #### Capped Iteratee Arguments
  80
  81 Methods that cap iteratees to one argument:<br>
  82 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 1)))) %>
  83
  84 Methods that cap iteratees to two arguments:<br>
  85 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 2)))) %>
  86
  87 The iteratee of `mapKeys` is invoked with one argument: (key)
  88
  89 #### Fixed Arity
  90
  91 Methods with a fixed arity of one:<br>
  92 <%= toFuncList(mapping.aryMethod[1]) %>
  93
  94 Methods with a fixed arity of two:<br>
  95 <%= toFuncList(mapping.aryMethod[2]) %>
  96
  97 Methods with a fixed arity of three:<br>
  98 <%= toFuncList(mapping.aryMethod[3]) %>
  99
 100 Methods with a fixed arity of four:<br>
 101 <%= toFuncList(mapping.aryMethod[4]) %>
 102
 103 #### Rearranged Arguments
 104
 105 Methods with a fixed arity of two have an argument order of:<br>
 106 <%= toArgOrder(mapping.aryRearg[2]) %>
 107
 108 Methods with a fixed arity of three have an argument order of:<br>
 109 <%= toArgOrder(mapping.aryRearg[3]) %>
 110
 111 Methods with a fixed arity of four have an argument order of:<br>
 112 <%= toArgOrder(mapping.aryRearg[4]) %>
 113
 114 Methods with custom argument orders:<br>
 115 <%= _.map(mapping.methodRearg, function(orders, methodName) {
 116   return ' * `_.' + methodName + '` has an order of ' + toArgOrder(orders);
 117 }).join('\n') %>
 118
 119 Methods with unchanged argument orders:<br>
 120 <%= toFuncList(_.keys(mapping.skipRearg)) %>
 121
 122 The methods `partial` & `partialRight` accept an array of arguments to partially
 123 apply as their second parameter.
 124
 125 #### New Methods
 126
 127 Methods created to accommodate Lodash’s variadic methods:<br>
 128 <%= toFuncList(_.keys(mapping.remap)) %>
 129
 130 #### Aliases
 131
 132 There are <%= _.size(mapping.aliasToReal) %> method aliases:<br>
 133 <%= _.map(mapping.aliasToReal, function(realName, alias) {
 134   return ' * Added `_.' + alias + '` as an alias of `_.' + realName + '`';
 135 }).join('\n') %>