diff --git a/packages/jest-docblock/README.md b/packages/jest-docblock/README.md index 85a740b8e6aa..4ffee198f817 100644 --- a/packages/jest-docblock/README.md +++ b/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,6 +79,9 @@ 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. @@ -83,4 +89,4 @@ Parses the pragmas in a docblock string into an object whose keys are the pragma 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. \ No newline at end of file +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. diff --git a/packages/jest-docblock/src/__tests__/index.test.js b/packages/jest-docblock/src/__tests__/index.test.js index b2097b3ba484..579560a3de63 100644 --- a/packages/jest-docblock/src/__tests__/index.test.js +++ b/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(''); diff --git a/packages/jest-docblock/src/index.js b/packages/jest-docblock/src/index.js index 7281a6941f77..7eddad6f94b7 100644 --- a/packages/jest-docblock/src/index.js +++ b/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; }