[jest-docblock] add strip (#4571)

* [jest-docblock] add strip

* add a couple tests

* off by one error

* improve code as per @cpojers suggestion

packages/jest-docblock/README.md

@@ -57,11 +57,14 @@ const code = `
  }
 `;
 
-const { extract, parse, parseWithComments, print } = require("jest-docblock");
+const { extract, strip, parse, parseWithComments, print } = require("jest-docblock");
 
 const docblock = extract(code);
 console.log(docblock); // "/**\n * Everything is awesome!\n * \n * @everything is:awesome\n * @flow\n */"
 
+const stripped = strip(code);
+console.log(stripped); // "export const everything = Object.create(null);\n export default function isAwesome(something) {\n return something === everything;\n }"
+
 const pragmas = parse(docblock);
 console.log(pragmas); // { everything: "is:awesome", flow: "" }
 
@@ -76,11 +79,14 @@ console.log(print({pragmas, comments: "hi!"})) // /**\n * hi!\n *\n * @everythin
 ### `extract(contents: string): string`
 Extracts a docblock from some file contents. Returns the docblock contained in `contents`. If `contents` did not contain a docblock, it will return the empty string (`""`).
 
+### `strip(contents: string): string`
+Strips the top docblock from a file and return the result. If a file does not have a docblock at the top, then return the file unchanged.
+
 ### `parse(docblock: string): {[key: string]: string}`
 Parses the pragmas in a docblock string into an object whose keys are the pragma tags and whose values are the arguments to those pragmas.
 
 ### `parseWithComments(docblock: string): { comments: string, pragmas: {[key: string]: string} }`
 Similar to `parse` except this method also returns the comments from the docblock. Useful when used with `print()`.
 
 ### `print({ comments?: string, pragmas?: {[key: string]: string} }): string`
-Prints an object of key-value pairs back into a docblock. If `comments` are provided, they will be positioned on the top of the docblock.
+Prints an object of key-value pairs back into a docblock. If `comments` are provided, they will be positioned on the top of the docblock.

packages/jest-docblock/src/__tests__/index.test.js

@@ -280,6 +280,16 @@ describe('docblock', () => {
     });
   });
 
+  it('strips the docblock out of a file that contains a top docblock', () => {
+    const code = '/**\n * foo\n * bar\n*/\nthe rest';
+    expect(docblock.strip(code)).toEqual('\nthe rest');
+  });
+
+  it('returns a file unchanged if there is no top docblock to strip', () => {
+    const code = 'someCodeAtTheTop();\n/** docblock */';
+    expect(docblock.strip(code)).toEqual(code);
+  });
+
   it('prints docblocks with no pragmas as empty string', () => {
     const pragmas = {};
     expect(docblock.print({pragmas})).toEqual('');

packages/jest-docblock/src/index.js

@@ -26,6 +26,11 @@ export function extract(contents: string): string {
   return match ? match[0].replace(ltrimRe, '') || '' : '';
 }
 
+export function strip(contents: string) {
+  const match = contents.match(docblockRe);
+  return match && match[0] ? contents.substring(match[0].length) : contents;
+}
+
 export function parse(docblock: string): {[key: string]: string} {
   return parseWithComments(docblock).pragmas;
 }