npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

operetta

v1.0.2

Published

The Node Option Parser That Sings!

Downloads

32,103

Readme

Plot Summary

Options

All options are arguments, but not all arguments are options.

$ nurl -I --insecure https://topsyturvey.onion/mikado.mkv

In the example above, the program nurl has three arguments, two of which are options. Options are arguments that are one letter long and start with a dash (-), these are "short options," or many letters long and start with a double dash (--), these are long options. Arguments that are not options are called "positional" arguments, because they have no name, so can only be referred to by their position following the command.

Operetta would parse the above example as follows:

For the program to receive these values, it calls the start function with a callback.

Simple, right? And quite enough for many programs. But that is not all, oh no that is not all!

Parameters

All parameters are options but not all options are parameters.

$ nysql --database secret_database --host=control.onion -usmart -p Iheart99

Sometimes options take a value. We call these Parameters.

The above shows the four valid forms to set values. Without any further instruction, Operetta would parse the above as follows:

Uhgg. That's probably not what we want. It got --host right, because that is the most unambiguous form for a parameter to take, a long option connected to a value by an equal sign. However the rest, what a mess! Since it doesn't know that --database and -p are parameters, it treats "secret_database" and "Iheart99" as positional arguments, and since short options can be chained together, Operetta thinks "usmart" is a chain of 6 options. We're going to have to give operetta more information to handle these correctly.

We use the parameters function to tell Operetta some things about our parameters, first we pass a list of options, i.e. ['-D','--database'], this gives the long and short form of the option, then we give a description.

Now, we get the follow values:

Much better! Note that the key for the value is always the first item in the options list passed, so -D is present, even though --database was used.

Help

What's more is now that we have descriptions, operetta will automatically bind the options -h and --help to show these descriptions as help.

Nifty, huh? But what about plain old options? We may want to give these descriptions too. For example, in our earlier nurl example, we may want to provide descriptions for -I and --insecure. We can use the options function for this.

If you really insist, you can can override -h and --help using either the options or parameters function, you can then then get the help output by calling the usage function, either with or without a callback.

We can add a banner above line that says "Usage."

Now we get the following Help:

There you go! Now you can add options and parameters to your program and have it display nice help with the descriptions. That's all you need right? But that is not all operetta can do! Oh no, that is not all!

Events

Sometimes you don't just want all the options parsed and dumped to a single callback as a values object, but you wold rather have an event triggered for each option. Here is where Operetta Sings!

The operetta object is an EventEmitter, so you can bind events with the on option.

Since -k is just an option, value will always be true when this event is called, in the case of a parameter, value will be the value passed or null if none was passed.

While using the on function works, the preferred way to set a callback is to pass it as the third argument to either the options or parameters function.

So there you have it, Options, Parameters, Help and Events. Surely that's the end of this interminable readme file? No! That's not all. And stop calling me Shirley.

Subcommands

Sometimes programs have different commands, each with their own options, i.e.

If the program nit has many subcommands, i.e. clone, commit, push then each of these could have their own options and help. Operetta has a command function that allows you to define these and get a new instance of operetta for each command.

Now, if you called help without a subcommand:

$ nit -h

You get a list of the subcommands.

However, if you call help on commit:

$ nit commit --help

You get the descriptions of the options defined for commit.

And yes, if you really want, subcommand can have subcommands:

Now you could do:

$ nit submodule add http://nitorious.onion/nitorious.nit

Coda

So, options, parameters, help, events and subcommands. Shirley, you're thinking operetta must be some big, baroque, bloated, blob of blubbery JavaScript! Well, here's what SLOCcount has to say:

That's right, small and cheap. So far it's only got One Hundred and Seven Lines of Code. So get it while it's small, before I add thousands of lines to support such must-have features as sending and receiving email and impersonating a teenager in IRC channels.

And yes, I called you Shirley.