You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

149 lines
6.3 KiB

4 years ago
  1. # set-value [![NPM version](https://img.shields.io/npm/v/set-value.svg?style=flat)](https://www.npmjs.com/package/set-value) [![NPM monthly downloads](https://img.shields.io/npm/dm/set-value.svg?style=flat)](https://npmjs.org/package/set-value) [![NPM total downloads](https://img.shields.io/npm/dt/set-value.svg?style=flat)](https://npmjs.org/package/set-value) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/set-value.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/set-value)
  2. > Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.
  3. ## Install
  4. Install with [npm](https://www.npmjs.com/):
  5. ```sh
  6. $ npm install --save set-value
  7. ```
  8. ## Usage
  9. ```js
  10. var set = require('set-value');
  11. set(object, prop, value);
  12. ```
  13. ### Params
  14. * `object` **{object}**: The object to set `value` on
  15. * `prop` **{string}**: The property to set. Dot-notation may be used.
  16. * `value` **{any}**: The value to set on `object[prop]`
  17. ## Examples
  18. Updates and returns the given object:
  19. ```js
  20. var obj = {};
  21. set(obj, 'a.b.c', 'd');
  22. console.log(obj);
  23. //=> { a: { b: { c: 'd' } } }
  24. ```
  25. ### Escaping
  26. **Escaping with backslashes**
  27. Prevent set-value from splitting on a dot by prefixing it with backslashes:
  28. ```js
  29. console.log(set({}, 'a\\.b.c', 'd'));
  30. //=> { 'a.b': { c: 'd' } }
  31. console.log(set({}, 'a\\.b\\.c', 'd'));
  32. //=> { 'a.b.c': 'd' }
  33. ```
  34. **Escaping with double-quotes or single-quotes**
  35. Wrap double or single quotes around the string, or part of the string, that should not be split by set-value:
  36. ```js
  37. console.log(set({}, '"a.b".c', 'd'));
  38. //=> { 'a.b': { c: 'd' } }
  39. console.log(set({}, "'a.b'.c", "d"));
  40. //=> { 'a.b': { c: 'd' } }
  41. console.log(set({}, '"this/is/a/.file.path"', 'd'));
  42. //=> { 'this/is/a/file.path': 'd' }
  43. ```
  44. ### Bracket support
  45. set-value does not split inside brackets or braces:
  46. ```js
  47. console.log(set({}, '[a.b].c', 'd'));
  48. //=> { '[a.b]': { c: 'd' } }
  49. console.log(set({}, "(a.b).c", "d"));
  50. //=> { '(a.b)': { c: 'd' } }
  51. console.log(set({}, "<a.b>.c", "d"));
  52. //=> { '<a.b>': { c: 'd' } }
  53. console.log(set({}, "{a..b}.c", "d"));
  54. //=> { '{a..b}': { c: 'd' } }
  55. ```
  56. ## History
  57. ### v2.0.0
  58. * Adds support for escaping with double or single quotes. See [escaping](#escaping) for examples.
  59. * Will no longer split inside brackets or braces. See [bracket support](#bracket-support) for examples.
  60. If there are any regressions please create a [bug report](../../issues/new). Thanks!
  61. ## About
  62. ### Related projects
  63. * [assign-value](https://www.npmjs.com/package/assign-value): Assign a value or extend a deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/assign-value) | [homepage](https://github.com/jonschlinkert/assign-value "Assign a value or extend a deeply nested property of an object using object path notation.")
  64. * [get-value](https://www.npmjs.com/package/get-value): Use property paths (`a.b.c`) to get a nested value from an object. | [homepage](https://github.com/jonschlinkert/get-value "Use property paths (`a.b.c`) to get a nested value from an object.")
  65. * [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value "Returns true if a value exists, false if empty. Works with deeply nested values using object paths.")
  66. * [merge-value](https://www.npmjs.com/package/merge-value): Similar to assign-value but deeply merges object values or nested values using object path/dot notation. | [homepage](https://github.com/jonschlinkert/merge-value "Similar to assign-value but deeply merges object values or nested values using object path/dot notation.")
  67. * [omit-value](https://www.npmjs.com/package/omit-value): Omit properties from an object or deeply nested property of an object using object path… [more](https://github.com/jonschlinkert/omit-value) | [homepage](https://github.com/jonschlinkert/omit-value "Omit properties from an object or deeply nested property of an object using object path notation.")
  68. * [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value "Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.")
  69. * [union-value](https://www.npmjs.com/package/union-value): Set an array of unique values as the property of an object. Supports setting deeply… [more](https://github.com/jonschlinkert/union-value) | [homepage](https://github.com/jonschlinkert/union-value "Set an array of unique values as the property of an object. Supports setting deeply nested properties using using object-paths/dot notation.")
  70. * [unset-value](https://www.npmjs.com/package/unset-value): Delete nested properties from an object using dot notation. | [homepage](https://github.com/jonschlinkert/unset-value "Delete nested properties from an object using dot notation.")
  71. ### Contributing
  72. Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
  73. ### Contributors
  74. | **Commits** | **Contributor** |
  75. | --- | --- |
  76. | 59 | [jonschlinkert](https://github.com/jonschlinkert) |
  77. | 1 | [vadimdemedes](https://github.com/vadimdemedes) |
  78. | 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
  79. ### Building docs
  80. _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
  81. To generate the readme, run the following command:
  82. ```sh
  83. $ npm install -g verbose/verb#dev verb-generate-readme && verb
  84. ```
  85. ### Running tests
  86. Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
  87. ```sh
  88. $ npm install && npm test
  89. ```
  90. ### Author
  91. **Jon Schlinkert**
  92. * [github/jonschlinkert](https://github.com/jonschlinkert)
  93. * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
  94. ### License
  95. Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
  96. Released under the [MIT License](LICENSE).
  97. ***
  98. _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 21, 2017._