https://github.com/budgielang/budgie-cli

Node CLI for Budgie. 🦜
https://github.com/budgielang/budgie-cli

csharp gls java javascript metaprogramming node npm oop-languages python ruby typescript

Last synced: 2 months ago
JSON representation

Node CLI for Budgie. 🦜

• Host: GitHub
• URL: https://github.com/budgielang/budgie-cli
• Owner: budgielang
• License: mit
• Created: 2017-07-28T08:15:55.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2020-06-02T00:35:47.000Z (almost 5 years ago)
• Last Synced: 2025-01-16T16:58:45.830Z (5 months ago)
• Topics: csharp, gls, java, javascript, metaprogramming, node, npm, oop-languages, python, ruby, typescript
• Language: TypeScript
• Homepage: https://budgielang.org
• Size: 1.85 MB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 17
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# `budgie-cli` 🦜

[![Build Status](https://travis-ci.org/budgielang/budgie-cli.svg?)](https://travis-ci.org/budgielang/budgie-cli)

[![NPM version](https://badge.fury.io/js/budgie-cli.svg)](http://badge.fury.io/js/budgie-cli)

Node CLI for [General Language Syntax (Budgie)](https://github.com/budgielang/Budgie).

## Usage

```cmd

npm install budgie-cli --global

budgie --help

```

Pass any number of filenames and/or globs _(matched with [glob](http://npmjs.com/package/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`:

```cmd

budgie --language Python file.bg

```

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

```cmd

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`](./src/files.ts) and globber may be dependency-injected to override the defaults.

See [`cli.ts`](./src/cli/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`](./src/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](https://github.com/budgielang/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`](./src/preprocessing/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`](./src/conversions/convertFiles.ts) and [`convertFile.ts`](./src/conversions/convertFile).

#### `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`](./src/postprocessing/postprocess.ts).