Shared code for running a command-line interface to the PiLisp programming language.

Designed originally for use with the pilisp and pilisp-native projects.

This is the pilisp_cli package on pub.dev.

Features

  • A cliMain function that is designed as a proxy for your program's main function:
    • Expects a PLEnv instance and your program's main arguments
    • Provides commands for:
      • Running a PiLisp REPL
      • Evaluating one-off expressions
      • Loading PiLisp files
  • Public repl and loadFile functions for starting a PiLisp REPL and loading a PiLisp file, respectively.

Getting started

$ dart pub add pilisp_cli

Then for your Dart program's entry-point, let's say bin/cli.dart:

import 'package:pilisp/pilisp.dart';
import 'package:pilisp_cli/pilisp_cli.dart' as pcli;

void main(List<String> args) {
  // piLispEnv is the default provided by the pilisp package
  pcli.cliMain(piLispEnv, args);
}

Now try running a REPL:

$ dart run bin/cli.dart
pl>

Usage

Dart Usage

As show in Getting Started, this is the simplest integration of the pilisp_cli package that proxies your main handling to the cliMain function:

import 'package:pilisp/pilisp.dart';
import 'package:pilisp_cli/pilisp_cli.dart' as pcli;

void main(List<String> args) {
  // piLispEnv is the default provided by the pilisp package
  pcli.cliMain(piLispEnv, args);
}

If you do not want to use cliMain for parsing arguments, etc., you can use this package's other functions directly.

To start a PiLisp REPL:

import 'package:pilisp/pilisp.dart';
import 'package:pilisp_cli/pilisp_cli.dart' as pcli;

void main(List<String> args) {
  // Start a REPL
  pcli.repl(piLispEnv);
}

To load a PiLisp file:

import 'package:pilisp/pilisp.dart';
import 'package:pilisp_cli/pilisp_cli.dart' as pcli;

void main(List<String> args) {
  // Load a file, pass args that become *command-line-args* in PiLisp
  pcli.loadFile(piLispEnv, '/path/to/a/file', args);
}

You can also change the piLispEnv or create your own PLEnv instance and pass that to these functions. The primary reason for doing so would be to change or add default language bindings. See this file in pilisp-native for a non-trivial example of extending the default PLEnv.

CLI Usage

We can use the main example found in this project to demonstrate how the CLI behaves:

$ dart run example/pilisp_cli_main_example.dart
pl>

$ dart run example/pilisp_cli_main_example.dart load --file example/example.pil a b c
Scripted, you passed in 6 command-line arguments: load, --file, example/example.pil, a, b, c

Additional information

Read up on PiLisp in these repositories:

License

Copyright © Daniel Gregoire 2023

Eclipse Public License - v 2.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

Exceptions

Project: cli_repl

The cli_repl code in this project has been copied and adapted from the cli_repl library by Jennifer Thakar, which is licensed under BSD 3-Clause "New" or "Revised" License.

Libraries

pilisp_cli
PiLisp CLI