cli_tools 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97ca4006c9d4aad3f468fee6c21a6e7f7ed92939
-  data.tar.gz: bd7c470b4d297335eb7bc463dd87448f4f2ac34e
+  metadata.gz: 4bcdce3da1ebb50323e0a4d23d8215aab5cf1036
+  data.tar.gz: 3967d3fb79f35e92060e6ae0b3f2beddf18d092f
 SHA512:
-  metadata.gz: ed93a838a7f58d8313baa67d84bb430c0202f23b353b2fbce7238e5475cdd0bb326b1fcffe069a38dd57a6c33794dc4059564ea88d3da15a0c523e30566a2a43
-  data.tar.gz: 058bc0e697e24561a7d9228021e4dd564e0768d88f628ce2a7777e9d371a6d07e7c8d8b0c7ed4b592713c8431b92b398461859a7a7674cf5883259f53af9775e
+  metadata.gz: ec2399a559e4486599225e35e998ef22363389a44970c316d920eef1dbc0c638aa5f1deb8a6b20d1d43580f249117b4f2351ff768e0ecc35a67020bdf3f79aa3
+  data.tar.gz: a55b1636c974b0f289af86e20be1bdf3ba164f602a2b4548eebd30333156ee938f30403a042fb325754a507d004e9c94bb4102e8d7d48fcf0a20aa11e887bc95

data/README.md

@@ -1,6 +1,16 @@
-# Tools for CLI application
+# Tools for a CLI application
 
-A collection of helper methods for ruby CLI application.
+A collection of helper methods for ruby CLI applications.
+
+- `sh` — shell command execution, with output capturing
+- `putr` — like `puts`, but erases current line and does not advance to a new line, invaluable for displaying things like progress bar
+- `esc_...` — ANSI colors for your output
+- `kb_getkey` — get the f.. key pressed in a non-blocking way
+- and other little friends
+
+## Requirements
+
+You probably need a Unix based system to find this gem useful. The gem methods are tested and working on Mac OS X and Linux systems, and it is not guaranteed to work on Windows (especially because the console input/output is done the unix way).
 
 ## Installation
 
@@ -18,21 +28,35 @@ Or install it yourself as:
 
 ## Usage
 
+Keep all helper methods in CliTools namespace:
 ```ruby
 require 'cli_tools'
-include CliTools
 
-puts esc_green("Hello")+' world!' # outputs 'Hello world!' where 'Hello' is painted green
+puts CliTools.esc_green("Hello")+' world!' # outputs 'Hello world!' where 'Hello' is painted green
 ```
 
-OR: all the methods automatically included into Kernel:
+OR: have all the methods automatically included:
 
 ```ruby
-require 'cli_tools/include'
+require 'cli_tools/include' # equivalent to:
+                            # require 'cli_tools'
+                            # include CliTools
 
 puts esc_green("Hello")+' world!'
 ```
 
+### Try it out
+```
+cd examples/
+ruby ex-ansi.rb
+```
+
+
+## TODO
+- add more specs
+- write comprehensive docs
+
+
 ## Contributing
 
 1. Fork it

data/examples/ex-ansi.rb

@@ -0,0 +1,10 @@
+require 'cli_tools/include'
+
+puts "this is ANSI output:"
+putr "one"
+sleep 1
+putr "two"
+sleep 1
+putr "three"
+sleep 1
+puts " and done"

data/examples/ex-block.rb

@@ -0,0 +1,27 @@
+require 'cli_tools/include'
+
+out = ''
+out_nest = ''
+sh_capture_output( out ) do
+  sh "ls -la"
+  puts ""
+  puts "captured inside:"
+  out1 = ''
+  sh "ruby ex-ok.rb", true, out1
+  puts "out1: #{out1}"
+
+  puts "nested block:"
+  sh_capture_output( out_nest ) do
+    sh "ruby ex-err.rb" rescue puts esc_red "sh raised an exception, recovered"
+  end
+end
+
+
+puts
+puts "Globally captured output:"
+puts out
+
+puts
+puts "Nested captured output:"
+puts out_nest
+

data/examples/ex-err.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require 'cli_tools/include'
+
+1.upto(10) do |i|
+  puts "this is stdout output #{i}"
+  STDOUT.flush
+  STDERR.puts esc_red "this is stderr output #{i}"
+  STDERR.flush
+  sleep 1
+end
+exit -1

data/examples/ex-kb-getkey.rb

@@ -0,0 +1,11 @@
+require 'cli_tools/include'
+
+count = 0
+puts "Press any key when you've had enough"
+while (key = kb_getkey).nil?
+  count += 1
+  putr "#{count} #{esc_green 'bottles'} hanging on the wall... "
+  sleep 1
+end
+puts # advances to a new line
+puts "pressed key code is: #{key[0].ord}"

data/examples/ex-ok.rb

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+puts "this is stdout output"

data/examples/ex-putr.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'cli_tools/include'
+
+COUNT = 10
+puts "hello, putr test"
+1.upto(COUNT) do |i|
+  putr "#{i} of #{COUNT}"
+  STDOUT.flush
+  sleep 1
+end
+puts " done"

data/examples/ex-puts-vs-putr.rb

@@ -0,0 +1,7 @@
+require 'cli_tools/include'
+
+puts "hello from puts"
+
+putr "hello from putr"
+
+puts "..and the end"

data/examples/ex-raise.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+puts "hello! 1"
+STDOUT.flush
+sleep 2
+puts "hello! 2"
+STDOUT.flush
+sleep 2
+puts "hello! 3"
+STDOUT.flush
+sleep 2
+raise "This is sample exception"

data/examples/ex-sh.rb

@@ -0,0 +1,25 @@
+require 'cli_tools/include'
+
+if ARGV.size == 0
+  puts "Usage: #{__FILE__} <command> [arg1] [arg2] ..."
+  puts "Examples:"
+  puts "  #{__FILE__} ruby test-err.rb"
+  puts "  #{__FILE__} ruby test-putr.rb"
+  exit -1
+end
+
+out = ''
+captured = ''
+begin
+  sh ARGV.join(' '), true, captured do |char|
+    putc char
+  end
+  puts esc_green "OK"
+  puts "captured output (captured):"
+  puts captured
+  puts
+rescue ShellExecutionError => e
+  puts esc_red "ERROR: #{e}, status:#{e.status}, output:"
+  puts e.output
+  puts
+end

data/lib/cli_tools/version.rb

@@ -1,3 +1,3 @@
 module CliTools
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cli_tools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Alex Kukushkin
@@ -52,6 +52,15 @@ files:
 - README.md
 - Rakefile
 - cli_tools.gemspec
+- examples/ex-ansi.rb
+- examples/ex-block.rb
+- examples/ex-err.rb
+- examples/ex-kb-getkey.rb
+- examples/ex-ok.rb
+- examples/ex-putr.rb
+- examples/ex-puts-vs-putr.rb
+- examples/ex-raise.rb
+- examples/ex-sh.rb
 - lib/cli_tools.rb
 - lib/cli_tools/console.rb
 - lib/cli_tools/include.rb