=encoding utf8

=head1 NAME

Sidef::Types::Glob::Backtick - Shell command execution via backticks

=head1 DESCRIPTION

This class represents a backtick expression: a shell command that can be executed to capture its standard output as a String.

Writing a command between backticks in Sidef source code executes it immediately and evaluates to its output, exactly like backticks in Perl, Ruby, or a POSIX shell:

    var out = `ls -1`
    say out

Constructing a C<Backtick> object explicitly via C<Backtick(command)> is different: it just stores the command B<without running it>. You then call L</run> on it to actually execute the command and get its output.

    var cmd = Backtick("uname -a")
    var out = cmd.run

Only standard output is captured; standard error goes to the parent process's own STDERR unless redirected inside the command itself (e.g. C<`command 2>&1`>).

B<Note:> C<call> is B<not> the method that runs the command — it's an alias of the constructor (the same convention C<Backtick(...)> itself uses), so C<cmd.call> builds another (typically empty) Backtick object rather than executing anything. Use L</run> (or its aliases C<execute>/C<exec>) to actually run the command.

=head1 SYNOPSIS

    # Backtick literal syntax: executes immediately
    var user = `whoami`.trim
    say "Hello, #{user}!"

    var files = `ls`.lines

    # Explicit object, run later
    var cmd = Backtick("date")
    say cmd.run

    # Interpolation works the same as in strings
    var dir = "/tmp"
    var listing = `ls #{dir}`

=head1 INHERITS

Inherits methods from L<Sidef::Object::Object>.

=head1 CONSTRUCTION

=head2 new

    Backtick(command)

Creates a new Backtick object wrapping C<command>, without executing it.

    var cmd = Backtick("echo hello")
    say cmd.run     # "hello\n"

Aliases: I<call>

=cut

=head1 EXECUTION

=head2 run

    self.run

Executes the stored command through the system shell and returns its captured standard output as a String, including any trailing newline.

    var cmd = Backtick("uname -r")
    say cmd.run

The command's exit status is not returned; use L<Sidef::Sys::Sys/system> if you need it.

Aliases: I<execute>, I<exec>

=cut

=head1 LOW-LEVEL ACCESS

=head2 get_value

    self.get_value

Returns the raw command string that was stored at construction time, without running it and without any debug-style formatting.

    var cmd = Backtick("ls -la")
    say cmd.get_value      # "ls -la"

=cut

=head1 STRING REPRESENTATION

=head2 dump

    self.dump

Returns a debug-style string representation of the Backtick object, in the form C<Backtick("command")> — this is also what a Backtick object produces when stringified implicitly (e.g. via interpolation), and does B<not> execute the command.

    var cmd = Backtick("echo hello")
    say cmd.dump      # Backtick("echo hello")
    say "#{cmd}"       # Backtick("echo hello")

Aliases: I<to_s>, I<to_str>

=cut

=head1 EXAMPLES

=head2 Basic Usage

    var date = `date`
    say date

    var user = `whoami`.trim
    say "Current user: #{user}"

=head2 Deferred Execution

    var cmd = Backtick("df -h")
    say cmd.get_value    # see the command before running it: "df -h"
    say cmd.run          # now actually run it

=head2 Shell Pipelines and Redirection

    var count = `ps aux | wc -l`.trim
    say "Running processes: #{count}"

    var combined = `command_that_might_fail 2>&1`

=head2 Combining with Sys for Exit Status

    # Backticks only give you the output
    var output = `grep -q root /etc/passwd`

    # Use Sys.system if you need to check success/failure
    var status = Sys.system("grep", "-q", "root", "/etc/passwd")
    if ((status == 0)) {
        say "Found it"
    }

=head1 SECURITY CONSIDERATIONS

Backtick commands run through the system shell, so interpolating untrusted input into one is a command-injection risk:

    # DANGEROUS - do not do this with untrusted input
    var filename = Sys.readln
    var content = `cat #{filename}`     # a filename like "x; rm -rf /" is exploitable

Prefer file I/O (e.g. C<File(filename).read>) or C<Sys.system>/C<Sys.exec> with separate arguments (which bypass the shell) whenever the input isn't fully trusted.

=head1 SEE ALSO

L<Sidef::Sys::Sys>, L<Sidef::Types::String::String>, L<Sidef::Types::Glob::File>

=cut
