mvb 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9a9dd9a37c9202b5016f54508d32d876b2baa95ab86f90355d9763427a6e79f
-  data.tar.gz: f40d7182c62000bcbd455d7e3a7c51d47ecc79ad17b1767ed20d88da1fd4c1a1
+  metadata.gz: f52946fe658cc5bcd3a37a90dbc0fad9c334c25dad48dab750f1bd084a6438cd
+  data.tar.gz: 27740c082628cedc8e9d5bf40a8519b1172527a48a5e5dc768b494261668aa0b
 SHA512:
-  metadata.gz: ac6bcf8e1d406b49e1a40b72fbaa6e1f1c3eed1e539b1a5e58b2e06d848e06f651ee1f077c4ee7445add1e884bbf8cc328920160fda21ee027a6c14992ccf472
-  data.tar.gz: 35388f1ba151d170dda9e4aa18f4bce064f02519a9c913f42a3411c932397c64d6c6ae66fc5eddeccf4da1a411f34eeea5f3c54dbfa70e7f6f8e04242bd1d87d
+  metadata.gz: 905eea5055c13151a502cc6f3d6984bd23e4a82ebd3ff49f6129fa3729126d33cd7642c8d7d4a3dc005d723c66d0c62ca05a22852437a0462b2a3d91a50b00f1
+  data.tar.gz: 4f88e22c25b5d1cc5081b106abde06eef3fa0e5ef52f98a19e27a6d5e13e4280d111028fbc631e116fa848611acd74480d59a3e6886cec81c3ade78b96a20914

data/exe/mvb

@@ -1,5 +1,4 @@
 #!/usr/bin/env ruby
-# Tienes una nota en Joplin. Léela.
 
 require 'optparse'
 require_relative '../lib/mvb'
@@ -11,32 +10,85 @@ pattern         = nil
 force_rename    = false
 steps           = 1
 
-banner = <<~EOM
-Usage:
-  mvb [-s,--search] "PATTERN" [-r,--replacement] ["STRING"] [-f,--force]
+banner = <<EOM
 
-You can enter the arguments by option tags or by position. Tag options get precedence over positions.
-In positional options, first argument corresponds to the search pattern, and second, the replacement.
+COMMAND USAGE:
+    mvb [-s,--search] "REGEX_PATTERN" [-r,--replacement] ["REPLACEMENT"] [-f,--force] [-i,--step N] [-h, --help]
 
-The only required argument is the search pattern. If replacement is not given,
-the output is a list of the matched files.
+  You can enter the search and replacement arguments by tag or by position. Tag options get precedence over positions.
+  In positional options, first argument corresponds to the search pattern, and second argument, to the replacement.
 
-If both options are given (search and replacement), the output will consists
-of two columns: first column lists the current filenames matched by the search patterns,
-and second column their replacement counterpart. This will be a dry-run, though; no rename
-will be executed
+COMMAND USAGE WITH POSITIONAL ARGUMENTS:
+    mvb "REGEX_PATTERN" ["REPLACEMENT"] [tag options...]
 
-To execute the rename, add the --force (or -f) option.
+  The only required argument is the search pattern. If replacement is not given,
+  the output is a list of the matched files.
 
-IMPORTANT: if you are going to use regex as pattern, it is strongly recommended
-to enclose it in double quotes in order to avoid conflicts between the regex
-special characters and the wildcards of the shell.
+  If both options are given (search and replacement), the output will consist of two columns:
+  first column lists the current filenames matched by the search pattern,
+  and second column their replacement counterpart.
+  If -f tag is not given, this list will be a dry-run; no rename will be executed.
+
+  To execute the rename, add the --force (or -f) tag option.
+
+  The search pattern can be a normal string or a regex pattern. The syntax of the regex partten is the one
+  used by Ruby. Which follows the PCRE convension; it is very similar VSCode's.
+
+  In replacement string, you can access to captured groups via "\\n" syntax, where "n" is the
+  group number; e.g. "\\1", "\\2", "\\3", etc.
+
+IMPORTANT:
+  This program is designed to rename files located at root folder.
+  So, you need first to change directory to the location of the files in order to use mvb.
+
+  If the search or replacement contain characters like backslashes, asterisks, parentheses or
+  brackets, you must enclose these fields in double quotes in order to avoid conflicts
+  with the wildcards of the shell. Otherwise, you will experience unexpected results.
+  On the other hand, if these fields are composed by letters and other typical chars, you can omit
+  the double quotes. To stay on the safe side, however, it is recommended to use double-quotes always.
 
 SEQUENTIAL NUMBERING:
-On replacement string, you can introduce sequential numbering by using a "#" as placeholder along
-with an integer which will be the starting point. For example, if you use "image-#1" as replacement,
-the output will consist of: image-1, image-2, image-3, etc. until reached the last replacement item.
-You can use the option `-i` to set the steps of increments.
+  In replacement string, you can introduce sequential numbering by using "#" as placeholder along
+  with an integer used as starting point. For example, if you use "image-#1" as replacement,
+  the output will consist of: image-1, image-2, image-3, etc. until reached the last replacement item.
+  You can use the option `-i` to set the step of increment.
+
+EXAMPLES OF USAGE:
+  Given this batch of files on root folder: book1.txt, book2.txt, book3.txt, book4.txt.
+  Consider the following examples of usage.
+
+  EXAMPLE 1 - List of the matched files
+
+  $ mvb book
+  book1.txt
+  book2.txt
+  book3.txt
+  book4.txt
+
+  EXAMPLE 2 - Dry-run of replacement
+
+  $ mvb book libro
+  book1.txt --> libro1.txt
+  book2.txt --> libro2.txt
+  book3.txt --> libro3.txt
+  book4.txt --> libro4.txt
+
+  EXAMPLE 3 - Dry-run of replacement, with sequential numbering
+
+  $ mvb "book\\d" "libro#3"
+  book1.txt --> libro3.txt
+  book2.txt --> libro4.txt
+  book3.txt --> libro5.txt
+  book4.txt --> libro6.txt
+
+  EXAMPLE 4 - Dry-run of replacement, with sequential numbering and increments of 2
+ 
+  $ mvb "book\d" "libro#3" -i 2
+  book1.txt --> libro3.txt
+  book2.txt --> libro5.txt
+  book3.txt --> libro7.txt
+  book4.txt --> libro9.txt
+
 
 EOM
 
@@ -44,28 +96,32 @@ opt_parser = OptionParser.new do |opts|
 
   opts.banner = banner
 
-  opts.on("-s", "--search PATTERN", "Search for files that match with PATTERN. If no replace PATTERN is given,
-    just list the matched files. Argument required, option tag is not required.") do |argument|
+  opts.on("-s", "--search REGEX_PATTERN", "Search for files that match with PATTERN. If no replacement is given, just list the matched files. Required. Tag not required") do |argument|
     search = argument
   end
 
-  opts.on("-r", "--replacement PATTERN", "Replace the matched files with given PATTERN. Optional.") do |argument|
+  opts.on("-r", "--replacement STRING", "Replace the matched files with given STRING. Optional. Tag is not required") do |argument|
     replacement = argument
   end
 
-  opts.on("-f", "--force", "Execute renaming") do
+  opts.on("-f", "--force", "Execute rename") do
     force_rename = true
   end
 
-  opts.on("-i STEPS", "--steps=STEPS", "Steps of increment on sequential numbering." ) do |argument|
+  opts.on("-i STEP", "--step=STEP", "Step of increment on sequential numbering" ) do |argument|
     steps = argument.to_i if argument.to_i != 0
   end
 
-  opts.on("-h", "--help", "Show this help message.") do
+  opts.on("-h", "--help", "Show this help message") do
     puts opts
     exit
   end
 
+  opts.on("-v", "--version", "Show gem version") do
+    puts "mvb version: #{Mvb::VERSION}"
+    exit
+  end
+
 end
 
 # Parse the options and store remaining arguments as positional

data/lib/mvb/version.rb

@@ -1,4 +1,4 @@
 
 module Mvb
-    VERSION = "0.0.1"
+    VERSION = "0.0.3"
 end

data/lib/mvb.rb

@@ -104,7 +104,7 @@ module Mvb
         if force_rename
             puts "\nFiles renamed!"
         else
-            puts "\nThis is a dry-run. No file has been renamed."
+            puts "\nThis is a dry-run. No file has been renamed.\nAdd -f to execute rename."
         end
     end
 

metadata

@@ -1,16 +1,23 @@
 --- !ruby/object:Gem::Specification
 name: mvb
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Manuel Fuenmayor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2024-10-13 00:00:00.000000000 Z
 dependencies: []
-description: A gem to rename batch of files, with sequential numbering feature
+description: |
+  This is a simple-to-use command-line gem to rename batch of files (or folders) using regex patterns. Sequential numbering feature is also added to re-define (or establish) numbered files.
+
+  Supported regex follows PCRE convention which is very similar to the one used by VSCode.
+
+  At this stage, this program is designed to rename files located at root folder. Therefore, you would need first to change directory to the location of the files to use mvb.
+
+  For full documentation, use "mvb -h".
 email: manuel.fuenmayor98@gmail.com
 executables:
 - mvb
@@ -32,7 +39,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -42,5 +49,5 @@ requirements: []
 rubygems_version: 3.5.20
 signing_key:
 specification_version: 4
-summary: A script to rename batch of files
+summary: A gem to rename batch of files using regex, with sequential numbering capabilities.
 test_files: []