TripeHound's fork of Vorpal

This Fork

This is essentially a personal-use fork of dhthree/vorpal. I wanted to add both command-line-driven and interactive-prompt facilities to a program I was writing and ended up looking at Vorpal. While it did a lot of what I wanted, there were some areas where I wanted it to behave differently (see below). I started by modifying the local node-modules version, but decided it would be better to push my changes to a fork of the original.

Feel free to download/clone/fork from this, or even submit pull-requests, but bear in mind:

• This is my first fork of a Git repository, so I may need to feel my way around a bit...

• As this is primarily for personal use, while I won't refuse to look at a pull-request, at this stage, I'll be mostly focusing on what I need to change.

• For the time being, I'll only be working under Windows. I am not yet able to check whether any of my changes (let alone any pull-requests!) work under Unix.

• I have not yet looked into getting any automatic tests running.

• All credit for Vorpal goes to dthree and other contributors to the original version; any blame for what I've done to it lies with me.

My Changes (not yet pushed)

FileCompleter

Vorpal allows for command/parameter auto-completion. I have added file-name completion. Because I work primarily under Windows, I wanted to mimic the Windows command-prompt behaviour whereby repeatedly pressing TAB will cycle through all filenames that match what has been entered so far. There is an option to use a Unix-like file-completion (show all files that match what has been entered, and allow the user to refine their choice) but it is not fully working at the moment.

Ability to Stay Interactive

Vorpal either allows you to specify a command on the command-line, in which case it executes it and exits, or to enter an interactive prompt where you can give multiple commands. I have added the ability to do both: run a command from the command-line then remain interactive. I would also like to provide the ability to enter multiple commands on the command-line (with or without staying interactive) but have not got to this yet.

Documentation on the above should follow once I get my local changes into this fork and ready for pushing.

Other Points

• At the time of writing, the main Vorpal repository hasn't been updated for around 11 months (August 2018) and dhthree has said they are not able to invest much time in maintaining it. Should any new commits be made to the original (and I notice them) I will probably try to pull them into my fork (providing they don't totally break my modifications :-) ), but make no promises at this stage.

• The current commit of Vorpal (and therefore of my fork) shows four issues from the npm audit command: [https://npmjs.com/advisories/1065] (twice), [https://npmjs.com/advisories/782], and [https://npmjs.com/advisories/577]. As far as I can see, these are caused by out-of-date copies of loadsh (one used directly by Vorpal, one indirectly by an old version of inquirer). Later versions of both loadsh and inquirer seem to have fixed all problems, but break "semver" with the rest of Vorpal.

  As the problems seem relatively minor (some lodash functions fail to prevent you accidentally modifying the prototype of Object; something you can deliberately do anyway) I will probably not look to update the affected modules unless or until I get the full testing suite running.

• The original Vorpal has a 2.0-ts branch where, seemingly, an attempt at conversion to TypeScript was started. However, this doesn't appear to have been updated any more recently than the master branch. I seem to remember seeing a comment either on an issue/pull-request/elsewhere that someone else had created their fork to convert Vorpal to TypeScript, but (a) I cannot find the link at the moment, and (b) from what I remember of it, they were only something like 58% through the process.

• I will try to organize things so that creating pull-request of my changes back to the original version of Vorpal should be possible, but creating a PR is not my top priority.

Regards, TripeHound.

---

Original README below

---

Vorpal

Conquer the command-line.

              (O)
              <M
   o          <M
  /| ......  /:M\------------------------------------------------,,,,,,
(O)[ vorpal ]::@+}==========================================------------>
  \| ^^^^^^  \:W/------------------------------------------------''''''
   o          <W
              <W
              (O)

Vorpal is Node's first framework for building interactive CLI applications. With a simple and powerful API, Vorpal opens the door to a new breed of rich, immersive CLI environments like cash and wat.

Notice

This is now an OPEN Open Source project. I am not able to invest a significant amount of time into maintaining Vorpal and so am looking for volunteers who would like to be active maintainers of the project. If you are interested, shoot me a note.

Contents

• Introduction
• Getting Started
• API
• Extensions
• FAQ
• License

Introduction

Inspired by and based on commander.js, Vorpal is a framework for building immersive CLI applications built on an interactive prompt provided by inquirer.js. Vorpal launches Node into an isolated CLI environment and provides a suite of API commands and functionality including:

• Simple, powerful command creation
• Supports optional, required and variadic arguments and options
• Piped commands
• Persistent command history
• Built-in help
• Built-in tabbed auto-completion
• Command-specific auto-completion
• Customizable prompts
• Extensive terminal control
• Custom event listeners
• And more

Vorpal supports community extensions, which empower it to do awesome things such as piping commands to less, importing commands live or supporting a built-in REPL.

Made with ❤️ by dthree.

Getting Started

Quick Start

Install vorpal into your project:

$ npm install vorpal --save

Create a .js file and add the following:

const vorpal = require('vorpal')();

vorpal
  .command('foo', 'Outputs "bar".')
  .action(function(args, callback) {
    this.log('bar');
    callback();
  });

vorpal
  .delimiter('myapp$')
  .show();

This creates an instance of Vorpal, adds a command which logs "bar", sets the prompt delimiter to say "myapp$", and shows the prompt.

Run your project file. Your Node app has become a CLI:

$ node server.js
myapp~$

Try out your "foo" command.

myapp~$ foo
bar
myapp~$

Now type "help" to see Vorpal's built in commands in addition to "foo":

myapp~$ help

  Commands

    help [command]    Provides help for a given command.
    exit [options]    Exits instance of Vorpal.
    foo               Outputs "bar".

myapp~$

There's the basics. Once you get the hang of it, follow this tutorial or read on to learn what else Vorpal can do.

Community

Questions? Use the vorpal.js StackOverflow tag for fast answers that help others, or jump into chat on Gitter.

• Stack Overflow
• Gitter Chat
• Vorpal extensions
• Projects made with Vorpal
• Follow @vorpaljs

API

Command

• vorpal.command
• command.description
• command.alias
• command.parse
• command.option
• command.hidden
• command.remove
• command.help
• command.autocomplete
• command.action
• command.cancel

Mode

• vorpal.mode
• mode.delimiter
• mode.init
• mode.action

Catch

• vorpal.catch

CommandInstance

• commandInstance.log
• commandInstance.prompt
• commandInstance.delimiter

UI

• ui.delimiter
• ui.input
• ui.imprint
• ui.submit
• ui.cancel
• ui.imprint
• ui.redraw
• ui.redraw.clear
• ui.redraw.done

Vorpal

• .parse
• .delimiter
• .show
• .find
• .exec
• .execSync
• .log
• .history
• .localStorage
• .help
• .pipe
• .use

Events

Extensions

You can build your own Vorpal commands and extensions.

• List of awesome extensions
• Building your own extension

FAQ

• What is an "immersive CLI app?"
• Wasn't this called Vantage?

Why Vorpal?

One, two! One, two! and through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.

Lewis Carroll, Jabberwocky

Life Goals:

• Build a popular framework based on the Jabberwocky poem.

License

MIT © David Caccavella