tty-file 0.6.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 12c95f3b7bd457b553e6592d5a9c74cf3dff2d9a
-  data.tar.gz: adc293eda605ad68b5f45acff1d37c2849050922
+SHA256:
+  metadata.gz: e1d9e2c1d0c438b74128707623835e44da4ec23dcdebfe0ba88afb5284c730a7
+  data.tar.gz: 63c7b68f347b2199502240cbdbfdf20264f90a95ece1ea50f60a78d2c3a6c73f
 SHA512:
-  metadata.gz: 3a86b5c70306a91576514af459e7fd3a458858732352cbe68683afa27786576abdc018c4388e4aa00105e85a23de1d0dcd84f02ea715377ef86e7bbee2ff2197
-  data.tar.gz: a484156abd85e985118467b7cfd087c9672882e763fe0a84867b2543d08c4aa2000fc7640d205ffd6c2201fd18d0a79bcc0f83bf128165668ae4d7d06ca52e5c
+  metadata.gz: 0ab6abf98fa2bcdb58f7f0eb2d3518e1184607863fedfeb2a1de34b21eeb876d3e7c9ce2eb0c48198b98dfaae7d281c49447a7dfe872a48e19d07493fdb0c020
+  data.tar.gz: 9925c5f71b7a0c8f9afb369abb6b83df9c6700d87884a3b9e4ce2dd77c02c2e0d9848803979ac599e431c0f282419ba2be72ea241de10479930989bc7073ed57

data/CHANGELOG.md

@@ -1,12 +1,68 @@
 # Change log
 
+## [v0.10.0] - 2020-07-27
+
+### Added
+* Add diff option to file conflict menu to show file contents differences
+* Add :header option to #diff to show two-line header for compared files
+* Add git-like hunk coloring when displaying diff lines in unified format
+
+### Changed
+* Change to only use keyword arguments in all methods
+* Change #tail_file to accept :lines as keyword parameter
+* Change to update tty-prompt & pastel dependencies
+* Change prompt to be quiet and provide no output after selection
+* Change #diff_files to stop raising on binary or large files
+
+## [v0.9.0] - 2020-04-28
+
+### Changed
+* Change #chmod custom permission implementation for built-in FileUtils one
+* Change to update tty-prompt dependency
+* Change gemspec to include metadata and stop loading test artefacts
+
+### Fixed
+* Fix Ruby 2.7 hash to keywords conversion warnings
+
+## [v0.8.0] - 2019-07-25
+
+### Added
+* Add #read_to_char for reading file content limited by bytes until a valid char
+
+### Fixed
+* Fix #binary? to correctly identify large UTF-8 files as non-binary
+
+## [v0.7.1] - 2019-05-06
+
+### Changed
+* Change all methods to accept Pathname instances as argument by Chris Hoffman(@yarmiganosca)
+
+### Fixed
+* Fix Ruby 2.6.0 ERB#new arguments deprecation warnings
+* Fix #replace_in_file to handle character encoding
+
+## [v0.7.0] - 2018-12-17
+
+### Added
+* Add :secure option to #remove_file call
+* Add #safe_append_to_file, #safe_prepend_to_file, #safe_inject_into_file
+
+### Changed
+* Change #replace_in_file, #append_to_file, #prepend_to_file, and #inject_into_file to perform operation unsafely without checking prior content
+* Change to load gemspec files directly
+* Change to update tty-prompt
+* Change to freeze strings
+* Change to relax tty-prompt & diff-lcs version constraints
+
+### Fixed
+* Fixed windows tests
+
 ## [v0.6.0] - 2018-05-21
 
 ### Changed
 * Change identical files conflict message from blue to cyan for readability
 * Change replace_in_file to stop raising error and allow forcing file overwrite
-* Change replace_in_file, inject_into_file, prepend_to_file, append_to_file to return true
-  when operation is performed successfully, false otherwise
+* Change replace_in_file, inject_into_file, prepend_to_file, append_to_file to return true when operation is performed successfully, false otherwise
 * Update tty-prompt dependency
 * Change download_file to preserve query parameters
 
@@ -64,6 +120,11 @@
 
 * Initial implementation and release
 
+[v0.10.0]: https://github.com/piotrmurach/tty-file/compare/v0.9.0...v0.10.0
+[v0.9.0]: https://github.com/piotrmurach/tty-file/compare/v0.8.0...v0.9.0
+[v0.8.0]: https://github.com/piotrmurach/tty-file/compare/v0.7.1...v0.8.0
+[v0.7.1]: https://github.com/piotrmurach/tty-file/compare/v0.7.0...v0.7.1
+[v0.7.0]: https://github.com/piotrmurach/tty-file/compare/v0.6.0...v0.7.0
 [v0.6.0]: https://github.com/piotrmurach/tty-file/compare/v0.5.0...v0.6.0
 [v0.5.0]: https://github.com/piotrmurach/tty-file/compare/v0.4.0...v0.5.0
 [v0.4.0]: https://github.com/piotrmurach/tty-file/compare/v0.3.0...v0.4.0

data/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+</div>
+
 # TTY::File [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-file.svg)][gem]
@@ -26,7 +30,7 @@ Though Ruby's `File` and `FileUtils` libraries provide very robust apis for deal
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-file'
+gem "tty-file"
 ```
 
 And then execute:
@@ -48,11 +52,11 @@ Or install it yourself as:
   * [2.5. create_file](#25-create_file)
   * [2.6. copy_dir](#26-copy_dir)
   * [2.7. create_dir](#27-create_dir)
-  * [2.8. diff](#28-diff)
+  * [2.8. diff_files](#28-diff_files)
   * [2.9. download_file](#29-download_file)
   * [2.10. inject_into_file](#210-inject_into_file)
   * [2.11. replace_in_file](#211-replace_in_file)
-  * [2.12. append_to_file](#212-apend_to_file)
+  * [2.12. append_to_file](#212-append_to_file)
   * [2.13. prepend_to_file](#213-prepend_to_file)
   * [2.14. remove_file](#214-remove_file)
   * [2.15. tail_file](#215-tail_file)
@@ -60,7 +64,7 @@ Or install it yourself as:
 ## 1. Usage
 
 ```ruby
-TTY::File.replace_in_file('Gemfile', /gem 'rails'/, "gem 'hanami'")
+TTY::File.replace_in_file("Gemfile", /gem 'rails'/, "gem 'hanami'")
 ```
 
 ## 2. Interface
@@ -74,7 +78,7 @@ If you wish to silence verbose output use `verbose: false`. Similarly if you wis
 To check whether a file is a binary file, i.e. image, executable etc. do:
 
 ```ruby
-TTY::File.binary?('image.png') # => true
+TTY::File.binary?("image.png") # => true
 ```
 
 ### 2.2. checksum_file
@@ -89,7 +93,7 @@ Among the supported message digest algorithms are:
 For example, to create a digest for a string using `SHA1` do:
 
 ```ruby
-TTY::File.checksum_file("Some content\nThe end", 'sha1')
+TTY::File.checksum_file("Some content\nThe end", "sha1")
 # => "289388f187404135e6c15b21460442cf867180dd"
 ```
 
@@ -98,19 +102,19 @@ TTY::File.checksum_file("Some content\nThe end", 'sha1')
 To change file modes use `chmod`, like so:
 
 ```ruby
-TTY::File.chmod('filename.rb', 0777)
+TTY::File.chmod("filename.rb", 0777)
 ```
 
 There are a number of constants available to represent common mode bits such as `TTY::File::U_R` and `TTY::File::O_X`, and they can be used as follows:
 
 ```ruby
-TTY::File.chmod('filename.rb', TTY::File::U_R | TTY::File::O_X)
+TTY::File.chmod("filename.rb", TTY::File::U_R | TTY::File::O_X)
 ```
 
 Apart from traditional octal number definition for file permissions, you can use the more convenient permission notation used by the Unix `chmod` command:
 
 ```ruby
-TTY::File.chmod('filename.rb', 'u=wrx,g+x')
+TTY::File.chmod("filename.rb", "u=wrx,g+x")
 ```
 
 The `u`, `g`, and `o` specify the user, group, and other parts of the mode bits. The `a` symbol is equivalent to `ugo`.
@@ -120,13 +124,13 @@ The `u`, `g`, and `o` specify the user, group, and other parts of the mode bits.
 Copies a file's contents from a relative source to a relative destination.
 
 ```ruby
-TTY::File.copy_file 'Gemfile', 'Gemfile.bak'
+TTY::File.copy_file "Gemfile", "Gemfile.bak"
 ```
 
 If you provide a block then the file content is yielded:
 
 ```ruby
-TTY::File.copy_file('Gemfile', 'app/Gemfile') do |content|
+TTY::File.copy_file("Gemfile", "app/Gemfile") do |content|
   "https://rubygems.org\n" + content
 end
 ```
@@ -135,25 +139,25 @@ If the source file is an `ERB` template then you can provide a `:context` in whi
 
 ```ruby
 variables = OpenStruct.new
-variables[:foo] = 'bar'
+variables[:foo] = "bar"
 
-TTY::File.copy_file('templates/application.html.erb', context: variables)
+TTY::File.copy_file("templates/application.html.erb", context: variables)
 ```
 
-You can also specify the template name surrounding any dynamic variables with `%` to be evaluted:
+You can also specify the template name surrounding any dynamic variables with `%` to be evaluated:
 
 ```ruby
 variables = OpenStruct.new
-variables[:file_name] = 'foo'
+variables[:file_name] = "foo"
 
-TTY::File.copy_file('templates/%file_name%.rb', context: variables)
+TTY::File.copy_file("templates/%file_name%.rb", context: variables)
 # => Creates templates/foo.rb
 ```
 
 If the destination is a directory, then copies source inside that directory.
 
 ```ruby
-TTY::File.copy_file 'docs/README.md', 'app'
+TTY::File.copy_file "docs/README.md", "app"
 ```
 
 If the destination file already exists, a prompt menu will be displayed to enquire about action:
@@ -161,24 +165,50 @@ If the destination file already exists, a prompt menu will be displayed to enqui
 If you wish to preserve original owner, group, permission and modified time use `:preserve` option:
 
 ```ruby
-TTY::File.copy_file 'docs/README.md', 'app', preserve: true
+TTY::File.copy_file "docs/README.md", "app", preserve: true
 ```
 
 ### 2.5. create_file
 
-To create a file at a given destination with the given content use `create_file`:
+To create a file at a given destination with some content use `create_file`:
 
 ```ruby
-TTY::File.create_file 'docs/README.md', '## Title header'
+TTY::File.create_file "file-a/README.md", content
+```
+
+On collision with already existing file, a menu gets displayed:
+
+```
+   collision  examples/file-a
+Overwrite examples/file-a? (enter "h" for help) [y,d,n,q,h]
 ```
 
-On collision with already existing file, a menu is displayed:
+The `d` option allows to compare the changes:
+
+```
+--- a/examples/file-a
++++ b/examples/file-a
+@@ -1,8 +1,9 @@
+ aaaaa
+ bbbbb
+-ccccc
++xxxxx
++
+ ddddd
+ eeeee
+ fffff
+-ggggg
++yyyyy
+Overwrite examples/file-a? (enter "h" for help) [y,d,n,q,h]
+````
 
 You can force to always overwrite file with `:force` option or always skip by providing `:skip`.
 
+There is [examples/overwrite.rb](examples/overwrite.rb) that demonstrates diffing file with new content.
+
 ### 2.6. copy_dir
 
-To recursively copy a directory of files from source to destination location use `copy_directory` or its alias 'copy_dir'.
+To recursively copy a directory of files from source to destination location use `copy_directory` or its alias `copy_dir`.
 
 Assuming you have the following directory structure:
 
@@ -190,10 +220,10 @@ Assuming you have the following directory structure:
 #   %name%.rb
 ```
 
-you can copy `doc` folder to `docs` by invoking:
+You can copy `doc` folder to `docs` by invoking:
 
 ```ruby
-TTY::File.copy_directory('doc', 'docs', context: ...)
+TTY::File.copy_directory("doc", "docs", context: ...)
 ```
 
 The `context` needs to respond to `name` message and given it returns `foo` value the following directory gets created:
@@ -209,13 +239,13 @@ The `context` needs to respond to `name` message and given it returns `foo` valu
 If you only need to copy top level files use option `recursive: false`:
 
 ```ruby
-TTY::File.copy_directory('doc', 'docs', recursive: false)
+TTY::File.copy_directory("doc", "docs", recursive: false)
 ```
 
 By passing `:exclude` option you can instruct the method to ignore any files including the given pattern:
 
 ```ruby
-TTY::File.copy_directory('doc', 'docs', exclude: 'subcommands')
+TTY::File.copy_directory("doc", "docs", exclude: "subcommands")
 ```
 
 ### 2.7. create_dir
@@ -223,21 +253,21 @@ TTY::File.copy_directory('doc', 'docs', exclude: 'subcommands')
 To create directory use `create_directory` or its alias `create_dir` passing as a first argument file path:
 
 ```ruby
-TTY::File.create_dir(/path/to/directory)
+TTY::File.create_dir("/path/to/directory")
 ```
 
-or a data structure describing the directory tree including any files with or without content:
+Or a data structure describing the directory tree including any files with or without content:
 
 ```ruby
 tree =
-  'app' => [
-    'README.md',
-    ['Gemfile', "gem 'tty-file'"],
-    'lib' => [
-      'cli.rb',
-      ['file_utils.rb', "require 'tty-file'"]
+  "app" => [
+    "README.md",
+    ["Gemfile", "gem 'tty-file'"],
+    "lib" => [
+      "cli.rb",
+      ["file_utils.rb", "require 'tty-file'"]
     ]
-    'spec' => []
+    "spec" => []
   ]
 ```
 
@@ -256,50 +286,93 @@ TTY::File.create_dir(tree)
 As a second argument you can provide a parent directory, otherwise current directory will be assumed:
 
 ```ruby
-TTy::File.create_dir(tree, '/path/to/parent/dir')
+TTY::File.create_dir(tree, "/path/to/parent/dir")
 ```
 
-### 2.8. diff
+### 2.8. diff_files
 
 To compare files line by line in a system independent way use `diff`, or `diff_files`:
 
 ```ruby
-TTY::File.diff('file_a', 'file_b')
-# =>
-#  @@ -1,4 +1,4 @@
-#   aaa
-#  -bbb
-#  +xxx
-#   ccc
+print TTY::File.diff_files("file-a", "file-b")
 ```
 
-You can also pass additional arguments such as `:format`, `:context_lines` and `:threshold`.
+Printing output to console would result in:
+
+```
+        diff  examples/file-a and examples/file-b
+--- examples/file-a
++++ examples/file-b
+@@ -1,8 +1,9 @@
+ aaaaa
+ bbbbb
+-ccccc
++xxxxx
++
+ ddddd
+ eeeee
+ fffff
+-ggggg
++yyyyy
+```
 
-Accepted formats are `:old`, `:unified`, `:context`, `:ed`, `:reverse_ed`, by default the `:unified` format is used.
+You can also pass additional parameters such as:
 
-The `:context_lines` specifies how many extra lines around the differing lines to include in the output. By default its 3 lines.
+* `:format` - accepted values are `:unified`, `:old`, `:context` and `:ed`. Defaults to `:unified` as seen in the output above - similar to git tool.
+* `:lines` - how many extra lines to include in the output around the compared lines. Defaults to `3` lines.
+* `:threshold` - set maximum file size in bytes. By default files larger than `10Mb` are no processed.
+* `:header` - controls display of two-line files comparison. By default `true`.
 
-The `:threshold` sets maximum file size in bytes, by default files larger than `10Mb` are not processed.
+Changing format to `:old`, removing context lines and skipping log output:
 
 ```ruby
-TTY::File.diff('file_a', 'file_b', format: :old)
-# =>
-#  1,4c1,4
-#  < aaa
-#  < bbb
-#  < ccc
-#  ---
-#  > aaa
-#  > xxx
-#  > ccc
+TTY::File.diff_files("file_a", "file_b", format: :old, lines: 0, verbose: false)
+```
+
+Results in the following output:
+
+```
+<<< examples/file-a
+>>> examples/file-b
+3c3,4
+< ccccc
+---
+> xxxxx
+>
+
+7c8
+< ggggg
+---
+> yyyyy
 ```
 
-Equally, you can perform a comparison between a file content and a string content like so:
+In addition, you can perform a comparison between a file and a string or between two strings. For example, comparing file with content:
 
 ```ruby
-TTY::File.diff('/path/to/file', 'some long text')
+TTY::File.diff_files("file-a", "new\nlong\ntext")
 ```
 
+Will output:
+
+```
+        diff  a/examples/file-a and b/examples/file-a
+--- a/examples/file-a
++++ b/examples/file-a
+@@ -1,8 +1,4 @@
+-aaaaa
+-bbbbb
+-ccccc
+-ddddd
+-eeeee
+-fffff
+-ggggg
++new
++long
++text
+````
+
+Please run [examples/diff.rb](examples/diff.rb) to see how output works.
+
 ### 2.9. download_file
 
 To download a content from a given address and to save at a given relative location do:
@@ -328,32 +401,46 @@ TTY::File.download_file("https://gist.github.com/4701967", "doc/README.md", limi
 Inject content into a file at a given location and return `true` when performed successfully, `false` otherwise.
 
 ```ruby
-TTY::File.inject_into_file 'filename.rb', "text to add", after: "Code below this line\n"
+TTY::File.inject_into_file "filename.rb", "text to add", after: "Code below this line\n"
 ```
 
-or using a block
+Or using a block:
 
 ```ruby
-TTY::File.inject_into_file 'filename.rb', after: "Code below this line\n" do
+TTY::File.inject_into_file "filename.rb", after: "Code below this line\n" do
   "text to add"
 end
 ```
 
-You can also use Regular Expressions in `:after` or `:before` to match file location. The `append_to_file` and `prepend_to_file` allow you to add content at the end and the begging of a file.
+You can also use Regular Expressions in `:after` or `:before` to match file location.
+
+By default, this method will always inject content into file, regardless whether it is already present or not. To change this pass `:force` set to `false` to perform check before actually inserting text:
+
+```ruby
+TTY::File.inject_into_file("filename.rb", "text to add", after: "Code below this line\n"
+```
+
+Alternatively, use `safe_inject_into_file` to check if the text can be safely inserted.
+
+```ruby
+TTY::File.safe_inject_into_file("Gemfile", "gem 'tty'")
+```
+
+The [append_to_file](#212-append_to_file) and [prepend_to_file](#213-prepend_to_file) allow you to add content at the end and the begging of a file.
 
 ### 2.11. replace_in_file
 
 Replace content of a file matching condition by calling `replace_in_file` or `gsub_file`, which returns `true` when substitutions are performed successfully, `false` otherwise.
 
 ```ruby
-TTY::File.replace_in_file 'filename.rb', /matching condition/, 'replacement'
+TTY::File.replace_in_file "filename.rb", /matching condition/, "replacement"
 ```
 
 The replacement content can be provided in a block
 
 ```ruby
-TTY::File.gsub_file 'filename.rb', /matching condition/ do
-  'replacement'
+TTY::File.gsub_file "filename.rb", /matching condition/ do
+  "replacement"
 end
 ```
 
@@ -362,45 +449,69 @@ end
 Appends text to a file and returns `true` when performed successfully, `false` otherwise. You can provide the text as a second argument:
 
 ```ruby
-TTY::File.append_to_file('Gemfile', "gem 'tty'")
+TTY::File.append_to_file("Gemfile", "gem 'tty'")
 ```
 
-or inside a block:
+Or inside a block:
 
 ```ruby
-TTY::File.append_to_file('Gemfile') do
+TTY::File.append_to_file("Gemfile") do
   "gem 'tty'"
 end
 ```
 
+By default, this method will always append content regardless whether it is already present or not. To change this pass `:force` set to `false` to perform check before actually appending:
+
+```ruby
+TTY::File.append_to_file("Gemfile", "gem 'tty'", force: false)
+```
+
+Alternatively, use `safe_append_to_file` to check if the text can be safely appended.
+
+```ruby
+TTY::File.safe_append_to_file("Gemfile", "gem 'tty'")
+```
+
 ### 2.13. prepend_to_file
 
 Prepends text to a file and returns `true` when performed successfully, `false` otherwise. You can provide the text as a second argument:
 
 ```ruby
-TTY::File.prepend_to_file('Gemfile', "gem 'tty'")
+TTY::File.prepend_to_file("Gemfile", "gem 'tty'")
 ```
 
-or inside a block:
+Or inside a block:
 
 ```ruby
-TTY::File.prepend_to_file('Gemfile') do
+TTY::File.prepend_to_file("Gemfile") do
   "gem 'tty'"
 end
 ```
 
+By default, this method will always prepend content regardless whether it is already present or not. To change this pass `:force` set to `false` to perform check before actually prepending:
+
+```ruby
+TTY::File.prepend_to_file("Gemfile", "gem 'tty'", force: false)
+```
+
+Alternatively, use `safe_prepend_to_file` to check if the text can be safely appended.
+
+```ruby
+TTY::File.safe_prepend_to_file("Gemfile", "gem 'tty'")
+```
+
 ### 2.14. remove_file
 
 To remove a file do:
 
 ```ruby
-TTY::File.remove_file 'doc/README.md'
+TTY::File.remove_file "doc/README.md"
 ```
 
 You can also pass in `:force` to remove file ignoring any errors:
 
 ```ruby
-TTY::File.remove_file 'doc/README.md', force: true
+TTY::File.remove_file "doc/README.md", force: true
 ```
 
 ### 2.15. tail_file
@@ -408,14 +519,14 @@ TTY::File.remove_file 'doc/README.md', force: true
 To read the last 10 lines from a file do:
 
 ```ruby
-TTY::File.tail_file 'doc/README.md'
-# => ['## Copyright', 'Copyright (c) 2016-2017', ...]
+TTY::File.tail_file "doc/README.md"
+# => ["## Copyright", "Copyright (c) 2016-2017", ...]
 ```
 
 You can also pass a block:
 
 ```ruby
-TTY::File.tail_file('doc/README.md') do |line|
+TTY::File.tail_file("doc/README.md") do |line|
   puts line
 end
 ```
@@ -423,7 +534,7 @@ end
 To change how many lines are read pass a second argument:
 
 ```ruby
-TTY::File.tail_file('doc/README.md', 15)
+TTY::File.tail_file("doc/README.md", 15)
 ```
 
 ## Development
@@ -442,4 +553,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Copyright
 
-Copyright (c) 2016-2018 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2016 Piotr Murach. See LICENSE for further details.