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

spectcl

v0.6.3

Published

Spawns and interacts with child processes using spawn / expect commands

Downloads

7

Readme

spectcl Build Status Coverage Status Dependencies NPM Follow Spectcl

spectcl (pronounced spectacle) is a node.js module for spawning child applications (such as ssh) and seamlessly controlling them using javascript callbacks. spectcl is based on the ideas of the Expect library by Don Libes and the pexpect library by Noah Spurrier.

Note that this module is under initial development. The API is subject to change until we reach the v1.0.0 Milestone.

Motivation

Node.js has good built in control for spawning child processes. nexpect built on those methods that allowed developers to easily pipe data to child processes and assert the expected response.

spectl stands on the shoulders of nexpect; one of this module's main goals is to more closely emulate the Expect extensions built into the Tcl language. Its concentration is to map the functionality and features of the Expect library as closely as possible, while adhering to an event-driven control flow.

Installation

  $ npm install --save spectcl

Usage

var Spectcl = require('spectcl')
  , session = new Spectcl()

session.spawn('node --interactive')
session.expect([
    '>', function(match, matched, cb){
        session.send('process.version\n')
        cb()
    }
], function(err){
    session.expect([
        '>', function(match, matched, cb){
            session.send('process.exit()\n')
            cb()
        }
    ], function(err){
        var version = session.expect_out.buffer.match(/(v[0-9]\.[0-9]+\.[0-9]+)/)[1]
        console.log('version is: %s', version)
    })
})

In the example above, we spawn a node interactive interpreter, have it output the value of process.version, and send process.exit(). We capture the results from the expect_out buffer, as well as the input string that was matched, and close the session, printing the version in the final callback.

Compare to this Tcl Expect block:

package require Expect

log_user 0

spawn node "--interactive"
expect ">" {
    exp_send "process.version\n"
}
expect ">" {
    exp_send "process.exit()\n"
}
regexp {(v[0-9]\.[0-9]+\.[0-9]+)} $expect_out(buffer) -> version
puts "version is: $version"

Getting Started

var session = new Spectcl()

A spectcl object exposes two main functions: spawn and expect. A Spectcl object is intended to only have one spawned child at a time. To operate concurrently on many sessions, you will need to spawn an object for each concurrent session.

spawn()

This function is used to spawn the child session that you'll be expecting on. Note that like Tcl Expect, by default your child will be wrapped in a pseudoterminal. Some sessions, like Telnet, are not sensitive to having a pty, and as such can be spawned without a pty if desired. You can do that like so:

session.spawn('echo', ['hello'], {}, {noPty: true})

The Spectcl object will emit exit when the child is complete, and error if there is an issue spawning the child.

expect()

This function will wait for data from the stream to match one of the expectations you specify. It takes an array and a final callback, structured like so:

session.expect([
    'hello', function(){
        // handle hello here
        cb()
    }
], function(){
    console.log('all done!')
})

The array needs to be even in length. The even indices are your "expectations". These can be of type String or Regexp, and are things that you want to match on. The odd indices will be the handler functions for the expectation that precedes it. In the example above, we are going to match on /hello/. When we do, the handler function is called.

The handler functions will be called with the match object (Either a String or the Match object from the RegExp test), the String or object that is a result of the successful match ("Matched"), and the final callback. For example, if the Match object is /he([a-z])lo/ and the input is "hello," the Matched object will be ["hello","l"]. If the Match object is a String, the Matched parameter is the same as the Match: e.g. 'hello', 'hello'.

Like Tcl Expect, expect() will wait until a match occurs, a specified period of time has elapsed, or EOF is seen. The timeout period can be specified when creating the Spectcl object by specifying a timeout property in the options object. The default period is 30s.

This specifies the timeout period, in ms:

var session = new Spectcl({timeout: 5000})

...and you can expect TIMEOUT or EOF like so:

session.expect([
    session.TIMEOUT, function(match, cb){
        cb(new Error('timeout'))
    },
    session.EOF, function(match, cb){
        cb(new Error('eof'))
    }
], function(err){
    if(err){ console.log(err) }
})

In the above sample, we are expecting to see either a TIMEOUT or an EOF, and can handle it appropriately. It is important to note that if you do not expect TIMEOUT or EOF and one occurs, the final callback will be called, with no Error:

session.expect([
    /foo/, function(match, matched, cb){
        // do things
        cb()
    }
], function(err){
    if(err){ console.log(err) }
})

In the above example, if the session is ended abruptly or if it is inactive for the specified period of time, then the final callback will be called directly, since no handler was specified for either case.

This design mirrors Tcl Expect's expect procedure, which returns immediately for these cases if they are not expected.

Examples

The examples directory contains spectcl code examples, as well as their Tcl Expect equivalents.

API Reference

The Spectcl API is documented on spectcl.github.io.

Tests

All tests are written with mocha:

  $ npm test

Authors

Greg Cochard and Ryan Milbourne

Originally forked from nodejitsu/nexpect by Elijah Insua, Marak Squires, and Charlie Robbins.