summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorTim Smith <tsmith84@gmail.com>2016-02-17 11:32:39 -0800
committerTim Smith <tsmith84@gmail.com>2016-02-17 11:32:39 -0800
commitbc7db8ef40b5aa729c5da139e61eb502e49fd780 (patch)
tree97d5a7a793e029d064d72417a31116696ebd2908 /README.md
parent523e68c9b3a387d8c3d2b7c4278ea4aab1e8b040 (diff)
downloadmixlib-shellout-bc7db8ef40b5aa729c5da139e61eb502e49fd780.tar.gz
Format markdown for better rendering
Also add the require to the example and fix an awkward sentence
Diffstat (limited to 'README.md')
-rw-r--r--README.md52
1 files changed, 32 insertions, 20 deletions
diff --git a/README.md b/README.md
index 2cfe5b0..51a0e81 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,66 @@
# Mixlib::ShellOut
-Provides a simplified interface to shelling out yet still collecting both
-standard out and standard error and providing full control over environment,
-working directory, uid, gid, etc.
+Provides a simplified interface to shelling out while still collecting both standard out and standard error and providing full control over environment, working directory, uid, gid, etc.
No means for passing input to the subprocess is provided.
## Example
Invoke find(1) to search for .rb files:
- find = Mixlib::ShellOut.new("find . -name '*.rb'")
- find.run_command
+```ruby
+ require 'mixlib/shellout'
+ find = Mixlib::ShellOut.new("find . -name '*.rb'")
+ find.run_command
+```
If all went well, the results are on `stdout`
- puts find.stdout
+```ruby
+ puts find.stdout
+```
`find(1)` prints diagnostic info to STDERR:
- puts "error messages" + find.stderr
+```ruby
+ puts "error messages" + find.stderr
+```
Raise an exception if it didn't exit with 0
- find.error!
+```ruby
+ find.error!
+```
Run a command as the `www` user with no extra ENV settings from `/tmp`
- cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
- cmd.run_command # etc.
+```ruby
+ cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
+ cmd.run_command # etc.
+```
## STDIN Example
Invoke crontab to edit user cron:
- # :input only supports simple strings
- crontab_lines = [ "* * * * * /bin/true", "* * * * * touch /tmp/here" ]
- crontab = Mixlib::ShellOut.new("crontab -l -u #{@new_resource.user}", :input => crontab_lines.join("\n"))
- crontab.run_command
+```ruby
+ # :input only supports simple strings
+ crontab_lines = [ "* * * * * /bin/true", "* * * * * touch /tmp/here" ]
+ crontab = Mixlib::ShellOut.new("crontab -l -u #{@new_resource.user}", :input => crontab_lines.join("\n"))
+ crontab.run_command
+```
## Windows Impersonation Example
Invoke "whoami.exe" to demonstrate running a command as another user:
- whoami = Mixlib::ShellOut.new("whoami.exe", :user => "username", :domain => "DOMAIN", :password => "password")
- whoami.run_command
+```ruby
+ whoami = Mixlib::ShellOut.new("whoami.exe", :user => "username", :domain => "DOMAIN", :password => "password")
+ whoami.run_command
+```
## Platform Support
-Mixlib::ShellOut does a standard fork/exec on Unix, and uses the Win32
-API on Windows. There is not currently support for JRuby.
+Mixlib::ShellOut does a standard fork/exec on Unix, and uses the Win32 API on Windows. There is not currently support for JRuby.
## License
Apache 2 Licensed. See LICENSE for full details.
## See Also
-* `Process.spawn` in Ruby 1.9
-* [https://github.com/rtomayko/posix-spawn](https://github.com/rtomayko/posix-spawn)
+- `Process.spawn` in Ruby 1.9
+- [https://github.com/rtomayko/posix-spawn](https://github.com/rtomayko/posix-spawn)