/ 
Sidef-26.01
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 115 GitHub stars
/ Sidef::Types::Glob::Pipe

NAME

Sidef::Types::Glob::Pipe - Interface for creating and managing pipe handles

SYNOPSIS

# Create a pipe for reading command output
var pipe = Pipe("ls -la")
pipe.open_r(\var fh)
fh.each { |line|
    say line
}
fh.close

# Create a pipe for writing to a command
var pipe = Pipe("sort | uniq")
pipe.open_w(\var fh)
fh.say("banana")
fh.say("apple")
fh.say("banana")
fh.say("cherry")
fh.close

# Alternative: using open with mode
var pipe = Pipe("wc -l")
pipe.open('<', \var in_fh)   # read mode
# or
pipe.open('>', \var out_fh)  # write mode

DESCRIPTION

The Pipe class provides an interface for working with Unix-style pipes in Sidef. Pipes allow bidirectional communication between your Sidef program and external commands or processes, enabling data to flow from your program to a command (write mode) or from a command to your program (read mode).

This class wraps the underlying system pipe mechanisms and provides a clean, object-oriented interface for pipe operations.

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

new

Pipe.new(command)
Pipe(command)

Creates a new Pipe object for the specified command string.

Parameters:

  • command - The shell command to execute (String)

Returns: A new Pipe object

Example:

var pipe = Pipe("grep 'error' /var/log/syslog")
var pipe2 = Pipe.new("cat file.txt | sed 's/foo/bar/g'")

Note: The command is not executed until open, open_r, or open_w is called.

Aliases: call

command

pipe.command

Returns the command string associated with this Pipe object.

Returns: The command string (String)

Example:

var pipe = Pipe("ls -la")
say pipe.command          # prints: ls -la

open

pipe.open(mode, var_ref)

Opens the pipe in the specified mode and assigns the resulting filehandle to the variable reference provided.

Parameters:

  • mode - The opening mode: '<' for read, '>' for write (String)

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object

Example:

var pipe = Pipe("grep pattern file.txt")
pipe.open('<', \var fh)    # open for reading

var output_pipe = Pipe("sort")
output_pipe.open('>', \var out)  # open for writing

Note: The mode parameter follows Perl/Unix conventions: '<' or 'r' for read mode (input from command) '>' or 'w' for write mode (output to command)

open_r

pipe.open_r(var_ref)

Opens the pipe in read mode, allowing your program to read output from the command. This is equivalent to open('<', var_ref).

Parameters:

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object configured for reading

Example:

var pipe = Pipe("ps aux | grep sidef")
pipe.open_r(\var fh)

fh.each { |line|
    say "Process: #{line}"
}
fh.close

Use Case: Use this when you want to capture and process output from a shell command within your Sidef program.

Aliases: open_read

open_w

pipe.open_w(var_ref)

Opens the pipe in write mode, allowing your program to send data to the command's standard input. This is equivalent to open('', var_ref)>.

Parameters:

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object configured for writing

Example:

var pipe = Pipe("mail -s 'Report' user@example.com")
pipe.open_w(\var fh)

fh.say("This is the report content.")
fh.say("Generated at: #{Time.local}")
fh.close

Use Case: Use this when you want to pipe data from your Sidef program into another command for processing.

Aliases: open_write

to_s

pipe.to_s

Returns a string representation of the Pipe object, typically showing the command it encapsulates.

Returns: String representation of the Pipe object

Example:

var pipe = Pipe("echo 'hello'")
say pipe.to_s             # shows Pipe object info
say pipe.dump             # same output

Aliases: dump, to_str

USAGE EXAMPLES

Reading from a Pipe

# Execute a command and read its output line by line
var pipe = Pipe("find /etc -name '*.conf'")
pipe.open_r(\var fh)

var count = 0
fh.each { |line|
    say line.trim
    ++count
}
fh.close

say "Found #{count} configuration files"

Writing to a Pipe

# Send data to a command for processing
var data = %w(zebra apple mango banana kiwi)
var pipe = Pipe("sort -r")
pipe.open_w(\var fh)

data.each { |item|
    fh.say(item)
}
fh.close

Complex Pipeline

# Chain multiple commands together
var pipe = Pipe("ps aux | awk '{print $2, $11}' | sort -n")
pipe.open_r(\var fh)

say "PID\tCommand"
say "=" * 40
fh.each { |line|
    say line
}
fh.close

Error Handling

# Always check if pipe operations succeed
var pipe = Pipe("some-command")

try {
    pipe.open_r(\var fh)
    fh.each { |line| say line }
    fh.close
} catch {
    say "Error: #{_}"
}

COMPARISON WITH FILE OPERATIONS

While FileHandle deals with regular files on disk, Pipe works with commands and processes:

# File operations
var file = File("data.txt")
file.open_r(\var fh)
# reads from file

# Pipe operations  
var pipe = Pipe("cat data.txt")
pipe.open_r(\var fh)
# reads from command output

The key difference: Pipes execute commands and stream data to/from them, while FileHandles access data stored in files.

TECHNICAL NOTES

  • Pipes use the underlying operating system's pipe mechanism

  • Commands are executed through the shell, so shell metacharacters are interpreted

  • Pipe handles should be closed when finished to avoid resource leaks

  • The command doesn't execute until the pipe is opened

  • Write operations are buffered; close the handle to ensure all data is flushed

PLATFORM CONSIDERATIONS

Pipe functionality depends on the underlying operating system:

  • Unix/Linux/macOS: Full support for pipes with shell command execution

  • Windows: Limited pipe support; some shell features may not work as expected

SEE ALSO

AUTHOR

Daniel Șuteu (trizen)

LICENSE

This code is distributed under the terms of the Artistic License 2.0. For more details, see the full license text at: https://www.perlfoundation.org/artistic-license-20.html