Shell Commands with os_process¶

Attention

The os_process type has been deprecated and this documentation has been superseded by the new sys_process type.

Lasso provides the ability to execute local processes or shell commands through the os_process type. This type allows local processes to be launched with an array of parameters and shell variables. Some processes will execute and return a result immediately. Other processes can be left open for interactive read/write operations. The os_process type enables Lasso users to do tasks such as execute AppleScripts, print PDF files, and filter data through external applications.

The os_process type works across all three platforms that Lasso supports. The UNIX underpinnings of OS X and Linux mean that those two operating systems can run many of the same commands and shell scripts. Windows presents a very different environment including DOS commands and batch files.

The os_process type is implemented in an LCAPI module that is loaded by default with Lasso Server, but not loaded when executing Lasso scripts from the command line. To load the LCAPI module for use with Lasso shell scripts, place the following line of code in your script:

// If LASSO9_MASTER_HOME is specified, find module there
// Otherwise, find it in the LASSO9_HOME path
lcapi_loadModule((sys_masterHomePath || sys_homePath) + '/LassoModules/OS_Process.' + sys_dll_ext)

For more information on writing shell scripts with Lasso, see the Command-Line Tools chapter.

Using os_process¶

type os_process¶: Deprecated since version 9.2: Use sys_process instead.

os_process(...): The os_process type allows a developer to create a new process on the machine and both read from and write data to it. The process is usually closed after the os_process object is destroyed, but can optionally be left running. The os_process type shares many of the same member methods and conventions as the file type.

os_process->open(command::string, arguments::trait_array=?, env::trait_array=?)¶: Opens a new process. The command string should consist of any path information required to find the executable and the executable’s name. An optional arguments array can be given. Any arguments are converted to strings and passed to the new process. An optional array of environment strings may also be passed in. Both of these optional arrays will be passed to the new process. The command string should be identical to what would have been typed on the command line with the Lasso site folder as the current working directory.

os_process->read(length::integer=?) → bytes¶: Reads the specified number of bytes from the process. Returns a bytes object. The number of bytes of data actually returned from this method may be less than the specified number, depending on the number of bytes that are actually available to read. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.

os_process->readError(length::integer=?) → bytes¶: Reads the specified number of bytes from standard error output for the process. Returns a bytes object. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.

os_process->readLine() → string¶: Reads data up until a carriage return or line feed. Returns a string object created by using the current encoding set for the instance.

os_process->readString(length::integer=?) → string¶: Reads the specified number of bytes from the process. Returns a string object created by using the current encoding set for the instance. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.

os_process->write(data::string)¶

os_process->write(data::bytes): Writes the data to the process. If the data is a string, the current encoding is used to convert the data before being written. If the data is a byte stream, the data is sent unaltered.

os_process->setEncoding(encoding::string)¶: Sets the encoding for the instance. The encoding controls how string data is written via os_process->write and how string data is returned via os_process->readString. By default, UTF-8 is used.

os_process->isOpen() → boolean¶: Returns “true” for as long as the process is running. After the process is terminated, it will return “false”.

os_process->detach()¶: Detaches the os_process object from the process. This will prevent the process from terminating when the os_process object is destroyed.

os_process->close()¶: Closes the connection to the process. This will cause the process to terminate unless it has previously been detached from the os_process object by calling os_process->detach.

os_process->closeWrite()¶: Closes the “write” portion of the connection to the process. This results in the process’s standard input file being closed.

OS X and Linux Examples¶

This section includes several examples of using os_process on OS X. Except for the AppleScript example, all of these examples should also work on Linux installations.

Echo¶

This example uses the /bin/echo command to simply echo the input back to STDOUT, which is then read by Lasso:

local(os) = os_process('/bin/echo', (: 'Hello World!'))
#os->read->encodeHtml
#os->close

// => Hello World!

List¶

This example uses the /bin/ls command to list the contents of a directory:

local(os) = os_process('/bin/ls', (: '/' + sys_homePath))
#os->readString->encodeHtml(true, false)
#os->close

// =>
// LassoApps
// LassoModules
// LassoStartup
// SQLiteDBs
// lasso.err.txt
// lasso.fastcgi.sock
// lasso.out.txt

Create File¶

This example uses the /usr/bin/tee command to create a file “test.txt” in the site folder. The code does not generate any output, it just creates the file.

local(os) = os_process
handle => {
   #os->close
}
#os->open('/usr/bin/tee', (: './test.txt'))
#os->write('This is a test\n')
#os->write('This is a test\n')
#os->close

Print¶

This example uses the /usr/bin/lpr command to print some text on the default printer. The result in this case is a page that contains the phrase “This is a test” at the top. This style of printing can output text data using the default font for the printer. The lpr command can also be used with some common file formats such as PDF files.

local(os) = os_process('/usr/bin/lpr')
#os->write('This is a test')
#os->write(bytes->import8Bits(4)&)
#os->closeWrite
#os->close

AppleScript¶

This example uses the /usr/bin/osascript command to run a simple AppleScript. AppleScript is a full scripting language that provides access to the system and running applications in OS X. The script shown below returns the current date and time:

local(os) = os_process('/usr/bin/osascript', (: '-'))
#os->write('return current date')
#os->closeWrite
#os->read->encodeHtml
#os->close

// => Tuesday, March 21, 2006 11:52:34 AM

Web Request¶

This example uses the /usr/bin/curl command to fetch a web page and return the results. The curl type or include_url method can be used for the same purpose. Only the first part of the output is shown.

local(os) = os_process('/usr/bin/curl', (: 'http://www.apple.com/'))
#os->read->encodeHtml
#os->close

// =>
// <!DOCTYPE html>
// <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
// <head>
//    <meta charset="utf-8" />
//    <meta name="Author" content="Apple Inc." />
// ... rest of response ...