filename 0.0.6 → 0.1.0

data/README.md

@@ -1,21 +1,31 @@
 # filename
 
-This gem includs the class FileName to create filename that is not duplicated
-and command 'filename-create' for shell.
-We select type of additional part of filename: number or time.
+The gem 'filename' is used to create filenames that have sequential numbers,
+time strings, or strings of other formats not to be duplicated.
+This includes the class FileName and command 'filename-create' for shell.
+
+* [http://rubygems.org/gems/filename](http://rubygems.org/gems/filename)
+* [http://rubydoc.info/gems/filename/](http://rubydoc.info/gems/filename/)
 
 ## Installation
 
+We can install gem command.
+
     gem install filename
 
+## Requirements
+
+filename is tested on ruby 1.9.2.
+For arguments with variable length errors occur on ruby 1.8.7.
+
 ## How to use as library
 
 We need to require 'filename'.
 
     require 'filename'
 
-And then we create method for an instance of FileName or
-class method FileName.create.
+And then we call 'create' method for an instance of FileName or
+class method 'FileName.create'.
 
 ### Filenames with sequential numbers
 
@@ -28,12 +38,25 @@ Default options add suffixes and use additional parts of sequential numbers.
     p filename.create(:add => :always)    # => "/path/to/base.txt.01"
     p filename.create(:add => :always)    # => "/path/to/base.txt.02"
 
+We give a base filename and get an instance of FileName.
+Then, we get filenames with sequential numbers
+by FileName#create.
+The default value of option :add of FileName#create is :auto
+and add some string to filename if the targeted file exists.
+If we set :auto to the option :add as the above example,
+we add always add some string to filename.
+
 ### Filenames with time strings
 
     require 'filename'
     filename = FileName.new('base.txt', :type => :time)
     p filename.create(:add => :always)    # For example, returns "/path/to/base.txt.20110326_073247_078247"
 
+If we set :time to the option :type of FileName.new,
+we add time string to filename.
+The default value of the option :type is :number and
+we add a number to filename.
+
 ### Control adding additional parts
 
     require 'filename'
@@ -42,7 +65,11 @@ Default options add suffixes and use additional parts of sequential numbers.
     p filename.create(:add => :prohibit)  # Always returns "/path/to/base.txt"
     p filename.create(:add => :auto)      # If the file exist, returns "/path/to/base.txt.00". Otherwise, "/path/to/base.txt"
 
-### Add additinal parts to prefix or middle position
+### Add additional parts to prefix or middle position
+
+An option :position controls positions of additional strings.
+The value :suffix, :prefix, and :middle are accepted.
+The default is :suffix.
 
     require 'filename'
     filename = FileName.new('base.txt', :position => :prefix)
@@ -53,6 +80,11 @@ Default options add suffixes and use additional parts of sequential numbers.
 
 ### Change delimiters
 
+The default delimiter is "." if the option :position is :suffix.
+Otherwise, the string is "_".
+If we want to change delimiter string, we set desired string to
+an option :delimiter.
+
     require 'filename'
     filename = FileName.new('base.txt', :position => :prefix, :delimiter => '')
     p filename.create(:add => :always)    # => "/path/to/00base.txt"
@@ -62,24 +94,48 @@ Default options add suffixes and use additional parts of sequential numbers.
 
 ### Change extensions
 
+If we want to change extension of base filename,
+we set an option :extension.
+
     require 'filename'
     filename = FileName.new('base.txt')
     p filename.create(:add => :always, :extension => 'log')    # => "/path/to/base.log.00"
 
 ### Create parent directory
 
+If we set :parent to an option :directory,
+we make the parent directories on creating filenames.
+
     require 'filename'
     filename = FileName.new('dir/base.txt')
     p filename.create(:add => :always, :directory => :parent)    # Create 'dir' directory.
 
 ### Create directory of created filename
 
+If we set :self to an option :directory,
+we make the directories of created filenames.
+
     require 'filename'
     filename = FileName.new('dir1/dir2')
     p filename.create(:add => :always, :directory => :self)    # Create 'dir1/dir2' directory.
 
+### Create empty file
+
+If we set an option :file, we can create an empty file.
+If the value is :write and the targeted file does not exist,
+we create an empty file.
+If the value is :overwrite, we always create an empty file.
+
+    require 'filename'
+    filename = FileName.new('path/to/file')
+    p filename.create(:file => :write)        # Create empty file 'path/to/file' if 'path/to/file' does not exist.
+    p filename.create(:file => :overwrite)    # Create empty file 'path/to/file' even if 'path/to/file' exists.
+
 ### Change starting numbers and digits of sequential numbers
 
+We can set starting number by an option :start and
+digit number by an option :digit.
+
     require 'filename'
     filename = FileName.new('base.txt', :digit => 4, :start => 1000)
     p filename.create(:add => :always)    # => "/path/to/base.txt.1000"
@@ -87,6 +143,11 @@ Default options add suffixes and use additional parts of sequential numbers.
 
 ### Change formats of sequential numbers
 
+If we set string object to an option :format,
+the value is used by method sprintf.
+If we set proc object that take Fixnum,
+we use the evaluation of the proc object as an additional string.
+
     require 'filename'
     filename = FileName.new('base.txt', :format => "@%03d@")
     p filename.create(:add => :always)    # => "/path/to/base.txt.@000@"
@@ -97,6 +158,13 @@ Default options add suffixes and use additional parts of sequential numbers.
 
 ### Change formats of time strings
 
+We can set a string or proc object to an option :format
+similar to the case of number type.
+If the value is a string, we use the string as first argument of
+method sprintf.
+If the value is a proc object, we evaluate it and
+use returned value as an additional part.
+
     require 'filename'
     filename = FileName.new('base.txt', :format => "%H%M%S")
     p filename.create(:add => :always)    # For example, returns "/path/to/base.txt.075130"
@@ -106,6 +174,10 @@ Default options add suffixes and use additional parts of sequential numbers.
 
 ### Use of variable for proc set by :format option
 
+If we give a hash to an option :data,
+the values of the hash are saved as instance variables.
+We can use the variables in proc object for an option :format.
+
     require 'filename'
     filename = FileName.new('base.txt', :data => { :a => 3 },
                             :format => lambda { |n| s = sprintf("%03d", @a * n); @a += 2; s })
@@ -113,18 +185,38 @@ Default options add suffixes and use additional parts of sequential numbers.
     p filename.create(:add => :always)    # => "/path/to/base.txt.005"
     p filename.create(:add => :always)    # => "/path/to/base.txt.014"
 
+In the above example we prepare the instance variable "@a = 3"
+and use @a in proc object specified by an option :format.
+
+### Options of FileName#new, FileName#create, and FileName.create
+
+If we set options of FileName#create to FileName#new,
+the values is the default values of FileName#create.
+If we want to change on creating filenames, 
+we set options for FileName#create.
+Options of FileName.create are the same as these of FileName#new.
+
 ## How to use command 'filename-create'
 
+We can use command 'filename-create' on shell.
+
+### Basic usage and options
+
 filename-create with 'new' and basename puts path of file.
 
     filename-create new basename
 
-We can use the corresponding options to optional arguments of
-FileName#create.
+Then the created filename is displayed.
+
+We can use the options corresponding to
+the optional arguments of FileName#create
+except for "--cache" option.
+We also can not set proc object to :format by command filename-create.
 
     -s, --start NUM                  Set the starting number.
     -i, --digit NUM                  Set the digit of number.
     -d, --delimiter STR              Set the delimiter string: number or time.
+    -n, --no-delimiter               Do not use delimiter.
     -t, --type TYPE                  Set the type of additional part.
     -f, --format STR                 Set the format string.
     -p, --position POS               Set the position of addition: prefix, suffix, or middle.
@@ -132,15 +224,47 @@ FileName#create.
     -e, --extension STR              Set the extension string.
     -a, --add STR                    Change the behavior of addition: always, auto, or prohibit.
     -D, --directory STR              Create directory: self or parent.
+    -F, --file STR                   Create an empty file: write or overwrite.
+    -c, --cache KEY                  Create cache for command "new" and "config".
+
+### cache
 
 To create sequential filenames, we call 'filename-create new' with '--cache' option
-and then 'filename-create cache'.
+to create cache. At this point, we set options that we want to use.
+
+    filename-create new basename --add always --cache cache_name
+
+We refer created cache by 'cache_name'.
+To generate filenames from cache we type the following.
+
+    filename-create cache cache_name
+
+Sequential commands create filenames with sequential numbers.
 
-    filename-create new basename --add always --cache base
-    filename-create cache base
-      /path/to/basename.00
-    filename-create cache base
-      /pat/to/basename.01
+When we finish to use the cache,
+we type
+
+    filename-create delete_cache cache_name
+
+and then delete the cache.
+
+To list the saved cache, we type
+
+    filename-create list_cache
+
+### Configuration files
+
+If we save files in directory ~/.filename\_gem/conf,
+which define a ruby hash of options of FileName#create,
+we can use the configurations to create filenames.
+If there is ~/.filename\_gem/conf/sample.rb that preserves an option hash,
+we type
+
+    filename-create config sample
+
+and get filename from the configuration.
+We can also create cache to type it with "--cache" option
+same as "filename-create new".
 
 ## Contributing to filename
  
@@ -152,7 +276,11 @@ and then 'filename-create cache'.
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
+## License
+
+The license is GPLv3.
+See LICENSE.txt for further details.
+
 ## Copyright
 
-Copyright (c) 2011 Takayuki YAMAGUCHI. See LICENSE.txt for
-further details.
+Copyright (c) 2011 Takayuki YAMAGUCHI. 

data/VERSION

@@ -1 +1 @@
-0.0.6
+0.1.0

data/bin/filename-create

@@ -18,7 +18,7 @@ Usage: #{basename} <command> [arguments ...] [options ...]
 
 HELP
 
-Version = '0.0.4'
+Version = '0.1.0'
 
 options = {}
 create_cache = false
@@ -34,6 +34,9 @@ begin
     opt.on('-d STR', '--delimiter STR', String, 'Set the delimiter string: number or time.') do |v|
       options[:delimiter] = v
     end
+    opt.on('-n', '--no-delimiter', "Do not use delimiter.") do |v|
+      options[:delimiter] = ''
+    end
     opt.on('-t TYPE', '--type TYPE', String, 'Set the type of additional part.') do |v|
       options[:type] = v.intern
     end
@@ -55,7 +58,10 @@ begin
     opt.on('-D STR', '--directory STR', String, 'Create directory: self or parent.') do |v|
       options[:directory] = v.intern
     end
-    opt.on('-c KEY', '--cache KEY', String, 'Create cache for command "new".') do |v|
+    opt.on('-F STR', '--file STR', String, 'Create an empty file: write or overwrite.') do |v|
+      options[:file] = v.intern
+    end
+    opt.on('-c KEY', '--cache KEY', String, 'Create cache for command "new" and "config".') do |v|
       create_cache = v
     end
     opt.parse!(ARGV)
@@ -116,6 +122,9 @@ begin
   when 'init'
     manage.save_configuration_example
     exit(0)
+  else
+    raise OptionParser::InvalidArgument
+    exit(1)
   end
 rescue OptionParser::InvalidOption
   $stderr.print <<MES

data/filename.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{filename}
-  s.version = "0.0.6"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Takayuki YAMAGUCHI"]
-  s.date = %q{2011-04-09}
+  s.date = %q{2011-04-15}
   s.description = %q{Create filename with sequential number or time string that is not duplicated.}
   s.email = %q{d@ytak.info}
   s.executables = ["filename-create"]

data/lib/filename.rb

@@ -8,7 +8,7 @@ class FileName
 
   attr_accessor :configuration_key, :format
 
-  OPTIONS_CREATE = [:extension, :add, :directory]
+  OPTIONS_CREATE = [:extension, :add, :directory, :file]
 
   # The options are following:
   # 
@@ -55,6 +55,9 @@ class FileName
   # 
   # [:directory]
   #  Default value of the option of FileName#create.
+  # 
+  # [:file]
+  #  Default value of the option of FileName#create.
   def initialize(basepath, *rest)
     if Hash === rest[-1]
       opts = rest.delete_at(-1)
@@ -69,6 +72,9 @@ class FileName
     end
     @number = opts[:start] || 0
     @digit = opts[:digit] || 2
+    if @digit < 1
+      raise ArgumentError, "Number of digit must be positive."
+    end
     @type = opts[:type] || :number
     @position = opts[:position] || :suffix
     @delimiter = opts[:delimiter] || (@position == :suffix ? '.' : '_')
@@ -190,6 +196,28 @@ class FileName
   end
   private :create_directory
 
+  def touch_file(path)
+    FileUtils.mkdir_p(File.dirname(path))
+    open(path, 'w') {}
+  end
+  private :touch_file
+
+  def write_file(path, file_opt)
+    if file_opt
+      case file_opt
+      when :write
+        unless File.exist?(path)
+          touch_file(path)
+        end
+      when :overwrite
+        touch_file(path)
+      else
+        raise ArgumentError, "Invalid file option."
+      end
+    end
+  end
+  private :write_file
+
   # The options are following:
   # [:extension (String of extension)]
   #  If we want to change extension, we set the value of the option.
@@ -203,6 +231,12 @@ class FileName
   # [:directory (:self, :parent, or nil)]
   #  If the value is :self, we make directory of created filename.
   #  If the value is :parent, we make parent directory of created filename.
+  #  If the value is nil, we do nothing.
+  # 
+  # [:file]
+  #  If the value is :overwrite, we create a new empty file.
+  #  If the value is :write and the file does not exist, we create an empty file.
+  #  If the value is nil, we do nothing.
   def create(opts = {})
     base = get_basepath(get_option_create(opts, :extension))
     opt_add = get_option_create(opts, :add)
@@ -220,6 +254,7 @@ class FileName
       path = base
     end
     create_directory(path, get_option_create(opts, :directory))
+    write_file(path, get_option_create(opts, :file))
     path
   end
 

data/spec/filename_spec.rb

@@ -143,6 +143,25 @@ describe FileName do
     FileUtils.rm_r(File.dirname(path))
   end
 
+  it "should create empty file" do
+    basename = File.join(File.dirname(__FILE__), 'abc/def')
+    filename = FileName.new(basename)
+    path = filename.create(:file => :write)
+    File.exist?(path).should be_true
+    File.read(path).should == ''
+    FileUtils.rm_r(File.dirname(path))
+  end
+
+  it "should overwrite empty file" do
+    basename = File.join(File.dirname(__FILE__), 'abc/def')
+    filename = FileName.new(basename, :add => :prohibit)
+    open(filename.create(:directory => :parent), 'w') { |f| f.puts "hello world" }
+    path = filename.create(:file => :overwrite)
+    File.exist?(path).should be_true
+    File.read(path).should == ''
+    FileUtils.rm_r(File.dirname(path))
+  end
+
   it "should conbine a few arguments" do
     filename = FileName.new('abc', 'def', 'ghi')
     filename.create.should == File.expand_path('abc/def/ghi')
@@ -212,6 +231,30 @@ describe FileName do
       end
     end
 
+    it "should create empty file" do
+      basename = File.join(File.dirname(__FILE__), 'abc/def')
+      filename = FileName.new(basename, :file => :write)
+      NUMBER_TEST_REPEAT.times do |i|
+        path = filename.create
+        File.exist?(path).should be_true
+        File.read(path).should == ''
+        FileUtils.rm_r(File.dirname(path))
+      end
+    end
+
+    it "should overwrite empty file" do
+      basename = File.join(File.dirname(__FILE__), 'abc/def')
+      filename0 = FileName.new(basename, :add => :prohibit, :directory => :parent)
+      filename = FileName.new(basename, :add => :prohibit, :file => :overwrite)
+      NUMBER_TEST_REPEAT.times do |i|
+        open(filename0.create, 'w') { |f| f.puts "hello world" }
+        path = filename.create
+        File.exist?(path).should be_true
+        File.read(path).should == ''
+        FileUtils.rm_r(File.dirname(path))
+      end
+    end
+
     it "should change extension" do
       filename = FileName.new(__FILE__, :extension => 'txt', :add => :prohibit)
       NUMBER_TEST_REPEAT.times do |i|

metadata

@@ -2,7 +2,7 @@
 name: filename
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors: 
 - Takayuki YAMAGUCHI
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-09 00:00:00 Z
+date: 2011-04-15 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
@@ -94,7 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -1246538817859403112
+      hash: -1890861991035807209
       segments: 
       - 0
       version: "0"