FUSETOOLS2-1067 - adding settings and doc (#530)

* FUSETOOLS2-1067 - adding settings and doc

* updating available commands doc
* adding tests
* handling blank value

Signed-off-by: Brian Fitzpatrick <bfitzpat@redhat.com>

Author: bfitzpat

CHANGELOG.md

@@ -23,6 +23,8 @@ All notable changes to the "vscode-didact" extension will be documented in this
 - Added `Insert Didact Badge` completion to show `Powered by Didact` badge with link back to the project in GitHub
 - Added new `vscode` URI processing to handle registering a Didact tutorial via a web link and a new command - `Didact: Process VSCode link from web` to process a copied link
 - Add new `Ctrl/Cmd+Alt+T` shortcut to convert selected text into a `sendNamedTerminalAString` Didact link
+  - Added new settings to customize the link text shown and whether to execute the command in the terminal
+  - Add new `sendNamedTerminalAStringNoLF` command that sends text to the terminal but doesn't execute it
 
 ## 0.3.2
 

docs/available-commands.md

@@ -81,6 +81,10 @@ Sends text to a named terminal, which is then executed in the terminal. If the n
 
 Note: In order to send multiple commands spread out across multiple links in the same terminal window, ensure that the `name` passed is consistent.
 
+## vscode.didact.sendNamedTerminalAStringNoLF
+
+Same as sendNamedTerminalAString, but the command is not executed in the terminal by default.
+
 ## vscode.didact.sendNamedTerminalCtrlC
 
 Send a Ctrl+C key combination to a named terminal to stop a long-running process. Terminal with the given name must be accessible.
@@ -212,6 +216,18 @@ Command to copy text directly from the URL to the clipboard. Handy for short str
 * Input: URL encoded text to copy onto the clipboard
 * Example: `didact://?commandId=vscode.didact.copyToClipboardCommand&text=The%20fox%20jumped%20over%20the%20lazy%20dog.`
 
+## vscode.didact.copyTextToCLI
+
+Command to take the currently selected text in the open editor (of a Didact Markdown or AsciiDoc file) and add a new Didact `sendNamedTerminalAString` or `sendNamedTerminalAStringNoLF` link with the selected text automatically URLencoded.
+
+This is triggered by default using `Ctrl+Alt+T` or `Cmd+Alt+T`. Note that the key combination can be changed by going into Keyboard Shortcuts (`File->Preferences->Keyboard Shortcuts`) and searching for `copyTextToCLI`, then overwriting the Keybinding.
+
+A couple of things to note:
+
+* Any link inserted using this method will be surrounded by parentheses. For example, `^ execute` will appear in the Didact link as `(^ execute)`. 
+* Though you can modify the text inside the parentheses (i.e. `^ execute`) in the [`Didact>Edit: Cli Link Text` field in the Settings for Didact](https://redhat-developer.github.io/vscode-didact/settings), some characters will need to be escaped such as close square brackets (`\]`) due to the way links are formatted in Markdown and AsciiDoc.
+* You can insert emojis such as the [play button](https://emojipedia.org/play-button/) or [two-hump camel](https://emojipedia.org/two-hump-camel/) instead of text. 
+
 ***
 # Commands Elsewhere
 

docs/images/settings.jpg

@@ -7,4 +7,9 @@ The Didact Extension has several configurable settings available. To access the
 * To turn on generic Didact completion notifications (off by default), set the `Didact: Disable Notifications` checkbox. If unchecked, additional notifications will occur when Didact actions are activated in the IDE.
 * To have Didact open a window with the default Didact file on startup, set the `Didact: Open Default Tutorial At Startup` checkbox.
 
+The `vscode.didact.copyTextToCLI` command (accessible via the default keyboard shorcut `Ctrl/Cmd+Alt+T`) has two customizations available:
+
+* By default, the Didact link generated commits the change, executing it in the VS Code terminal. To simply add the text to the terminal without executing it, uncheck the `Didact>Edit:Cli Link LF` checkbox.
+* By default, the Didact link generated uses the label `(^ Execute)`, but you can change that by updating the `Didact>Edit: Cli Link Text` field. Note that this field can also use Emojis, so you can use characters such as the `Play` button [(▶️)](https://emojipedia.org/play-button/).
+
 ![Didact Settings](./images/settings.jpg)

docs/settings.md

@@ -45,7 +45,7 @@
 	"contributes": {
 		"configuration": [
 			{
-				"title": "Didact Extension Settings",
+				"title": "Didact",
 				"properties": {
 					"didact.defaultUrl": {
 						"type": "string",
@@ -70,6 +70,20 @@
 						"default": "true",
 						"description": "Automatically add the default Didact tutorials to the Didact Tutorials view at workspace startup if not already registered",
 						"scope": "window"
+					},
+					"didact.edit.cliLinkText": {
+						"type": "string",
+						"default": "^ execute",
+						"markdownDescription": "Link text to use when converting text for use in a copyTextToCLI terminal link. Cannot be an empty string. Special characters must be escaped. Defaults to `^ execute`. [Read more.](https://redhat-developer.github.io/vscode-didact/settings)",
+						"scope": "window",
+						"pattern": "^(?!\\s*$).+",
+						"patternErrorMessage": "Link text cannot be an empty string. Please provide at least one character."
+					},
+					"didact.edit.cliLinkLF": {
+						"type": "boolean",
+						"default": "true",
+						"markdownDescription": "Automatically execute copyTextToCLI command in generated CLI terminal link. [Read more.](https://redhat-developer.github.io/vscode-didact/settings)",
+						"scope": "window"
 					}
 				}
 			}

package.json

@@ -21,13 +21,11 @@ import { DidactNodeProvider, SimpleNode } from './nodeProvider';
 import { registerTutorialWithCategory, clearRegisteredTutorials, getOpenAtStartupSetting, 
 	clearOutputChannels, registerTutorialWithJSON, getAutoInstallDefaultTutorialsSetting,
 	addNewTutorialWithNameAndCategoryForDidactUri, 
-	removeTutorialByNameAndCategory,
-	getValue} from './utils';
+	removeTutorialByNameAndCategory } from './utils';
 import { DidactUriCompletionItemProvider } from './didactUriCompletionItemProvider';
 import { DidactPanelSerializer } from './didactPanelSerializer';
 import { didactManager, VIEW_TYPE } from './didactManager';
-import { handleVSCodeDidactUriParsingForPath, handleVSCodeUri, sendTextToOutputChannel } from './extensionFunctions';
-import * as querystring from 'querystring';
+import { handleVSCodeUri } from './extensionFunctions';
 
 const DIDACT_VIEW = 'didact.tutorials';
 
@@ -48,6 +46,7 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.START_DIDACT_COMMAND, extensionFunctions.revealOrStartDidactByURI));
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.START_TERMINAL_COMMAND, extensionFunctions.startTerminal));
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.SEND_TERMINAL_SOME_TEXT_COMMAND, extensionFunctions.sendTerminalText));
+	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.SEND_TERMINAL_SOME_TEXT_COMMAND_NO_LF, extensionFunctions.sendTerminalTextNoLF));
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.REQUIREMENT_CHECK_COMMAND, extensionFunctions.requirementCheck));
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.EXTENSION_REQUIREMENT_CHECK_COMMAND, extensionFunctions.extensionCheck));
 	context.subscriptions.push(vscode.commands.registerCommand(extensionFunctions.WORKSPACE_FOLDER_EXISTS_CHECK_COMMAND, extensionFunctions.validWorkspaceCheck));

src/extension.ts

@@ -28,19 +28,19 @@ import { handleExtFilePath, handleProjectFilePath } from './commandHandler';
 import * as download from 'download';
 import { didactManager } from './didactManager';
 import { parse } from 'node-html-parser';
-import { addNewTutorialWithNameAndCategoryForDidactUri, delay, DIDACT_DEFAULT_URL, getCachedOutputChannel, getCurrentFileSelectionPath, getValue, getWorkspacePath, registerTutorialWithCategory, rememberOutputChannel } from './utils';
+import { addNewTutorialWithNameAndCategoryForDidactUri, delay, DIDACT_DEFAULT_URL, getCachedOutputChannel, getCurrentFileSelectionPath, getInsertLFForCLILinkSetting, getLinkTextForCLILinkSetting, getValue, getWorkspacePath, registerTutorialWithCategory, rememberOutputChannel } from './utils';
 
 const tmp = require('tmp');
 const fetch = require('node-fetch');
 const url = require('url-parse');
-const EDITOR_OPENED_TIMEOUT = 3000;
 
 // command IDs
 export const SCAFFOLD_PROJECT_COMMAND = 'vscode.didact.scaffoldProject';
 export const OPEN_TUTORIAL_COMMAND = 'vscode.didact.openTutorial';
 export const START_DIDACT_COMMAND = 'vscode.didact.startDidact';
 export const START_TERMINAL_COMMAND = 'vscode.didact.startTerminalWithName';
 export const SEND_TERMINAL_SOME_TEXT_COMMAND = 'vscode.didact.sendNamedTerminalAString';
+export const SEND_TERMINAL_SOME_TEXT_COMMAND_NO_LF = 'vscode.didact.sendNamedTerminalAStringNoLF';
 export const REQUIREMENT_CHECK_COMMAND = 'vscode.didact.requirementCheck';
 export const EXTENSION_REQUIREMENT_CHECK_COMMAND = 'vscode.didact.extensionRequirementCheck';
 export const WORKSPACE_FOLDER_EXISTS_CHECK_COMMAND = 'vscode.didact.workspaceFolderExistsCheck';
@@ -185,10 +185,10 @@ export async function startTerminal(...rest: any[]): Promise<void>{ //name:strin
 	}
 }
 
-export async function showAndSendText(terminal: vscode.Terminal, text:string): Promise<void> {
+export async function showAndSendText(terminal: vscode.Terminal, text:string, sendLF = true): Promise<void> {
 	if (terminal) {
 		terminal.show();
-		terminal.sendText(text);
+		terminal.sendText(text, sendLF);
 	}
 }
 
@@ -220,15 +220,24 @@ export function findTerminal(name: string) : vscode.Terminal | undefined {
 }
 
 // send a message to a named terminal
-export async function sendTerminalText(name:string, text:string): Promise<void> {
+export async function sendTerminalText(name:string, text:string, sendLF = true): Promise<void> {
 	let terminal : vscode.Terminal | undefined = findTerminal(name);
 	if (!terminal) {
 		terminal = vscode.window.createTerminal(name);
 	}
 	if (terminal) {
-		showAndSendText(terminal, text);
+		showAndSendText(terminal, text, sendLF);
+	}
+	const msg = `Sent terminal ${name} the text ${text}`;
+	if (sendLF) {
+		sendTextToOutputChannel(msg + ` with LF`);
+	} else {
+		sendTextToOutputChannel(msg);
 	}
-	sendTextToOutputChannel(`Sent terminal ${name} the text ${text}`);
+}
+
+export async function sendTerminalTextNoLF(name:string, text:string): Promise<void> {
+	return sendTerminalText(name, text, false);
 }
 
 export async function sendTerminalCtrlC(name:string): Promise<void> {
@@ -1137,6 +1146,22 @@ export async function handleVSCodeUri(uri:vscode.Uri | undefined) : Promise<void
 	}
 }
 
+// for testing purposes
+export function getDidactLinkForSelectedText(selectedText : string, isAdoc : boolean) : string {
+	const encodedText = encodeURI(selectedText);
+	const linkText = getLinkTextForCLILinkSetting();
+	const linkUseLF = getInsertLFForCLILinkSetting();
+	let commandToUse = 'vscode.didact.sendNamedTerminalAString';
+	if(!linkUseLF) {
+		commandToUse = 'vscode.didact.sendNamedTerminalAStringNoLF';
+	}
+	let templatedLink = ` ([${linkText}](didact://?commandId=${commandToUse}&text=newTerminal$$${encodedText}))`;
+	if (isAdoc) {
+		templatedLink = ` link:didact://?commandId=${commandToUse}&text=newTerminal$$${encodedText}[(${linkText})]`;
+	}
+	return templatedLink;
+}
+
 export async function convertSelectionToCLILinkAndInsertAfterSelection() : Promise<void> {
 	const editor = vscode.window.activeTextEditor;
 	if (editor) {
@@ -1147,12 +1172,8 @@ export async function convertSelectionToCLILinkAndInsertAfterSelection() : Promi
 		const selection = vscode.window.activeTextEditor?.selection;
 		const selectedText = vscode.window.activeTextEditor?.document.getText(selection);
 		if (selectedText && selectedText.trim().length > 0) {
-			const encodedText = encodeURI(selectedText);
 			const isAdoc = isAsciiDoc(editor.document.uri?.toString());
-			let templatedLink = ` ([^ execute](didact://?commandId=vscode.didact.sendNamedTerminalAString&text=newTerminal$$${encodedText}))`;
-			if (isAdoc) {
-				templatedLink = ` link:didact://?commandId=vscode.didact.sendNamedTerminalAString&text=newTerminal$$${encodedText}[(^ execute)]`;
-			}
+			const templatedLink = getDidactLinkForSelectedText(selectedText, isAdoc);
 			await insertTextAtFirstWhitespacePastCurrentSelection(templatedLink);
 		}
 	}

src/extensionFunctions.ts

@@ -110,7 +110,7 @@ suite("Didact URI completion provider tests", function () {
 	test("that the command processing for a command prefix returns expected results", async () => {
 		const match = provider.findMatchForCommandVariable('didact://?commandId=vscode.didact.');
 		const completionList = await provider.processCommands(match);
-		expect(completionList.items).to.have.lengthOf(34)
+		expect(completionList.items).to.have.lengthOf(35)
 	});
 
 	test("that the command processing for one command returns one expected result", async () => {

src/test/suite/didactUriCompletionItemProvider.test.ts

@@ -3,7 +3,7 @@ import * as vscode from 'vscode';
 import * as extensionFunctions from '../../extensionFunctions';
 import { handleExtFilePath, handleProjectFilePath } from '../../commandHandler';
 import * as path from 'path';
-import { removeFilesAndFolders, getCachedOutputChannel, getCachedOutputChannels } from '../../utils';
+import { removeFilesAndFolders, getCachedOutputChannel, getCachedOutputChannels, setInsertLFForCLILinkSetting, getLinkTextForCLILinkSetting, setLinkTextForCLILinkSetting, DEFAULT_EXECUTE_LINK_TEXT } from '../../utils';
 import { beforeEach, after, afterEach } from 'mocha';
 import * as sinon from 'sinon';
 import { expect } from 'chai';
@@ -317,6 +317,56 @@ suite('Extension Functions Test Suite', () => {
 			expect.fail("Editor did not open");
 		}
 	});
+
+	test('verify inserted link text for markdown CLI and default send terminal command', async() => {
+		const selectedText = `echo The quick brown fox markdown`;
+		await setInsertLFForCLILinkSetting(true); // reset default
+		const linkText = getLinkTextForCLILinkSetting();
+		const generatedText = extensionFunctions.getDidactLinkForSelectedText(selectedText, false);
+		const encodedText = encodeURI(selectedText);
+		const defaultCommandToUse = extensionFunctions.SEND_TERMINAL_SOME_TEXT_COMMAND;
+		const expectedLink = ` ([${linkText}](didact://?commandId=${defaultCommandToUse}&text=newTerminal$$${encodedText}))`;
+		expect(generatedText.trim()).to.deep.equal(expectedLink.trim());
+	});
+
+	test('verify inserted link text for adoc CLI and LF send terminal command setting set', async() => {
+		const selectedText = `echo The quick brown fox adoc`;
+		await setInsertLFForCLILinkSetting(false);
+		const linkText = getLinkTextForCLILinkSetting();
+		const generatedText = extensionFunctions.getDidactLinkForSelectedText(selectedText, true);
+		const encodedText = encodeURI(selectedText);
+		const defaultCommandToUse = extensionFunctions.SEND_TERMINAL_SOME_TEXT_COMMAND_NO_LF;
+		const expectedLink = ` link:didact://?commandId=${defaultCommandToUse}&text=newTerminal$$${encodedText}[(${linkText})]`;
+		await setInsertLFForCLILinkSetting(true); // reset default
+		expect(generatedText.trim()).to.deep.equal(expectedLink.trim());
+	});
+
+	test('verify altered link text appears in generated CLI link', async() => {
+		const selectedText = `echo The quick brown fox`;
+		await setInsertLFForCLILinkSetting(true); // reset default
+		const newLinkText = `**link**`;
+		await setLinkTextForCLILinkSetting(newLinkText);
+		const generatedText = extensionFunctions.getDidactLinkForSelectedText(selectedText, false);
+		const encodedText = encodeURI(selectedText);
+		const defaultCommandToUse = extensionFunctions.SEND_TERMINAL_SOME_TEXT_COMMAND;
+		const expectedLink = ` ([${newLinkText}](didact://?commandId=${defaultCommandToUse}&text=newTerminal$$${encodedText}))`;
+		await setLinkTextForCLILinkSetting(DEFAULT_EXECUTE_LINK_TEXT); // reset default
+		expect(generatedText.trim()).to.deep.equal(expectedLink.trim());
+	});
+
+	test('validate that if we clear the link text setting, it resets to default', async() => {
+		await setLinkTextForCLILinkSetting(DEFAULT_EXECUTE_LINK_TEXT); // reset default
+		await setLinkTextForCLILinkSetting(undefined);
+		const linkTextFromSettings = getLinkTextForCLILinkSetting();
+		await setLinkTextForCLILinkSetting(DEFAULT_EXECUTE_LINK_TEXT); // reset default
+		expect(linkTextFromSettings).to.equal(DEFAULT_EXECUTE_LINK_TEXT);
+
+		await setLinkTextForCLILinkSetting(''); // blank
+		const linkTextFromSettings2 = getLinkTextForCLILinkSetting();
+		await setLinkTextForCLILinkSetting(DEFAULT_EXECUTE_LINK_TEXT); // reset default
+		expect(linkTextFromSettings2).to.equal(DEFAULT_EXECUTE_LINK_TEXT);
+	});
+
 });
 
 function checkCanParseDidactUriForPath(urlValue: string, endToCheck: string, alternateEnd : string) {

src/test/suite/extensionFunctions.test.ts

@@ -28,9 +28,13 @@ export const DIDACT_NOTIFICATION_SETTING = 'didact.disableNotifications';
 export const DIDACT_COLUMN_SETTING = 'didact.lastColumnUsed';
 export const DIDACT_OPEN_AT_STARTUP = 'didact.openDefaultTutorialAtStartup';
 export const DIDACT_AUTO_INSTALL_DEFAULT_TUTORIALS = 'didact.autoAddDefaultTutorials';
+export const DIDACT_CLI_LINK_LF_SETTING = 'didact.edit.cliLinkLF';
+export const DIDACT_CLI_LINK_TEXT_SETTING = 'didact.edit.cliLinkText';
 
 const CACHED_OUTPUT_CHANNELS: OutputChannel[] = new Array<OutputChannel>();
 
+export const DEFAULT_EXECUTE_LINK_TEXT = '^ execute';
+
 export interface ITutorial {
 	name: string;
 	category: string;
@@ -463,3 +467,25 @@ export async function removeTutorialByNameAndCategory(node : TutorialNode ) : Pr
 	}
 	return success;
 }
+
+export function getInsertLFForCLILinkSetting() : boolean {
+	return workspace.getConfiguration().get(DIDACT_CLI_LINK_LF_SETTING, true);
+}
+
+export function getLinkTextForCLILinkSetting() : string {
+	const value = workspace.getConfiguration().get(DIDACT_CLI_LINK_TEXT_SETTING, DEFAULT_EXECUTE_LINK_TEXT);
+	if (value && value.trim().length > 0) {
+		return value;
+	}
+	return DEFAULT_EXECUTE_LINK_TEXT;
+}
+
+// for testing
+export async function setInsertLFForCLILinkSetting(flag: boolean): Promise<void> {
+	await workspace.getConfiguration().update(DIDACT_CLI_LINK_LF_SETTING, flag);
+}
+
+// for testing
+export async function setLinkTextForCLILinkSetting(text: string | undefined): Promise<void> {
+	await workspace.getConfiguration().update(DIDACT_CLI_LINK_TEXT_SETTING, text);
+}