comment-json - npm Package Compare versions

Comparing version 0.1.9 to 0.1.10

lib/stringify.js

@@ -164,3 +164,3 @@ 'use strict';
           
-          var top = join(prev, 1);
+          var top = join(prev, 1, '\n' + deeper_gap);
           var right = prev[2];
@@ -184,3 +184,3 @@ if (top) {
             // ```
-            v = deeper_gap + top + v;
+            v = deeper_gap + top + '\n' + v;
           }
@@ -298,3 +298,6 @@
   return indent
-    ? head_comments + result + foot_comments
+    ? [head_comments, result, foot_comments]
+      // filter empty `head_comments` or `foot_comments`
+      .filter(Boolean)
+      .join('\n')
     : result;
@@ -304,5 +307,5 @@ };
 
-function join (host, key) {
+function join (host, key, joiner) {
   return host[key]
-    ? join_comments(host[key]) + '\n'
+    ? join_comments(host[key], joiner)
     : '';
@@ -312,6 +315,6 @@ }
 
-function join_comments (value) {
+function join_comments (value, joiner) {
   return is_array(value)
-    ? value.join('\n')
+    ? value.join(joiner || '\n')
     : value;
 }

package.json

 {
   "name": "comment-json",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Parse and stringify JSON file with comments",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

 # comment-json [![NPM version](https://badge.fury.io/js/comment-json.svg)](http://badge.fury.io/js/comment-json) [![Build Status](https://travis-ci.org/kaelzhang/node-comment-json.svg?branch=master)](https://travis-ci.org/kaelzhang/node-comment-json) [![Dependency Status](https://gemnasium.com/kaelzhang/node-comment-json.svg)](https://gemnasium.com/kaelzhang/node-comment-json)
 
-Parse and stringify JSON file with comments.
+- Parse JSON strings with comments into JavaScript objects.
+- stringify the objects into JSON strings with comments if there are.
 
+The usage of `comment-json` is exactly the same as the vanilla `JSON` object.
+
 ## Install
@@ -28,3 +31,3 @@
 // {
-//   "// name": "// package name",
+//   "// name": [["// package name"]],
 //   name: "comment-json"
@@ -40,3 +43,72 @@ // }
 
+Above all, `json.parse()` is not a parser with 100% accuracy to output a AST which describe every detail of the commented json, including the location of every comments, whitespaces, etc.
 
+But it DOES work, and could meet most of our requirements to record important informations as fast as possible without making everything too complicated. 
+
+#### Let's jump into a much more integrated case:
+
+code:
+
+```js
+/**
+ block comment at the top
+ */
+// comment at the top
+{
+  // comment for a
+  // comment line 2 for a
+  /* block comment */
+  "a": 1 // comment at right
+}
+// comment at the bottom
+```
+
+```js
+var result = json.parse(code);
+```
+
+Then the `result` will be:
+
+```js
+{
+  // Comments at the top of the file
+  '//^': [
+    '/**\n block comment at the top\n */', 
+    '// comment at the top'
+  ],
+
+  // Comments at the bottom of the file
+  '//$': ['// comment at the bottom'],
+
+  // Comment for a property is the value of `'// <prop>'`
+  '// a': [
+    // Comments above property `a`
+    [
+      '// comment for a',
+      '// comment line 2 for a',
+      '/* block comment */'
+    ],
+    ['// comment at right']
+  ],
+
+  // The real value
+  a: 1
+}
+```
+
+**TL;NR**
+
+There are two types of comments:
+  - single line comment which starts with `//`
+  - block comment which is wrapped by `/*` and `*/`
+
+`//^`, is the array which contains comments at the top. If there are two lines of comments which start with `//`, they will be considered as two comment items in the array.
+
+`//$`, similar to `//^`, is the comments at the bottom.
+
+`// <key>`, is a two-dimensional array contains the comments for a certain property `key`.
+  - the first item of the array is an array of the comments above the `key`
+  - the second item is the comments at the right side of the `key`
+
+
 ### json.stringify(object, [replacer], [space])
@@ -46,5 +118,16 @@
 
-And it does the similar thing as the vanilla one, and also stringify the `"// abc"`-like property into comments if the `"abc"` property is found.
+And it does the similar thing as the vanilla one, but also deal with extra properties and convert them into comments.
 
+#### space
 
+If space is not specified, or the space is an empty string, there will be no comments.
+
+For the case above:
+
+```js
+console.log( json.stringify(result) ); // {"a":1}
+console.log( json.stringify(result, null, 2) ); // is the same as `code`
+```
+
+
 <!-- ### json.strip(string)
@@ -51,0 +134,0 @@

test/comment-json.js

@@ -93,3 +93,5 @@ 'use strict';
     // simple case, of which the comment is not an array.
-    'simple'
+    'simple',
+    // #2
+    'indent'
   ],
@@ -96,0 +98,0 @@ [null],

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20420

increased by18.56%

Number of package files

33

increased by13.79%

Lines of code

525

increased by9.38%

Number of lines in readme file

149

increased by125.76%

No dependency changes