benry-unixcmd 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73411bbc7b8bd31e455acdc67c7ef3d12df08ec3aa0bab56d631fcf12395b34b
-  data.tar.gz: 9fadc9355cf0006c83f48835c55197a4a9498a49b7e03f752af86eb951f03691
+  metadata.gz: 2ff5113d6cd99d3a50101096451203ade6c1f482ee0445fb92c54b7be806a92b
+  data.tar.gz: 130e7f320428382759597309256c39e9a50d0f8ab8e81d1854949f722f29b99d
 SHA512:
-  metadata.gz: 14462cad893ee39cc9e9ae27977b0a71c76fd2b142c2878c14f52f93f9471186a66d2ed895d8e62b53ea3565b5312cd49782d4b1e9c3a8fc0eafcc38c6c53197
-  data.tar.gz: 309f3813307636ff6adbe9b72f39fd01a4edf1bcf304b97ead6abd74787742795d7686fc40ededd3b97aa60816bea05dca3670a7e80a9999f6ae92b6acf126bb
+  metadata.gz: ffd7cc9973ff041b2478a5dbdb7c79ce93daf7214389bb8f5bf6caa561f181614cc68b085b0d2377bb11cc855108989bbc3e6dae7dfc34ff3c593586d45176a7
+  data.tar.gz: 4d9e61b09b80a5299327fc491605c92ea9f655b9737fac4d137b48590e61cf3e73c4e467cacbd5fde4cc1c9a50080fcc3349856e6f7ca4a1adfd7e19600bbd5e

data/MIT-LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 kuwata-lab.com
+Copyright (c) 2021 kwatch@gmail.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,9 +1,16 @@
-benry-unixcmd Gem README
-========================
+# Benry-UnixCmd
 
-($Release: 0.9.0 $)
+($Release: 0.9.1 $)
 
-benry-unixcmd gem implements popular UNIX commands, like FileUtils.
+
+## What's this?
+
+Benry-UnixCmd implements popular UNIX commands, like FileUtils,
+but much better than it.
+
+* Document: <https://kwatch.github.io/benry-ruby/benry-unixcmd.html>
+* GitHub: <https://github.com/kwatch/benry-ruby/tree/main/benry-unixcmd>
+* Changes: <https://github.com/kwatch/benry-ruby/blob/main/benry-unixcmd/CHANGES.md>
 
 Features compared to FileUtils:
 
@@ -19,53 +26,54 @@ Features compared to FileUtils:
 * provides `store` command which copies files recursively into target directory, keeping file path.
 * provides `atomic_symlink!` command which switches symlink atomically.
 
-(benry-unixcmd gem requires Ruby >= 2.3)
+(Benry-UnixCmd requires Ruby >= 2.3)
 
 
 
-Table of Contents
-=================
+### Table of Contents
 
 <!-- TOC -->
 
-* <a href="#install">Install</a>
-* <a href="#command-reference">Command Reference</a>
-  * <a href="#echo"><code>echo</code></a>
-  * <a href="#echoback"><code>echoback</code></a>
-  * <a href="#cp"><code>cp</code></a>
-  * <a href="#mv"><code>mv</code></a>
-  * <a href="#rm"><code>rm</code></a>
-  * <a href="#mkdir"><code>mkdir</code></a>
-  * <a href="#rmdir"><code>rmdir</code></a>
-  * <a href="#ln"><code>ln</code></a>
-  * <a href="#atomic_symlink"><code>atomic_symlink!</code></a>
-  * <a href="#touch"><code>touch</code></a>
-  * <a href="#chmod"><code>chmod</code></a>
-  * <a href="#chown"><code>chown</code></a>
-  * <a href="#pwd"><code>pwd</code></a>
-  * <a href="#store"><code>store</code></a>
-  * <a href="#sys"><code>sys</code></a>
-  * <a href="#ruby"><code>ruby</code></a>
-  * <a href="#capture2"><code>capture2</code></a>
-  * <a href="#capture2e"><code>capture2e</code></a>
-  * <a href="#capture3"><code>capture3</code></a>
-  * <a href="#zip"><code>zip</code></a>
-  * <a href="#unzip"><code>unzip</code></a>
-  * <a href="#time"><code>time</code></a>
-* <a href="#faq">FAQ</a>
-  * <a href="#why-mv-or-cp-requires-to-option">Why <code>mv</code> or <code>cp</code> requires <code>to:</code> option?</a>
-  * <a href="#how-to-use-in-rakefile">How to use in Rakefile?</a>
-  * <a href="#how-to-change-prompt-string">How to change prompt string?</a>
-  * <a href="#how-to-make-prompt-colored">How to make prompt colored?</a>
-  * <a href="#how-to-disable-command-echoback">How to disable command echoback?</a>
-* <a href="#license-and-copyright">License and Copyright</a>
+* [What's this?](#whats-this)
+* [Install](#install)
+* [Command Reference](#command-reference)
+  * [`echo`](#echo)
+  * [`echoback`](#echoback)
+  * [`cp`](#cp)
+  * [`mv`](#mv)
+  * [`rm`](#rm)
+  * [`mkdir`](#mkdir)
+  * [`rmdir`](#rmdir)
+  * [`ln`](#ln)
+  * [`atomic_symlink!`](#atomic_symlink)
+  * [`touch`](#touch)
+  * [`chmod`](#chmod)
+  * [`chown`](#chown)
+  * [`pwd`](#pwd)
+  * [`cd`](#cd)
+  * [`pushd`](#pushd)
+  * [`store`](#store)
+  * [`sys`](#sys)
+  * [`ruby`](#ruby)
+  * [`capture2`](#capture2)
+  * [`capture2e`](#capture2e)
+  * [`capture3`](#capture3)
+  * [`zip`](#zip)
+  * [`unzip`](#unzip)
+  * [`time`](#time)
+* [FAQ](#faq)
+  * [Why `mv` or `cp` requires `to:` option?](#why-mv-or-cp-requires-to-option)
+  * [How to use in Rakefile?](#how-to-use-in-rakefile)
+  * [How to change prompt string?](#how-to-change-prompt-string)
+  * [How to make prompt colored?](#how-to-make-prompt-colored)
+  * [How to disable command echoback?](#how-to-disable-command-echoback)
+* [License and Copyright](#license-and-copyright)
 
 <!-- /TOC -->
 
 
 
-Install
-=======
+## Install
 
 ```
 $ gem install benry-unixcmd
@@ -77,26 +85,25 @@ File: ex1.rb
 require 'benry/unixcmd'      # !!!!!
 include Benry::UnixCommand   # !!!!!
 
-output = capture2 "ls -al"   # run command and return output
-#print output
+output = capture2 "uname -srmp"   # run command and return output
+p output
 ```
 
 Result:
 
 ```terminal
-[localhost] ruby ex1.rb
-$ ls -al
+[localhost]$ ruby ex1.rb
+$ uname -srmp
+"Darwin 22.5.0 arm64 arm\n"
 ```
 
 
 
-Command Reference
-=================
+## Command Reference
 
 
 
-`echo`
-------
+### `echo`
 
 File: ex-echo1.rb
 
@@ -127,8 +134,7 @@ Options:
 
 
 
-`echoback`
-----------
+### `echoback`
 
 * `echoback "command"` prints `$ command` string into stdout.
 * `echoback "command"` indents command if in block of `cd` or `pushd`.
@@ -163,8 +169,7 @@ $ cd -
 
 
 
-`cp`
-----
+### `cp`
 
 * `cp "x", "y"` copies `x` to new file `y'. Fails when `y` already exists.
 * `cp! "x", "y"` is similar to above, but overwrites `y` even if it exists.
@@ -172,6 +177,7 @@ $ cd -
 * `cp "x", "y", "dir"` will be error! (use `to: "dir"` instead.)
 * Glob pattern such as `*`, `**`, `?`, and `{}` are available.
 * (See [FAQ](#faq) about `to:` keyword option.)
+* If you want to copy files with keeping directory structure, use `store` instead of `cp`.
 
 <!--
 File: ex-cp1.rb
@@ -202,8 +208,7 @@ Options:
 
 
 
-`mv`
-----
+### `mv`
 
 * `mv "x", "y"` renames `x` to `y`. Fails when `y` already exists.
 * `mv! "x", "y"` is similar to above, but overwrites `y` even if it exists.
@@ -241,8 +246,7 @@ Options:
 
 
 
-`rm`
-----
+### `rm`
 
 * `rm "x", "y"` removes file `x` and `y`.
 * `rm :r, "dir1"` removes directory recursively.
@@ -275,8 +279,7 @@ Options:
 
 
 
-`mkdir`
--------
+### `mkdir`
 
 * `mkdir "x", "y"` creates `x` and `y` directories.
 * `mkdir :p, "x/y/z"` creates `x/y/z` directory.
@@ -309,8 +312,7 @@ Options:
 
 
 
-`rmdir`
--------
+### `rmdir`
 
 * `rmdir "x", "y"` removed empty directores.
 * Raises error when directory not empty.
@@ -333,8 +335,7 @@ Options:
 
 
 
-`ln`
-----
+### `ln`
 
 * `ln "x", "y"` creates hard link.
 * `ln :s, "x", "y"` creates symbolic link. Error if `y` already exists.
@@ -361,14 +362,13 @@ ln! :s, "foo1.txt", "dir/foo1.txt"    # overwrites dir/foo1.txt if exists.
 ## create symbolic link into directory.
 ln :s, "foo1.txt", to: "dir"
 
-## error! use `to: "dir"` instead.
+## error! use ``to: "dir"`` instead.
 ln :s, "foo1.txt", "dir"
 ```
 
 
 
-`atomic_symlink!`
------------------
+### `atomic_symlink!`
 
 * `atomic_symlink! "x", "y"` creates symbolic link atomically.
 
@@ -395,8 +395,7 @@ Options:
 
 
 
-`touch`
--------
+### `touch`
 
 * `touch "x"` updates timestamp of file.
 * `touch :r, "reffile", "x"` uses timestamp of `reffile` instead current timestamp.
@@ -424,8 +423,7 @@ Options:
 
 
 
-`chmod`
--------
+### `chmod`
 
 * `chmod 0644, "x"` changes file permission.
 * `chmod :R, "a+r", "dir"` changes permissions recursively.
@@ -448,14 +446,13 @@ chmod :R, 0644, "dir"
 chmod :R, "a+r", "dir"
 ```
 
-Optionns:
+Options:
 
 * `chmod :R` -- changes permissions recursively.
 
 
 
-`chown`
--------
+### `chown`
 
 * `chown "user:group", "x", "y"` changes owner and group of files.
 * `chown "user", "x", "y"` changes owner of files.
@@ -476,14 +473,13 @@ chown "user1",        "file*.txt"     # change owner
 chown ":group1",      "file*.txt"     # change group
 ```
 
-Optionns:
+Options:
 
 * `chown :R` -- changes owner and/or group recursively.
 
 
 
-`pwd`
------
+### `pwd`
 
 * `pwd()` prints current working directory path.
 
@@ -496,7 +492,106 @@ require 'benry/unixcmd'
 include Benry::UnixCommand
 
 ## prints current working directory
-pwd()
+pwd()            #=> /home/yourname (for example)
+```
+
+Options:
+
+* (no options)
+
+
+
+### `cd`
+
+* `cd` changes current working directory.
+* If block given, `cd` invokes block just after changing current directory,
+  and back to previous directory automatically.
+* Within block argument, echoback indentation is increased.
+* `chdir` is an alias to `cd`.
+
+File: ex-cd1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## change directory, invoke block, and back to previous directory.
+pwd()           #=> /home/yourname (for example)
+cd "/tmp" do
+  pwd()         #=> /tmp
+end
+pwd()           #=> /home/yourname (for example)
+
+## just change directory
+cd "/tmp"
+pwd()           #=> /tmp
+```
+
+Result:
+
+```terminal
+[localhost]$ ruby ex-cd1.rb
+$ pwd
+/home/yourname
+$ cd /tmp
+$  pwd
+/tmp
+$ cd -
+$ pwd
+/home/yourname
+$ cd /tmp
+$ pwd
+/tmp
+```
+
+Options:
+
+* (no options)
+
+
+
+### `pushd`
+
+* `pushd` changes current directory, invokes block, and back to previous directory.
+* `pushd` requires block argument. `cd` also takes block argument but it is an optional.
+* Within block argument, echoback indentation is increased.
+
+File: ex-pushd1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## change directory, invoke block, and back to previous directory.
+pwd()           #=> /home/yourname (for example)
+pushd "/var" do
+  pwd()         #=> /var
+  pushd "tmp" do
+    pwd()       #=> /var/tmp
+  end
+  pwd()         #=> /var
+end
+pwd()           #=> /home/yourname (for example)
+```
+
+Result:
+
+```terminal
+[localhost]$ ruby ex-pushd1.rb
+$ pwd
+/home/yourname
+$ pushd /var
+$  pwd
+/var
+$  pushd tmp
+$   pwd
+/var/tmp
+$  popd    # back to /var
+$  pwd
+/var
+$ popd    # back to /home/yourname
+$ pwd
+/home/yourname
 ```
 
 Options:
@@ -505,8 +600,7 @@ Options:
 
 
 
-`store`
--------
+### `store`
 
 * `store "x", "y", to: "dir", ` copies files under `x` and `y` to `dir` keeping file path.
   For example, `x/foo/bar.rb` will be copied as `dir/x/foo/bar.rb`.
@@ -522,6 +616,9 @@ include Benry::UnixCommand
 
 ## copies files into builddir, keeping file path
 store "lib/**/*.rb", "test/**/*.rb", to: "builddir"
+
+## `store()` is similar to unix `tar` command.
+##     $ tar cf - lib/**/*.rb test/**/*.rb | (cd builddir; tar xf -)
 ```
 
 Options:
@@ -532,8 +629,7 @@ Options:
 
 
 
-`sys`
------
+### `sys`
 
 * `sys "ls -al"` runs `ls -al` command.
 * `sys` raises error when command failed.
@@ -550,7 +646,7 @@ File: ex-sys1.rb
 require 'benry/unixcmd'
 include Benry::UnixCommand
 
-## run `ls` command
+## run ``ls`` command
 sys "ls foo.txt"     # may raise error when command failed
 sys! "ls foo.txt"    # ignore error even when command filed
 
@@ -568,8 +664,7 @@ Options:
 
 
 
-`ruby`
-------
+### `ruby`
 
 * `ruby "...."` is almost same as `sys "ruby ...."`.
 * `RbConfig.ruby` is used as ruby command path.
@@ -595,13 +690,12 @@ Options:
 
 
 
-`capture2`
-----------
+### `capture2`
 
 * `capture2 "ls -al"` runs `ls -al` and returns output of the command.
 * `capture2 "cat -n", stdin_data: "A\nB\n"` run `cat -n` command and uses `"A\nB\n"` as stdin data.
-* `caputre "ls foo"` will raise error when command failed.
-* `caputre! "ls foo"` ignores error even when command failed, and returns command output and process status object.
+* `caputre2 "ls foo"` will raise error when command failed.
+* `caputre2! "ls foo"` ignores error even when command failed, and returns command output and process status object.
 * `capture2()` invokes `Popen3.capture2()` internally. All keyword arguments are available.
 
 <!--
@@ -613,9 +707,9 @@ require 'benry/unixcmd'
 include Benry::UnixCommand
 
 ## run command and get output of the command.
-output = capture2 "ls -l foo.txt"                  # error if command failed
-output, process_status = capture2 "ls -l foot.xt"  # ignore error even command failed
-puts process_status.exitstatus
+output = capture2 "ls -l foo.txt"                   # error if command failed
+output, process_status = capture2! "ls -l foot.xt"  # ignore error even command failed
+puts process_status.exitstatus      #=> 1
 
 ## run command with stdin data.
 input = "AA\nBB\nCC\n"
@@ -628,8 +722,7 @@ Options:
 
 
 
-`capture2e`
------------
+### `capture2e`
 
 * almost same as `capture2`, but output contains both stdout and stderr.
 
@@ -653,10 +746,9 @@ Options:
 
 
 
-`capture3`
-----------
+### `capture3`
 
-* almost same as `capture3`, but returns both stdout output and stderr output.
+* almost same as `capture2`, but returns both stdout output and stderr output.
 
 <!--
 File: ex-capture3.rb
@@ -682,8 +774,7 @@ Options:
 
 
 
-`zip`
------
+### `zip`
 
 * `zip "foo.zip", "file1", "file2"` creates new zip file `foo.zip`.
 * `zip :r, "foo.zip", "dir1"` adds files under `dir1` into zip file recursively.
@@ -692,7 +783,8 @@ Options:
 * `zip :'0'` doesn't compress files.
 * `zip :'1'` compress files in best speed.
 * `zip :'9'` compress files in best compression level.
-* `zip` and `zip!` requires `rubyzip` gem. You must install it by yourself.
+* `zip` and `zip!` loads `rubyzip` gem automatically. You must install it by yourself.
+* (`rubyzip` gem is necessary ONLY when `zip` or `zip!` command is invoked.)
 * `zip` and `zip!` doesn't support absolute path.
 
 <!--
@@ -722,8 +814,7 @@ Options:
 
 
 
-`unzip`
--------
+### `unzip`
 
 * `unzip "foo.zip"` extracts files in zip file into current directory.
 * `unzip :d, "dir1", "foo.zip"` extracts files under `dir1`.
@@ -731,7 +822,8 @@ Options:
 * `unzip "foo.zip"` will be error if extracting file already exists.
 * `unzip! "foo.zip"` will overwrite existing files.
 * `unzip "foo.txt", "file1", "file2"` extracts only `file1` and `file2`.
-* `zunip` and `unzip!` requires `rubyzip` gem. You must install it by yourself.
+* `zunip` and `unzip!` loads `rubyzip` gem automatically. You must install it by yourself.
+* (`rubyzip` gem is necessary ONLY when `unzip` or `unzip!` command is invoked.)
 * `unzip` and `unzip!` doesn't support absolute path.
 
 <!--
@@ -758,8 +850,7 @@ Options:
 
 
 
-`time`
-------
+### `time`
 
 * `time do ... end` invokes block and prints elapsed time into stderr.
 
@@ -770,7 +861,7 @@ require 'benry/unixcmd'
 include Benry::UnixCommand
 
 time do
-  sh "zip -qr9 dir1.zip dir1"
+  sys "zip -qr9 dir1.zip dir1"
 end
 ```
 
@@ -785,13 +876,11 @@ $ zip -qr9 dir1.zip dir1
 
 
 
-FAQ
-====
+## FAQ
 
 
 
-Why `mv` or `cp` requires `to:` option?
----------------------------------------
+### Why `mv` or `cp` requires `to:` option?
 
 Because UNIX command has bad interface which causes unexpected result.
 
@@ -819,8 +908,7 @@ In the same reason, `cp()` and `ln()` of Benry::UnixCommand also requires `to:`
 
 
 
-How to use in Rakefile?
------------------------
+### How to use in Rakefile?
 
 File: Rakefile
 
@@ -830,6 +918,7 @@ include Benry::UnixCommand   # !!!!!
 Rake::DSL.prepend Benry::UnixCommand  # !!!!!
 
 task :example do
+  ## invoke commands defined in Benry::UnixCommand, not in Rake nor fileutils.rb
   mkdir :p, "foo/bar/baz"
   here = Dir.pwd()
   pushd "foo/bar/baz" do
@@ -852,8 +941,7 @@ $ popd    # back to /home/yourname
 
 
 
-How to change prompt string?
-----------------------------
+### How to change prompt string?
 
 File: ex-prompt1.rb
 
@@ -865,7 +953,7 @@ def prompt()                  # !!!!!
   "myname@localhost>"         # !!!!!
 end                           # !!!!!
 
-sh "date"
+sys "date"
 ```
 
 Result:
@@ -878,8 +966,7 @@ Wed Jan 15 20:23:07 UTC 2021
 
 
 
-How to make prompt colored?
----------------------------
+### How to make prompt colored?
 
 <!--
 File: ex-prompt2.rb
@@ -900,13 +987,12 @@ def prompt()
   #"\e[0;37m#{s}\e[0m"    # white
 end
 
-sh "date"
+sys "date"
 ```
 
 
 
-How to disable command echoback?
---------------------------------
+### How to disable command echoback?
 
 File: ex-quiet1.rb
 
@@ -916,7 +1002,7 @@ include Benry::UnixCommand
 
 BENRY_ECHOBACK = false            # !!!!!
 
-sh "date"
+sys "date"
 ```
 
 Result:
@@ -928,9 +1014,8 @@ Wed Jan  1 22:29:55 UTC 2020      # no echoback, only output
 
 
 
-License and Copyright
-=====================
+## License and Copyright
 
 $License: MIT License $
 
-$Copyright: copyright(c) 2021 kuwata-lab.com all rights reserved $
+$Copyright: copyright(c) 2021 kwatch@gmail.com $