textrepo 0.5.0 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc5cf6089b4883c93dc228e19aa0a149d71a8d9cc26a92e6c75fdc4ee0b2d694
-  data.tar.gz: 8ebecace02d486b6b6c12256d52adfd44963a3a14f6d39729b83d426bce3a26e
+  metadata.gz: e768443355f1c5764d5b5061f65c513485446f6df9ebce67b5b5f58a4ac30b20
+  data.tar.gz: 9062103447a89fd2e7484c448ac80315906a2602fba363e142c47f0d5ecc592d
 SHA512:
-  metadata.gz: aef27bf0363a66eeb1676ccda0682c253155875a8d0c16b27189674836edf2563b8df87b7f3b56cdb5d02c895f724f47a956588a5d97d24d83cdddce76fc083e
-  data.tar.gz: 81a4f8a76eb0ec8545e29ddbd537d49ec00f6009f5617dad61c61d8a5552c6df090d6d37fd507a7976c5f5f60b7d0c8b43f9a99d98d7efa1e933828270711d87
+  metadata.gz: 4889cfefdf5cadbaddd47f83e31a870829a9b144dddb346b8cf6f72d55fac68d6a75c1d7f180e315720f90eeb70801fd2a987920055c2d4334537955bd544678
+  data.tar.gz: 49c5b9a1d34de8335b815e7e56070d2fa9bfdaa2a9a931f53c93ac28bff6e3da03f307f57c5faf8155bf0c01ef7ee5a61956d0605cc7d372247f184da0b0c3a6

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 Nothing to record here.
 
+## [0.5.5] - 2020-11-10
+### Add
+- Add more methods for `Timestamp` class.
+  - most of them are delegated to Time class
+  - some of them are useful to manipulate `Timestamp` object as
+    `String`.
+
+## [0.5.4] - 2020-11-05
+### Add
+- Add a feature for `Repository#update` to keep timestamp unchanged
+  - add the third argument as:
+    - `Repository#update(timestamp, text, keep_stamp = false)`
+
+## [0.5.3] - 2020-11-03
+### Changed
+- Fix issue #38: fix typo in code for FileSystemRepository.
+
+## [0.5.2] - 2020-11-03
+### Changed
+- Fix issue #34:
+  - fix FileSystemRepository#entries to accept "yyyymo" pattern as a
+    Timestamp pattern.
+- Fix issue #33: fix typo in the doc for FileSystemRepository.new.
+- Fix issue #31: unfriendly error message of Timestamp.parse_s.
+
+## [0.5.1] - 2020-11-02
+### Changed
+- Fix issue #28.
+  - Modify `Repository#update` to do nothing when the given text is
+    identical to the one in the repository.
+
 ## [0.5.0] - 2020-11-01
 ### Added
 - Add a new API `Repository#search`.

data/lib/textrepo/error.rb

@@ -22,15 +22,26 @@ module Textrepo
 
   # :stopdoc:
   module ErrMsg
-    UNKNOWN_REPO_TYPE   = 'unknown type for repository: %s'
-    DUPLICATE_TIMESTAMP = 'duplicate timestamp: %s'
-    EMPTY_TEXT          = 'empty text'
-    MISSING_TIMESTAMP   = 'missing timestamp: %s'
+    ARGUMENT_RANGE      = "argument out of range: %s"
+    UNKNOWN_REPO_TYPE   = "unknown type for repository: %s"
+    DUPLICATE_TIMESTAMP = "duplicate timestamp: %s"
+    EMPTY_TEXT          = "empty text"
+    MISSING_TIMESTAMP   = "missing timestamp: %s"
     INVALID_TIMESTAMP_STRING = "invalid string as timestamp: %s"
     INVALID_SEARCH_RESULT = "invalid result by searcher: %s"
   end
   # :startdoc:
 
+  ##
+  # An error raised if argument is out of range for Timestamp class.
+
+  class ArgumentRangeError < Error
+    def initialize(arg)
+      super(ErrMsg::ARGUMENT_RANGE % arg)
+    end
+  end
+
+
   ##
   # An error raised if unknown type was specified as the repository
   # type.

data/lib/textrepo/file_system_repository.rb

@@ -67,9 +67,10 @@ module Textrepo
     # were not defined in `conf`.
     #
     # Be careful to set `:searcher_options`, it must be to specify the
-    # searcher behavior equivalent to `grep` with "-inR".  The default
-    # value for the searcher options is defined for BSD grep (default
-    # grep on macOS), GNU grep, and ripgrep (aka rg).  They are:
+    # searcher behavior equivalent to `grep` with "-inRE".  The
+    # default values for the searcher options is defined for BSD grep
+    # (default grep on macOS), GNU grep, and ripgrep (aka rg).  They
+    # are:
     #
     #   "grep"   => ["-i", "-n", "-R", "-E"]
     #   "egrep"  => ["-i", "-n", "-R"]
@@ -77,7 +78,7 @@ module Textrepo
     #   "gegrep" => ["-i", "-n", "-R"]
     #   "rg"     => ["-S", "-n", "--no-heading", "--color", "never"]
     #
-    # If use those 3 searchers, it is not recommended to set
+    # If use those searchers, it is not recommended to set
     # `:searcher_options`.  The default value works well in
     # `textrepo`.
     #
@@ -129,26 +130,32 @@ module Textrepo
     end
 
     ##
-    # Updates the file content in the repository.  A new timestamp
-    # will be attached to the text.
+    # Updates the file content in the repository.  A new Timestamp
+    # object will be attached to the text.  Then, returns the new
+    # Timestamp object.
+    #
+    # When true is passed as the third argument, keeps the Timestamp
+    # unchanged, though updates the content.  Then, returns the given
+    # Timestamp object.
+    #
+    # See the documentation of Repository#update to know about errors
+    # and constraints of this method.
     #
     # :call-seq:
-    #     update(Timestamp, Array) -> Timestamp
+    #     update(Timestamp, Array, true or false) -> Timestamp
 
-    def update(timestamp, text)
+    def update(timestamp, text, keep_stamp = false)
       raise EmptyTextError if text.empty?
-      org_abs = abspath(timestamp)
-      raise MissingTimestampError, timestamp unless FileTest.exist?(org_abs)
+      raise MissingTimestampError, timestamp unless exist?(timestamp)
 
-      # the text must be stored with the new timestamp
-      new_stamp = Timestamp.new(Time.now)
-      new_abs = abspath(new_stamp)
-      write_text(new_abs, text)
+      # does nothing if given text is the same in the repository one
+      return timestamp if read(timestamp) == text
 
-      # delete the original file in the repository
-      FileUtils.remove_file(org_abs)
+      stamp = keep_stamp ? timestamp : Timestamp.new(Time.now)
+      write_text(abspath(stamp), text)
+      FileUtils.remove_file(abspath(timestamp)) unless keep_stamp
 
-      new_stamp
+      stamp
     end
 
     ##
@@ -182,7 +189,7 @@ module Textrepo
         if exist?(stamp)
           results << stamp
         end
-      when 0, "yyyymoddhhmiss".size, "yyyymodd".size
+      when 0, "yyyymoddhhmiss".size, "yyyymodd".size, "yyyymo".size
         results += find_entries(stamp_pattern)
       when 4                    # "yyyy" or "modd"
         pat = nil
@@ -317,7 +324,7 @@ module Textrepo
         file = abspath(entries[0])
         o, s = Open3.capture2(searcher, *find_searcher_options(searcher),
                               pattern, file)
-        if s.success? && (! o.empty)
+        if s.success? && (! o.empty?)
           output += o.lines.map { |line|
             # add filename at the beginning of the search result line
             [file, line.chomp].join(":")
@@ -333,7 +340,7 @@ module Textrepo
         files = find_files(entries)
         o, s = Open3.capture2(searcher, *find_searcher_options(searcher),
                               pattern, *files)
-        if s.success? && (! o.empty)
+        if s.success? && (! o.empty?)
           output += o.lines.map(&:chomp)
         end
       end

data/lib/textrepo/repository.rb

@@ -43,13 +43,27 @@ module Textrepo
     def read(timestamp); []; end
 
     ##
-    # Updates the content with text in the repository, which is
-    # associated to the timestamp.  Returns the timestamp.
+    # Updates the content with given text in the repository, which is
+    # associated to the given Timestamp object.  Returns the Timestamp
+    # newly generated during the execution.
+    #
+    # When true is passed as the third argument, keeps the Timestamp
+    # unchanged, though updates the content.  Then, returns the given
+    # Timestamp object.
+    #
+    # If the given Timestamp object is not existed as a Timestamp
+    # attached to text in the repository, raises
+    # MissingTimestampError.
+    #
+    # If the given text is empty, raises EmptyTextError.
+    #
+    # If the given text is identical to the text in the repository,
+    # does nothing.  Returns the given timestamp itself.
     #
     # :call-seq:
-    #     update(Timestamp, Array) -> Timestamp
+    #     update(Timestamp, Array, true or false) -> Timestamp
 
-    def update(timestamp, text); timestamp; end
+    def update(timestamp, text, keep_stamp = false); timestamp; end
 
     ##
     # Deletes the content in the repository, which is associated to

data/lib/textrepo/timestamp.rb

@@ -1,3 +1,5 @@
+require "forwardable"
+
 module Textrepo
   ##
   # Timestamp is generated from a Time object.  It converts a time to
@@ -18,6 +20,7 @@ module Textrepo
 
   class Timestamp
     include Comparable
+    extend Forwardable
 
     ##
     # Time object which generates the Timestamp object.
@@ -29,16 +32,28 @@ module Textrepo
 
     attr_reader :suffix
 
+    ##
+    # String object which is regarded as a value of Timestamp object.
+    # The value is generated from @time and @suffix.
+
+    attr_reader :str
+
     ##
     # Creates a Timestamp object from a Time object.  In addition, an
     # Integer can be passed as a suffix use.
     #
+    # Since Textrepo adapts 1 second as the time resolution, the
+    # subsec part of a given time will be ignored.
+    #
     # :call-seq:
     #   new(Time, Integer = nil) -> Timestamp
 
     def initialize(time, suffix = nil)
-      @time = time
+      raise ArgumentRangeError, suffix unless is_valid_suffix?(suffix)
+      parts = [:year, :mon, :day, :hour, :min, :sec].map{ |s| time.send(s) }
+      @time = Time.new(*parts)
       @suffix = suffix
+      @str = time_to_str(@time, @suffix)
     end
 
     def <=>(other)              # :nodoc:
@@ -51,19 +66,257 @@ module Textrepo
     end
 
     ##
-    # Generate an obvious time string.
+    # Generates an obvious time string.
     #
     #    %Y   %m %d %H %M %S  suffix
     #   "2020-12-30 12:34:56  (0 | nil)" -> "20201230123456"
     #   "2020-12-30 12:34:56  (7)"       -> "20201230123456_007"
 
     def to_s
+      @str
+    end
+
+    alias to_str to_s
+
+    # :stopdoc:
+
+    # delegators to Time object
+
+    def_instance_delegators :@time, :year, :mon, :day, :hour, :min, :sec
+    def_instance_delegators :@time, :wday, :monday?, :tuesday?, :wednesday?, :thursday?, :friday?, :saturday?, :sunday?
+    def_instance_delegators :@time, :asctime, :ctime, :strftime
+    def_instance_delegators :@time, :subsec, :nsec, :usec
+    def_instance_delegators :@time, :tv_nsec, :tv_sec, :tv_usec
+    def_instance_delegators :@time, :to_f, :to_i, :to_r
+    def_instance_delegators :@time, :yday, :mday
+    def_instance_delegators :@time, :month
+
+    # :startdoc:
+
+    def hash                    # :nodoc:
+      @str[0, 14].to_i * 1000 + @suffix.to_i
+    end
+
+    def eql?(other)             # :nodoc:
+      other.is_a?(Timestamp) && @time == other.time && @suffix == other.suffix
+    end
+
+    ##
+    # Returns a new Timestamp object which is given seconds ahead.
+    # Even if the suffix is not nil, the new Timestamp object will
+    # always have nil as its suffix.
+    #
+    # :call-seq:
+    #     +(Integer) -> Timestamp
+
+    def +(seconds)
+      Timestamp.new(@time + seconds, nil)
+    end
+
+    ##
+    # Returns difference of seconds between self and an argument.  If
+    # the argument is an Integer object, returns a new Timestamp
+    # object which is the given seconds behind.
+    #
+    # Even if the suffix is not nil, the new Timestamp object will
+    # always have nil as its suffix.
+    #
+    # :call-seq:
+    #     -(Time) -> Float
+    #     -(Timetamp) -> Float
+    #     -(Integer) -> Timestamp
+
+    def -(arg)
+      case arg
+      when Time
+        @time - arg
+      when Timestamp
+        @time - arg.time
+      when Integer
+        Timestamp.new(@time - arg, nil)
+      when NilClass
+        raise TypeError, "can't convert nil into an exact number"
+      else
+        raise ArgumentError, arg
+      end
+    end
+
+    ##
+    # Generates an array contains components of the Timestamp object.
+    # Components means "year", "mon", "day", "hour", "min", "sec", and
+    # "suffix".
+
+    def to_a
+      a = [:year, :mon, :day, :hour, :min, :sec, :suffix].map { |s| self.send(s) }
+      a.delete_at(-1) if a[-1].nil?
+      a
+    end
+
+    # :stopdoc:
+
+    # delegators to String object
+    
+    def_instance_delegators :@str, :size, :length
+    def_instance_delegators :@str, :include?, :match, :match?
+
+    # :startdoc:
+
+    ##
+    # Returns a character or sub-string specified with args.
+    #
+    # Following type of objects could be used as args:
+    #
+    # - Integer          : specifies an index
+    # - Integer, Integer : specified an start index and length of sub-string
+    # - Range            : specified range of sub-string
+    # - Symbol           : specified a type of part
+    #
+    # Following symbols could be specified:
+    #
+    # - :year
+    # - :mon, or :month
+    # - :day
+    # - :hour
+    # - :min
+    # - :sec
+    # - :suffix
+    #
+    # :call-seq:
+    #     self[nth as Integer] -> String | nil
+    #     self[nth as Integer, len as Integer] -> String | nil
+    #     self[range as Range] -> String
+    #     self[symbol as Symbol] -> String
+
+    def [](*args)
+      raise ArgumentError, "wrong number of arguments (given %s, execpted 1..2)" % args.size unless (1..2).include?(args.size)
+
+      arg = args[0]
+      case arg
+      when Symbol, String
+        key = arg.to_sym
+        if key == :suffix
+          @suffix.nil? ? nil : FMTSTRS[key] % @suffix
+        elsif FMTSTRS.keys.include?(key)
+          @time.strftime(FMTSTRS[key])
+        else
+          nil
+        end
+      else
+        @str[*args]
+      end
+    end
+
+    alias slice []
+
+    ##
+    # Returns a Timestamp object which has a next Time object.
+    #
+    # If true was passed as an argument, use incremented suffix as
+    # base instead of a next Time object.
+    #
+    # For example,
+    #
+    #     "20201110160100"     -> "20201110160101"     (false as arg)
+    #     "20201110160100"     -> "20201110160100_001" (true as arg)
+    #     "20201110160200_001" -> "20201110160201"     (false as arg)
+    #     "20201110160200_001" -> "20201110160200_002" (true as arg)
+    #
+    # If suffix was 999 before call this method, raises
+    # ArgumentRangeError.
+
+    def next(use_suffix = nil)
+      if use_suffix
+        Timestamp.new(@time, increase_suffix(@suffix.to_i, 1))
+      else
+        Timestamp.new(@time + 1, nil)
+      end
+    end
+
+    alias succ next
+
+    ##
+    # Updates the time value to a next Time destructively.  See the
+    # document for Timestamp#next for more details.
+    #
+    # If suffix was 999 before call this method, raises
+    # ArgumentRangeError.
+
+    def next!(use_suffix = nil)
+      if use_suffix
+        @suffix = increase_suffix(@suffix.to_i, 1)
+      else
+        @time += 1
+        @suffix = nil
+      end
+      @str = time_to_str(@time, @suffix)
+      self
+    end
+
+    alias succ! next!
+
+    ##
+    # Splits the timestamp string into array of time parts, such as
+    # year, month, day, hour, minute, and second.  Then, returns the
+    # array.
+    #
+    # When a block was passed, it would apply to each part of the
+    # array.  Then, returns self.
+
+    def split(_ = $;, _ = 0, &blk)
+      parts = Timestamp.split_stamp(@str)
+      if blk.nil?
+        parts
+      else
+        parts.each { |p| yield p }
+        self
+      end
+    end
+
+    # :stopdoc:
+
+    def initialize_copy(_)
+      @time = @time.dup
+      @suffix = @suffix
+      @str = @str.dup
+    end
+
+    def freeze;  @time.freeze;  @suffix.freeze;  @str.freeze;  end
+    def taint;   @time.taint;   @suffix.taint;   @str.taint;   end
+    def untaint; @time.untaint; @suffix.untaint; @str.untaint; end
+
+    private
+
+    def is_valid_suffix?(suffix)
+      suffix.nil? || (0..999).include?(suffix)
+    end
+
+    def increase_suffix(suffix, num)
+      increased = suffix + num
+      raise ArgumentRangeError, suffix unless is_valid_suffix?(increased)
+      increased
+    end
+
+    def time_to_str(time, suffix = nil)
       s = @time.strftime("%Y%m%d%H%M%S")
       s += "_#{"%03u" % @suffix}" unless @suffix.nil? || @suffix == 0
       s
     end
 
+    FMTSTRS = {
+      :year => "%Y", :mon => "%m", :month => "%m", :day => "%d",
+      :hour => "%H", :min => "%M", :sec => "%S", :suffix => "%03u",
+    }
+
+    # :startdoc:
     class << self
+
+      ##
+      # Returns a Timestamp object generated from the current time.
+
+      def now(suffix = nil)
+        Timestamp.new(Time.now, suffix)
+      end
+
       ##
       # Splits a string which represents a timestamp into components.
       # Each component represents a part of constructs to instantiate
@@ -79,7 +332,8 @@ module Textrepo
         raise InvalidTimestampStringError, stamp_str if stamp_str.nil?
         #    yyyy  mo    dd    hh    mi      ss      sfx
         a = [0..3, 4..5, 6..7, 8..9, 10..11, 12..13, 15..17].map {|r| stamp_str[r]}
-        a[-1].nil? ? a[0..-2] : a
+        a.delete_at(-1) if a[-1].nil?
+        a
       end
 
       ##
@@ -98,10 +352,17 @@ module Textrepo
           ye, mo, da, ho, mi, se, sfx = split_stamp(stamp_str).map(&:to_i)
           Timestamp.new(Time.new(ye, mo, da, ho, mi, se), sfx)
         rescue InvalidTimestampStringError, ArgumentError => _
-          raise InvalidTimestampStringError, stamp_str
+          emsg = if stamp_str.nil?
+            "(nil)"
+          elsif stamp_str.empty?
+            "(empty string)"
+          else
+            stamp_str
+          end
+          raise InvalidTimestampStringError, emsg
         end
       end
-
     end
+
   end
 end

data/lib/textrepo/version.rb

@@ -1,3 +1,3 @@
 module Textrepo
-  VERSION = '0.5.0'
+  VERSION = '0.5.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: textrepo
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.5
 platform: ruby
 authors:
 - mnbi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-01 00:00:00.000000000 Z
+date: 2020-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler