Merge pull request #31 from Roaders/codeExamples

Add support for insertCode

README.MD

@@ -276,6 +276,10 @@ Markers in the document describe where the content should be inserted, existing
 | **markdownPath** | **m** | string | The file to write to. Without replacement markers the whole file content will be replaced. Path can be absolute or relative. |
 | **replaceBelow** | | string | A marker in the file to replace text below. |
 | **replaceAbove** | | string | A marker in the file to replace text above. |
+| **insertCodeBelow** | | string | A marker in the file to insert code below. File path to insert must be added at the end of the line and optionally codeComment flag: 'insertToken file="path/toFile.md" codeComment="ts"' |
+| **insertCodeAbove** | | string | A marker in the file to insert code above. |
+| **copyCodeBelow** | | string | A marker in the file being inserted to say only copy code below this line |
+| **copyCodeAbove** | | string | A marker in the file being inserted to say only copy code above this line |
 | **jsFile** | **j** | string[] | jsFile to 'require' that has an export with the 'UsageGuideConfig' export. Multiple file can be specified. |
 | **configImportName** | **c** | string[] | Export name of the 'UsageGuideConfig' object. Defaults to 'usageGuideInfo'. Multiple exports can be specified. |
 | **verify** | **v** | boolean | Verify the markdown file. Does not update the file but returns a non zero exit code if the markdown file is not correct. Useful for a pre-publish script. |

package.json

@@ -1,6 +1,6 @@
 {
     "name": "ts-command-line-args",
-    "version": "2.2.2",
+    "version": "2.3.0",
     "description": "A Typescript wrapper around command-line-args with additional support for markdown usage guide generation",
     "bin": {
         "write-markdown": "dist/write-markdown.js"
@@ -22,14 +22,16 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
-        "clean": "rimraf dist",
+        "clean": "rimraf dist coverage",
         "build": "tsc -p tsconfig.build.json",
+        "build:example": "tsc -p src/example",
+        "watch-build:example": "tsc -p src/example --watch",
         "watch-build": "tsc --watch -p tsconfig.build.json",
         "lint": "eslint . --ext .ts",
         "test": "jest --ci --coverage && tsc --noemit",
         "watch-test": "jest --watch",
         "prebuild-release": "npm run clean",
-        "build-release": "concurrently --kill-others-on-fail npm:test npm:lint npm:build npm:verify-markdown && codecov",
+        "build-release": "concurrently --kill-others-on-fail npm:test npm:lint npm:build npm:build:example npm:verify-markdown && codecov",
         "prewrite-markdown": "npm run build",
         "preverify-markdown": "npm run build",
         "write-markdown": "node dist/write-markdown -f package.json -p markdownConfig",
@@ -53,7 +55,7 @@
         "string-format": "^2.0.0"
     },
     "devDependencies": {
-        "@morgan-stanley/ts-mocking-bird": "^0.2.2",
+        "@morgan-stanley/ts-mocking-bird": "^0.2.3",
         "@types/chalk": "^2.2.0",
         "@types/command-line-args": "^5.0.0",
         "@types/command-line-usage": "^5.0.1",

src/contracts.ts

@@ -289,6 +289,21 @@ export interface Content extends SectionHeader {
     includeIn?: 'markdown' | 'cli' | 'both';
 }
 
+export interface IInsertCodeTokens {
+    insertCodeBelow?: string;
+    insertCodeAbove?: string;
+    copyCodeBelow?: string;
+    copyCodeAbove?: string;
+    removeDoubleBlankLines: boolean;
+}
+
+export interface IInsertCodeOptions extends IInsertCodeTokens {
+    // This is used as the base path to resolve relative paths from.
+    // This is not used for absolute paths
+    // if not provided process.cwd() is used for resolution
+    dirname?: string;
+}
+
 export interface IReplaceOptions {
     replaceBelow?: string;
     replaceAbove?: string;
@@ -297,7 +312,7 @@ export interface IReplaceOptions {
 
 export type JsImport = { jsFile: string; importName: string };
 
-export interface IWriteMarkDown extends IReplaceOptions {
+export interface IWriteMarkDown extends IReplaceOptions, IInsertCodeTokens {
     markdownPath: string;
     jsFile: string[];
     configImportName: string[];

src/example/additionalModifiers.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { additionalModifiers } from './configs';
 
 const args = parse(additionalModifiers.arguments, additionalModifiers.parseOptions);

src/example/configs.ts

@@ -1,5 +1,5 @@
 /* eslint-disable no-useless-escape */
-import { ArgumentConfig, UsageGuideConfig } from '../contracts';
+import { ArgumentConfig, UsageGuideConfig } from '../';
 
 /**
  * we do not have any side effects in this file as this file is required by write-markdown

src/example/exampleConfig.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { argumentConfig } from './configs';
 
 const args = parse(argumentConfig);

src/example/exampleConfigHelpWithMissingArgs.ts

@@ -1,5 +1,4 @@
-import { CommandLineOption } from '../contracts';
-import { parse } from '../parse';
+import { parse, CommandLineOption } from '../';
 import { argumentConfig } from './configs';
 
 const args = parse(argumentConfig, {

src/example/exampleConfigUsingPrintHelp.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { argumentConfig } from './configs';
 
 const args = parse(argumentConfig, { hideMissingArgMessages: true }, false, true);

src/example/exampleConfigWithHelp.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 
 interface ICopyFilesArguments {
     sourcePath?: string;

src/example/exitProcessExample.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { argumentConfig } from './configs';
 
 /**

src/example/insert-code-sample.md

@@ -0,0 +1,21 @@
+# Code inserted from file:
+
+[//]: # (ts-command-line-args_write-markdown_insertCodeBelow file="./insert-code.example.ts" codeComment="ts")
+```ts
+async function insertSampleCode() {
+    const fileContent = readFileSync('src/example/insert-code-sample.md').toString();
+
+    const newContent = await insertCode(fileContent, {
+        insertCodeBelow: insertCodeBelowDefault,
+        insertCodeAbove: insertCodeAboveDefault,
+        copyCodeBelow: copyCodeBelowDefault,
+        copyCodeAbove: copyCodeAboveDefault,
+        dirname: dirname(`src/example/insert-code-sample.md`),
+    });
+
+    writeFileSync('src/example/insert-code-sample.md', newContent);
+}
+```
+[//]: # (ts-command-line-args_write-markdown_insertCodeAbove)
+
+The above code was inserted using `ts-command-line-args`

src/example/insert-code.example.ts

@@ -0,0 +1,27 @@
+import { insertCode } from '../';
+import { readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import {
+    copyCodeAboveDefault,
+    copyCodeBelowDefault,
+    insertCodeAboveDefault,
+    insertCodeBelowDefault,
+} from '../write-markdown.constants';
+
+// ts-command-line-args_write-markdown_copyCodeBelow
+async function insertSampleCode() {
+    const fileContent = readFileSync('src/example/insert-code-sample.md').toString();
+
+    const newContent = await insertCode(fileContent, {
+        insertCodeBelow: insertCodeBelowDefault,
+        insertCodeAbove: insertCodeAboveDefault,
+        copyCodeBelow: copyCodeBelowDefault,
+        copyCodeAbove: copyCodeAboveDefault,
+        dirname: dirname(`src/example/insert-code-sample.md`),
+    });
+
+    writeFileSync('src/example/insert-code-sample.md', newContent);
+}
+// ts-command-line-args_write-markdown_copyCodeAbove
+
+insertSampleCode();

src/example/noExitProcessExample.ts

@@ -1,5 +1,5 @@
 import { argumentConfig } from './configs';
-import { parse } from '../parse';
+import { parse } from '../';
 
 /**
  * will ignore missing errors and not exit

src/example/tsconfig.json

@@ -0,0 +1,6 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "declaration": false,
+    }
+}

src/example/typicalAppWithGroups.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { typicalAppWithGroupsInfo } from './configs';
 
 const args = parse(typicalAppWithGroupsInfo.arguments, typicalAppWithGroupsInfo.parseOptions);

src/example/unknownArgumentsExample.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { argumentConfig } from './configs';
 
 /**

src/example/usageGuideWithExamples.ts

@@ -1,4 +1,4 @@
-import { parse } from '../parse';
+import { parse } from '../';
 import { exampleSections } from './configs';
 
 const args = parse(exampleSections.arguments, exampleSections.parseOptions);

src/helpers/content.helper.spec.ts → src/helpers/add-content.helper.spec.ts

@@ -1,7 +1,7 @@
-import { addContent } from './content.helper';
+import { addContent } from './add-content.helper';
 import { IReplaceOptions } from '../contracts';
 
-describe('conent.helper', () => {
+describe('content.helper', () => {
     describe('addContent', () => {
         const newContent = `new content line one
 new content line two`;

src/helpers/content.helper.ts → src/helpers/add-content.helper.ts

@@ -1,6 +1,6 @@
 import { IReplaceOptions } from '../contracts';
 import { footerReplaceBelowMarker } from '../write-markdown.constants';
-import { splitContent, findEscapeSequence } from './line-ending.helper';
+import { splitContent, findEscapeSequence, filterDoubleBlankLines } from './line-ending.helper';
 
 /**
  * Adds or replaces content between 2 markers within a text string
@@ -32,12 +32,12 @@ export function addContent(inputString: string, content: string | string[], opti
     const linesBefore = lines.slice(0, replaceBelowIndex + 1);
     const linesAfter = replaceAboveIndex >= 0 ? lines.slice(replaceAboveIndex) : [];
 
-    const constantLines = content.reduce(
+    const contentLines = content.reduce(
         (lines, currentContent) => [...lines, ...splitContent(currentContent)],
         new Array<string>(),
     );
 
-    let allLines = [...linesBefore, ...constantLines, ...linesAfter];
+    let allLines = [...linesBefore, ...contentLines, ...linesAfter];
 
     if (options.removeDoubleBlankLines) {
         allLines = allLines.filter((line, index, lines) => filterDoubleBlankLines(line, index, lines));
@@ -60,11 +60,3 @@ ${footerReplaceBelowMarker}`;
         removeDoubleBlankLines: false,
     });
 }
-
-const nonWhitespaceRegExp = /[^ \t]/;
-
-function filterDoubleBlankLines(line: string, index: number, lines: string[]): boolean {
-    const previousLine = index > 0 ? lines[index - 1] : undefined;
-
-    return nonWhitespaceRegExp.test(line) || previousLine == null || nonWhitespaceRegExp.test(previousLine);
-}

src/helpers/index.ts

@@ -1,7 +1,8 @@
 export * from './command-line.helper';
-export * from './content.helper';
+export * from './add-content.helper';
 export * from './markdown.helper';
 export * from './visitor';
 export * from './line-ending.helper';
 export * from './options.helper';
 export * from './string.helper';
+export * from './insert-code.helper';