Getting Started

<< home

Once you've setup shotgun and instantiated the shell you can build any UI application around it that you wish. The simplest application is just a basic console app so that's what we'll setup here.

1. First set up a basic app to continually get a value from the user.

    var readline = require('readline');
   
    // Create interface that reads from console and outputs to console.
    var rl = readline.createInterface(process.stdin, process.stdout);
    rl.setPrompt("> ");
   
    rl.on('line', function (cmdStr) {
        console.log("Echo: %s", cmdStr);
        rl.prompt();
    }).on('close', process.exit);
   
    rl.prompt();
   

   So far we haven't done anything with shotgun. We've just put together a small app that continually asks the user for input and then prints that input to the console.

   > test
   Echo: test

2. Once you have a proper prompt application setup go ahead and install shotgun.

   npm install shotgun

3. Require shotgun and instantiate a shell.

    var readline = require('readline'),
        shotgun = require('shotgun'),
        shell = new shotgun.Shell();
   
    ...
   

4. Now that you have an instance of the shell you can begin to pass the user's value into the execute() function.

    var readline = require('readline'),
        shotgun = require('../index'),
        shell = new shotgun.Shell();
   
    // Create interface that reads from console and outputs to console.
    var rl = readline.createInterface(process.stdin, process.stdout);
    rl.setPrompt("> ");
   
    rl.on('line', function (cmdStr) {
        shell.execute(cmdStr, function (result) {
            rl.prompt();
        });
    }).on('close', process.exit);
   
    rl.prompt();
   

5. So far all we've done is pass the user's input on to shotgun along with a callback function that receives a result object, but we're not yet using it for anything. The result object passed to the callback from shotgun acts as a set of instructions. Depending on the command modules installed the result object could contain a wide variety of properties for you to consume in your application. There are a few default commands that come with shotgun: clear, exit, and help. 'clear' sets a property on the result called clearDisplay. 'exit' sets a property on the result called exit. 'help' writes a bunch of objects to a lines array on the result object. The lines array will always contain an array of objects, each object representing a single line of text. This is how shotgun stays UI agnostic because the app using shotgun can iterate over this array and display each line however it chooses to. Let's write some code to handle each of these situations:

    var readline = require('readline'),
        shotgun = require('../index'),
        shell = new shotgun.Shell();
   
    // Create interface that reads from console and outputs to console.
    var rl = readline.createInterface(process.stdin, process.stdout);
    rl.setPrompt("> ");
   
    rl.on('line', function (cmdStr) {
        shell.execute(cmdStr, function (result) {
            if (result.clearDisplay)
                console.log('\u001B[2J\u001B[0;0f');
            result.lines.forEach(function (line) {
                console[line.type](line.text);
            });
            result.exit ? rl.close() : rl.prompt();
        });
    }).on('close', process.exit);
   
    rl.prompt();
   

   In the above example we do several things with the result. First we check if clearDisplay is true. If it is then we clear the console display using ASCII control sequences. Next we check if exit is true and if it is then we skip asking the user for input again and let the application exit. Lastly we iterate over the lines array. Each line object has a type property and a text property. Obviously text contains the text for that line; by default type contains either 'log', 'warn', 'error', or 'debug' as it's value. You can do whatever you choose with that value but in this example I decided to map that to the functions with the same name on console, passing in the line text to be displayed.

6. We're almost done but there is one more piece we need to include. To maintain state across executions shotgun hands back a context object. result.context contains information that allows shotgun to know if it was prompting the user for a value, among other things. You are welcome to examine this object in more detail, but the only thing you are required to do with it is pass it back in on each execution. To do this in our sample app we will create a context variable in a higher scope and update that with the value from result.

    var readline = require('readline'),
        shotgun = require('../index'),
        shell = new shotgun.Shell(),
        context = {}; // Declare empty context object.
   
    // Create interface that reads from console and outputs to console.
    var rl = readline.createInterface(process.stdin, process.stdout);
    rl.setPrompt("> ");
   
    rl.on('line', function (cmdStr) {
        // Pass in the context object.
        shell.execute(cmdStr, context, function (result) {
            context = result.context; // Overwrite context object with updated context object from shotgun.
            if (result.clearDisplay)
                console.log('\u001B[2J\u001B[0;0f');
            result.lines.forEach(function (line) {
                console[line.type](line.text);
            });
            result.exit ? rl.close() : rl.prompt();
        });
    }).on('close', process.exit);
   
    rl.prompt();
   

   Now our context object is traveling in a loop as we execute commands. Every time we execute a command we save the context and pass it back in with the next execution. If you were to use shotgun in a web application you would either need to send it to the client and then have the client send it back with the next request, or you would need to store it in session.

That's it, you're done with your first little shotgun app!

<< home