Home

Welcome to the atom-python-run wiki!

How does the terminal module work?

How does the terminal module work?

What is terminal?

The whole premise for terminal is to allow cross-platform compatibility.

It's the "how" that lets the atom-python-run module work it's arbitrary "magic" on any system.

terminal determines the Operating System and creates the proper parameters based on expected values for that particular system.

Because each OS has it's own internal operations, they usually require specific calls that can be considered determinate. This means that those calls will always be the same.

Windows will always have cmd. Mac OS X will always use terminal.

Linux is a bit a more complicated and is a bit less determinate than either Windows or Mac OS X.

That's because Windows and Mac OS X only use a single Desktop Environment. Windows uses aero and Mac OS X uses quartz.

Each Desktop Environment has a default shell that allows a user to use basic input/output text based operations.

This I/O operation typically takes place through a tty instance. A tty instance is also known as a console, terminal, shell, and so on. It has a lot of names. For simplicity, I'll call it by it's most common name. A terminal.

How do I use terminal?

You only need the <Shell> and <SpawnWrapper> classes.

Create a <Shell> and pass the Shell.object or the Shell.get method call to <SpawnWrapper>.

> let shell = new Shell();

When shell is created, it automatically determines the OS and creates an object defining the parameters to pass to child_process.spawn in the background.

> let spawn = new(shell.object);

When spawn is created, it uses the shell.object to define the arguments that are passed to child_process.spawn when it is finally called.

Before we call spawn.tty, we need to define a special object required by the method call.

> let object = {
    'log': true,
    'cp': true,
    'options': {},
    'args': [
        'python',
        `${process.env.HOME}/Documents/Python/hello.py`
    ]
};

• log is a flag for toggling stdout and stderr to atoms console.log.
• cp is a flag for using the cp python module to run scripts.
• options is the object to be passed to child_process.spawn parameter.
• args is an array that contains the arguments to pass to the shell or to the cp script.

Then call spawn.tty and pass the object defining the parameters to be passed to child_process.spawn.

> spawn.tty(object);

spawn.tty returns a tty object called <ChildProcess>.

NOTE that If a relative path is required, you can pass the __dirname value to <Shell> when it's called.

NOTE that the path value passed to a new <Shell> instance should ALWAYS be a <String> and NOT an <Object>.

> let pathToCp = __dirname + '/../cp/main.py';
> let shell = new Shell(pathToCp);
> let spawn = new SpawnWrapper(shell.object);
// ...some more code...

NOTE that If you want to modify the properties, you can do so after the <SpawnWrapper> instance has been created.

> let pathToCp = __dirname + '/../cp/main.py';
> let shell = new Shell(pathToCp);
> let spawn = new SpawnWrapper(shell.object);
> spawn.object.shell = 'terminator';
> spawn.object.option = ['-x'];
// ...some more code...

Learning by example with terminal

'use strict';

const terminal = require('./terminal');

let object = {
    'log': true,
    'cp': true,
    'options': {}, // if the object is empty, `spawn.tty` will create a default object in its place
    'args': [
        'python',
        `${process.env.HOME}/Documents/Python/hello.py`
    ]
}

// if a path is missing, it will create a default absolute path in its place
// here, we pass a relative path for the `shell` instance instead
let shell = new terminal.Shell(`${__dirname}/../cp/main.py`);

let spawn = new terminal.SpawnWrapper(shell.object);

// before we call the `terminal` instance, we can customize it instead...
// note that the shell will have a default value, but we are changing it here
// the named terminal should be in the OS's PATH environment variable; it can also be a path if it isn't.
spawn.object.shell = 'terminator';
spawn.object.option = '-x';

// when we call the terminal instance, it will use terminator instead of the default value
let process = spawn.tty(object);

How does the cp module work?

How does the atom-python-run module work?