File Coverage

blib/lib/EBook/Ishmael/ShellQuote.pm
Criterion Covered Total %
statement 11 31 35.4
branch 0 6 0.0
condition n/a
subroutine 4 7 57.1
pod 3 3 100.0
total 18 47 38.3


line stmt bran cond sub pod time code
1             package EBook::Ishmael::ShellQuote;
2 17     17   393 use 5.016;
  17         68  
3             our $VERSION = '2.03';
4 17     17   106 use strict;
  17         34  
  17         500  
5 17     17   73 use warnings;
  17         49  
  17         1319  
6              
7 17     17   98 use Exporter 'import';
  17         37  
  17         8053  
8             our @EXPORT_OK = qw(shell_quote command_quote safe_qx);
9              
10             my $IS_WIN = $^O eq 'MSWin32';
11              
12             sub shell_quote {
13              
14 0     0 1   my ($str) = @_;
15              
16 0 0         if ($IS_WIN) {
17 0           $str =~ s/(\\*)(?="|\z)/$1$1/g;
18 0           $str =~ s/"/\\"/g;
19 0           return $str;
20             } else {
21 0           $str =~ s/([\$`"\\\n])/\\$1/g;
22 0           return qq{"$str"};
23             }
24              
25             }
26              
27             sub command_quote {
28              
29 0     0 1   my ($str) = @_;
30              
31 0 0         if ($IS_WIN) {
32 0           return shell_quote($str);
33             } else {
34 0           return shell_quote($str);
35             }
36              
37             }
38              
39             sub safe_qx {
40              
41 0     0 1   my ($program, @args) = @_;
42              
43             open my $fh, '-|', $program, @args
44 0 0         or do { $? = -1; return undef };
  0            
  0            
45 0           my $output = do { local $/; <$fh> };
  0            
  0            
46 0           close $fh;
47              
48 0           return $output;
49              
50             }
51              
52             1;
53              
54             =head1 NAME
55              
56             EBook::Ishmael::ShellQuote - Quote strings to be used in shell commands
57              
58             =head1 SYNOPSIS
59              
60             use EBook::Ishmael::ShellQuote qw(shell_quote);
61              
62             my $quote = shell_quote("$ <-- literally a dollar sign");
63             system "echo $quote";
64              
65             =head1 DESCRIPTION
66              
67             B is a module that provides the C
68             subroutine for quoting strings to be passed as arguments to a shell command.
69             This is a private module, consult the L manual for user
70             documentation.
71              
72             =head1 SUBROUTINES
73              
74             =over 4
75              
76             =item $quoted = shell_quote($string)
77              
78             Returns the double-quote-quotted version of the given string. Characters like
79             C<$>, C<`>, and C<"> will be escaped via a backslash, and the string will be
80             wrapped in double quotes.
81              
82             =item $quoted = command_quote($string)
83              
84             Returns quoted version of the given string suitable for using as shell command.
85              
86             =item $output = safe_qx($program, [ @args ])
87              
88             Runs the given C<$program> with arguments C<@args> using the C operator
89             and returns the output. The program name and arguments are quoted to prevent
90             unexpected word-splitting.
91              
92             =back
93              
94             =head1 AUTHOR
95              
96             Written by Samuel Young, Esamyoung12788@gmail.comE.
97              
98             This project's source can be found on its
99             L. Comments and pull
100             requests are welcome!
101              
102             =head1 COPYRIGHT
103              
104             Copyright (C) 2025-2026 Samuel Young
105              
106             This program is free software: you can redistribute it and/or modify
107             it under the terms of the GNU General Public License as published by
108             the Free Software Foundation, either version 3 of the License, or
109             (at your option) any later version.
110              
111             =head1 SEE ALSO
112              
113             L
114              
115             =cut