Skip to content

Latest commit

 

History

History
161 lines (115 loc) · 5.3 KB

README.md

File metadata and controls

161 lines (115 loc) · 5.3 KB
Raw

budgie-cli 🦜

Build Status NPM version

Node CLI for General Language Syntax (Budgie).

Usage

npm install budgie-cli --global

budgie --help

Pass any number of filenames and/or globs (matched with glob) to the CLI to convert those files to an output -l/--language.

Input files to convert from Budgie to the output language must have a .bg extension.

.ts files may also be given with -t/--tsconfig to compile to .bg files before output language conversion.

Option Purpose
-e/--exclude Glob(s) of file(s) to exclude from conversion.
-l/--language Output language to convert to.
(Required)
-n/--namespace Namespace before path names, such as "Budgie".
-p/--project Path to a budgie.json project file to indicate to create project root-level exports and metadata files. Will default to a budgie.json file detected in the current directory if one exists and -p/--project is not provided as false.
-t/--tsconfig TypeScript project configuration file. (Required if .ts file(s) given)
-v/--version Prints the Budgie, budgie-cli, and TS-Budgie versions.

Example Usage

To convert file.bg to file.py:

budgie --language Python file.bg

To convert *.ts to *.bg, then to *.java:

budgie --language Java --tsconfig ./tsconfig *.ts

Requires Node >=8

Development

To build from scratch, install Node.js and run the following commands:

npm install
npm install budgielang ts-budgie typescript --no-save
npm run verify

Check package.json for the full list of commands. To set up source file compiling in watch mode, use tsc -w.

Tests

Run tsc -p test to build tests, or tsc -p test -w to rebuild the files in watch mode. Run npm run test:run to run tests.

Internals

When the CLI is called, the following code paths are used in order:

  1. Cli
  2. Main
  3. Preprocessing
  4. Conversions
  5. Postprocessing

Cli

Parses raw string arguments using commander. If the args are valid, it calls to the Main method.

System dependencies such as the IFileSystem and globber may be dependency-injected to override the defaults.

See cli.ts.

Main

Validates Budgie settings, sets up the conversion's Preprocess, Runner, and Postprocess, then runs them in that order. There are two real behaviors here not covered by the Cli:

  • Globbing file paths passed as glob args and reading them the file system.
  • Validating the provided language is known by Budgie.

See main.ts.

Preprocessing

If any files are passed in with native language extensions, namely .ts for TypeScript, they are converted here using that langauge's converter to their .bg equivalent.

For example, if a .ts file is provided, it will attempt to convert it using TS-Budgie and return the generated .bg file path. If a .bg file path is provided, it will do nothing and pass that path through.

Any language-specific files that are used as metadata files for that language, such as src/index.js for JavaScript, will be removed from the files list.

See preprocessFiles.ts.

Conversions

Converts each .bg file to the output language(s).

convertFiles uses an async queue to throttle the number of files that are attempted to be converted via convertFile at once, as some conversions may need asynchronous operations. Creates a BudgieConverter per output language and has each file run through them.

See convertFiles.ts and convertFile.ts.

Postprocess

Runs tasks on the converted .bg files as a project group after they've been successfully created.

If a .budgie.json is not provided or detected, this does nothing. Otherwise, it creates a root metadata file(s) as specified by each output language. These are typically one or both of:

  • Metadata file describing the output project.
  • Exports file exporting publicaly exportable objects for languages that need them.

See postprocess.ts.