balena-cli/automation/capitanodoc/utils.ts
Paulo Castro abf573fa47 Begin the transition to oclif with 'balena env add' (fix dropped leading
zero in device UUID).

This commit is fairly chunky because it adds the oclif dependency for
the first time, and refactors the CLI help and docs generation code to
accommodate both Capitano and oclif.

Change-type: patch
Signed-off-by: Paulo Castro <paulo@balena.io>
2019-06-04 13:51:56 +01:00

150 lines
4.1 KiB
TypeScript

/**
* @license
* Copyright 2019 Balena Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { OptionDefinition } from 'capitano';
import * as ent from 'ent';
import * as fs from 'fs';
import * as _ from 'lodash';
import * as readline from 'readline';
export function getOptionPrefix(signature: string) {
if (signature.length > 1) {
return '--';
} else {
return '-';
}
}
export function getOptionSignature(signature: string) {
return `${getOptionPrefix(signature)}${signature}`;
}
export function parseCapitanoOption(option: OptionDefinition): string {
let result = getOptionSignature(option.signature);
if (_.isArray(option.alias)) {
for (const alias of option.alias) {
result += `, ${getOptionSignature(alias)}`;
}
} else if (_.isString(option.alias)) {
result += `, ${getOptionSignature(option.alias)}`;
}
if (option.parameter) {
result += ` <${option.parameter}>`;
}
return ent.encode(result);
}
/** Convert e.g. 'env add NAME [VALUE]' to 'env add <name> [value]' */
export function capitanoizeOclifUsage(
oclifUsage: string | string[] | undefined,
): string {
return (oclifUsage || '')
.toString()
.replace(/(?<=\s)[A-Z]+(?=(\s|$))/g, match => `<${match}>`)
.toLowerCase();
}
export class MarkdownFileParser {
constructor(public mdFilePath: string) {}
/**
* Extract the lines of a markdown document section with the given title.
* For example, consider this sample markdown document:
* ```
* # balena CLI
*
* ## Introduction
* Lorem ipsum dolor sit amet, consectetur adipiscing elit,
*
* ## Getting Started
* sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
*
* ### Prerequisites
* - Foo
* - Bar
*
* ## Support
* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
* ```
*
* Calling getSectionOfTitle('Getting Started') for the markdown doc above
* returns everything from line '## Getting Started' (included) to line
* '## Support' (excluded). This method counts the number of '#' characters
* to determine that subsections should be included as part of the parent
* section.
*
* @param title The section title without '#' chars, eg. 'Getting Started'
*/
public async getSectionOfTitle(
title: string,
includeSubsections = true,
): Promise<string> {
let foundSectionLines: string[];
let foundSectionLevel = 0;
const rl = readline.createInterface({
input: fs.createReadStream(this.mdFilePath),
crlfDelay: Infinity,
});
rl.on('line', line => {
// try to match a line like "## Getting Started", where the number
// of '#' characters is the sectionLevel ('##' -> 2), and the
// sectionTitle is "Getting Started"
const match = /^(#+)\s+(.+)/.exec(line);
if (match) {
const sectionLevel = match[1].length;
const sectionTitle = match[2];
// If the target section had already been found: append a line, or end it
if (foundSectionLines) {
if (!includeSubsections || sectionLevel <= foundSectionLevel) {
// end previously found section
rl.close();
}
} else if (sectionTitle === title) {
// found the target section
foundSectionLevel = sectionLevel;
foundSectionLines = [];
}
}
if (foundSectionLines) {
foundSectionLines.push(line);
}
});
return await new Promise((resolve, reject) => {
rl.on('close', () => {
if (foundSectionLines) {
resolve(foundSectionLines.join('\n'));
} else {
reject(
new Error(
`Markdown section not found: title="${title}" file="${
this.mdFilePath
}"`,
),
);
}
});
});
}
}