textrepo 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d26af6dd86e8b79c9e50300f8c31102bf79d5c751e175740a7225c2ca4a9b33
-  data.tar.gz: 8d398c0848c0a4b06d2a775f3cb6bf1f49489be7f5ba5d8cf7eab2aad068b5c7
+  metadata.gz: dc5cf6089b4883c93dc228e19aa0a149d71a8d9cc26a92e6c75fdc4ee0b2d694
+  data.tar.gz: 8ebecace02d486b6b6c12256d52adfd44963a3a14f6d39729b83d426bce3a26e
 SHA512:
-  metadata.gz: ef79855cd99ebc3baea4368c00cdc4d439478cfc9733d45eee1e7a08ca005bf0dc15824cb57b46326c982e724acc762b25b722c112f19ae4f67349d575fffdcb
-  data.tar.gz: 4af657999971e6d3cef41dc5d3ef7ea1017a536b772372d38e79ffb91196c239585a0c932fe10e42f9d7ccbfee8fa477ec31bd97afa9cd4e1c31f0c894772110
+  metadata.gz: aef27bf0363a66eeb1676ccda0682c253155875a8d0c16b27189674836edf2563b8df87b7f3b56cdb5d02c895f724f47a956588a5d97d24d83cdddce76fc083e
+  data.tar.gz: 81a4f8a76eb0ec8545e29ddbd537d49ec00f6009f5617dad61c61d8a5552c6df090d6d37fd507a7976c5f5f60b7d0c8b43f9a99d98d7efa1e933828270711d87

data/.gitignore

@@ -1,8 +1,57 @@
-/.bundle/
-/.yardoc
-/_yardoc/
+Gemfile.lock
+*.gem
+*.rbc
+/.config
 /coverage/
-/doc/
+/InstalledFiles
 /pkg/
 /spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
 /tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 Nothing to record here.
 
+## [0.5.0] - 2020-11-01
+### Added
+- Add a new API `Repository#search`.
+- Add a new API `Repository#exist?`. (0.4.3)
+
 ## [0.4.0] - 2020-10-14
 ### Added
 - Released to rubygems.org.

data/Rakefile

@@ -35,3 +35,11 @@ end
 task :clobber => :clean_sandbox
 CLOBBER << 'test/fixtures/notes'
 CLOBBER << 'test/fixtures/test_repo'
+
+require "rdoc/task"
+
+RDoc::Task.new do |rdoc|
+  rdoc.generator = "ri"
+  rdoc.rdoc_dir = "doc"
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end

data/lib/textrepo/error.rb

@@ -1,12 +1,39 @@
 module Textrepo
+
+  ##
+  # Following errors might occur in repository operations:
+  #   +---------------------------------+-----------------------+
+  #   | operation (args)                | error type            |
+  #   +---------------------------------+-----------------------+
+  #   | create (timestamp, text)        | Duplicate timestamp   |
+  #   |                                 | Empty text            |
+  #   +---------------------------------+-----------------------+
+  #   | read   (timestamp)              | Missing timestamp     |
+  #   +---------------------------------+-----------------------+
+  #   | update (timestamp, text)        | Mssing timestamp      |
+  #   |                                 | Empty text            |
+  #   +---------------------------------+-----------------------+
+  #   | delete (timestamp)              | Missing timestamp     |
+  #   +---------------------------------+-----------------------+
+  #   | search (pattern, stamp_pattern) | Invalid search result |
+  #   +---------------------------------+-----------------------+
+
   class Error < StandardError; end
 
+  # :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'
+    INVALID_TIMESTAMP_STRING = "invalid string as timestamp: %s"
+    INVALID_SEARCH_RESULT = "invalid result by searcher: %s"
   end
+  # :startdoc:
+
+  ##
+  # An error raised if unknown type was specified as the repository
+  # type.
 
   class UnknownRepoTypeError < Error
     def initialize(type)
@@ -14,20 +41,9 @@ module Textrepo
     end
   end
 
-  # Following errors might occur in repository operations:
-  # +--------------------------+---------------------+
-  # | operation (args)         | error type          |
-  # +--------------------------+---------------------+
-  # | create (timestamp, text) | Duplicate timestamp |
-  # |                          | Empty text          |
-  # +--------------------------+---------------------+
-  # | read   (timestamp)       | Missing timestamp   |
-  # +--------------------------+---------------------+
-  # | update (timestamp, text) | Mssing timestamp    |
-  # |                          | Empty text          |
-  # +--------------------------+---------------------+
-  # | delete (timestamp)       | Missing timestamp   |
-  # +--------------------------+---------------------+
+  ##
+  # An error raised if the specified timestamp has already exist in
+  # the repository.
 
   class DuplicateTimestampError < Error
     def initialize(timestamp)
@@ -35,16 +51,43 @@ module Textrepo
     end
   end
 
+  ##
+  # An error raised if the given text is empty.
+
   class EmptyTextError < Error
     def initialize
       super(ErrMsg::EMPTY_TEXT)
     end
   end
 
+  ##
+  # An error raised if the given timestamp has not exist in the
+  # repository.
+
   class MissingTimestampError < Error
     def initialize(timestamp)
       super(ErrMsg::MISSING_TIMESTAMP % timestamp)
     end
   end
 
+  ##
+  # An error raised if an argument is invalid to convert a
+  # Textrepo::Timestamp object.
+
+  class InvalidTimestampStringError < Error
+    def initialize(str)
+      super(ErrMsg::INVALID_TIMESTAMP_STRING % str)
+    end
+  end
+
+  ##
+  # An error raise if the search result is not suitable to use.
+  #
+
+  class InvalidSearchResultError < Error
+    def initialize(str)
+      super(ErrMsg::INVALID_SEARCH_RESULT % str)
+    end
+  end
+
 end

data/lib/textrepo/file_system_repository.rb

@@ -1,26 +1,89 @@
 require 'fileutils'
+require "open3"
 
 module Textrepo
-  # A concrete repository which uses the default file system as a storage.
+
+  ##
+  # A concrete class which implements Repository interfaces.  This
+  # repository uses the default file system of the operating system as
+  # a text storage.
+
   class FileSystemRepository < Repository
-    attr_reader :path, :extname
+
+    ##
+    # Repository root.
+
+    attr_reader :path
+
+    ##
+    # Extension of notes sotres in the repository.
+
+    attr_reader :extname
+
+    ##
+    # Searcher program name.
+
+    attr_reader :searcher
+
+    ##
+    # An array of options to pass to the searcher program.
+
+    attr_reader :searcher_options
+
+    ##
+    # Default name for the repository which uses when no name is
+    # specified in the configuration settings.
 
     FAVORITE_REPOSITORY_NAME = 'notes'
+
+    ##
+    # Default extension of notes which uses when no extname is
+    # specified in the configuration settings.
+
     FAVORITE_EXTNAME = 'md'
 
-    # `conf` must be a Hash object.  It must hold the follwoing
-    # values:
+    ##
+    # Default searcher program to search text in the repository.
+
+    FAVORITE_SEARCHER = 'grep'
+
+    ##
+    # Creates a new repository object.  The argument, `conf` must be a
+    # Hash object.  It should hold the follwoing values:
     #
-    # - :repository_type (:file_system)
-    # - :repository_name => basename of the root path for the repository
-    # - :repository_base => the parent directory path for the repository
-    # - :default_extname => extname for a file stored into in the repository
+    # - MANDATORY:
+    #   - :repository_type => `:file_system`
+    #   - :repository_base => the parent directory path for the repository
+    # - OPTIONAL: (if not specified, default values are used)
+    #   - :repository_name => basename of the root path for the repository
+    #   - :default_extname => extname for a file stored into in the repository
+    #   - :searcher => a program to search like `grep`
+    #   - :searcher_options => an Array of option to pass to the searcher
     #
     # The root path of the repository looks like the following:
     # - conf[:repository_base]/conf[:repository_name]
     # 
-    # Default values are set when `repository_name` and `default_extname`
+    # Default values are set when `:repository_name` and `:default_extname`
     # 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:
+    #
+    #   "grep"   => ["-i", "-n", "-R", "-E"]
+    #   "egrep"  => ["-i", "-n", "-R"]
+    #   "ggrep"  => ["-i", "-n", "-R", "-E"]
+    #   "gegrep" => ["-i", "-n", "-R"]
+    #   "rg"     => ["-S", "-n", "--no-heading", "--color", "never"]
+    #
+    # If use those 3 searchers, it is not recommended to set
+    # `:searcher_options`.  The default value works well in
+    # `textrepo`.
+    #
+    # :call-seq:
+    #     new(Hash or Hash like object) -> FileSystemRepository
+
     def initialize(conf)
       super
       base = conf[:repository_base]
@@ -28,14 +91,17 @@ module Textrepo
       @path = File.expand_path("#{name}", base)
       FileUtils.mkdir_p(@path)
       @extname = conf[:default_extname] || FAVORITE_EXTNAME
+      @searcher = find_searcher(conf[:searcher])
+      @searcher_options = conf[:searcher_options]
     end
 
-    #
-    # repository operations
-    #
-
+    ##
     # Creates a file into the repository, which contains the specified
     # text and is associated to the timestamp.
+    #
+    # :call-seq:
+    #     create(Timestamp, Array) -> Timestamp
+
     def create(timestamp, text)
       abs = abspath(timestamp)
       raise DuplicateTimestampError, timestamp if FileTest.exist?(abs)
@@ -45,8 +111,13 @@ module Textrepo
       timestamp
     end
 
+    ##
     # Reads the file content in the repository.  Then, returns its
     # content.
+    #
+    # :call-seq:
+    #     read(Timestamp) -> Array
+
     def read(timestamp)
       abs = abspath(timestamp)
       raise MissingTimestampError, timestamp unless FileTest.exist?(abs)
@@ -57,8 +128,13 @@ module Textrepo
       content
     end
 
+    ##
     # Updates the file content in the repository.  A new timestamp
     # will be attached to the text.
+    #
+    # :call-seq:
+    #     update(Timestamp, Array) -> Timestamp
+
     def update(timestamp, text)
       raise EmptyTextError if text.empty?
       org_abs = abspath(timestamp)
@@ -75,7 +151,12 @@ module Textrepo
       new_stamp
     end
 
+    ##
     # Deletes the file in the repository.
+    #
+    # :call-seq:
+    #     delete(Timestamp) -> Array
+
     def delete(timestamp)
       abs = abspath(timestamp)
       raise MissingTimestampError, timestamp unless FileTest.exist?(abs)
@@ -86,7 +167,12 @@ module Textrepo
       content
     end
 
+    ##
     # Finds entries of text those timestamp matches the specified pattern.
+    #
+    # :call-seq:
+    #     entries(String = nil) -> Array of Timestamp instances
+
     def entries(stamp_pattern = nil)
       results = []
 
@@ -94,7 +180,7 @@ module Textrepo
       when "yyyymoddhhmiss_lll".size
         stamp = Timestamp.parse_s(stamp_pattern)
         if exist?(stamp)
-          results << stamp.to_s
+          results << stamp
         end
       when 0, "yyyymoddhhmiss".size, "yyyymodd".size
         results += find_entries(stamp_pattern)
@@ -117,12 +203,54 @@ module Textrepo
       results
     end
 
+    ##
+    # Check the existence of text which is associated with the given
+    # timestamp.
+    #
+    # :call-seq:
+    #     exist?(Timestamp) -> true or false
+
+    def exist?(timestamp)
+      FileTest.exist?(abspath(timestamp))
+    end
+
+    ##
+    # Searches a pattern in all text.  The given pattern is a word to
+    # search or a regular expression.  The pattern would be passed to
+    # a searcher program as it passed.
+    #
+    # See the document for Textrepo::Repository#search to know about
+    # the search result.
+    #
+    # :call-seq:
+    #     search(String for pattern, String for Timestamp pattern) -> Array
+
+    def search(pattern, stamp_pattern = nil)
+      result = nil
+      if stamp_pattern.nil?
+        result = invoke_searcher_at_repo_root(@searcher, pattern)
+      else
+        result = invoke_searcher_for_entries(@searcher, pattern, entries(stamp_pattern))
+      end
+      construct_search_result(result)
+    end
+
+    # :stopdoc:
+
     private
     def abspath(timestamp)
-      filename = timestamp.to_pathname + ".#{@extname}"
+      filename = timestamp_to_pathname(timestamp) + ".#{@extname}"
       File.expand_path(filename, @path)
     end
 
+    #  %Y   %m %d %H %M %S  suffix        %Y/%m/  %Y%m%d%H%M%S %L
+    # "2020-12-30 12:34:56  (0 | nil)" => "2020/12/20201230123456"
+    # "2020-12-30 12:34:56  (7)"       => "2020/12/20201230123456_007"
+    def timestamp_to_pathname(timestamp)
+      yyyy, mo = Timestamp.split_stamp(timestamp.to_s)[0..1]
+      File.join(yyyy, mo, timestamp.to_s)
+    end
+
     def write_text(abs, text)
       FileUtils.mkdir_p(File.dirname(abs))
       File.open(abs, 'w') { |f|
@@ -134,15 +262,156 @@ module Textrepo
       File.basename(text_path).delete_suffix(".#{@extname}")
     end
 
-    def exist?(timestamp)
-      FileTest.exist?(abspath(timestamp))
-    end
-
     def find_entries(stamp_pattern)
       Dir.glob("#{@path}/**/#{stamp_pattern}*.#{@extname}").map { |e|
-        timestamp_str(e)
+        begin
+          Timestamp.parse_s(timestamp_str(e))
+        rescue InvalidTimestampStringError => _
+          # Just ignore the erroneous entry, since it is not a text in
+          # the repository.  It may be a garbage, or some kind of
+          # hidden stuff of the repository, ... etc.
+          nil
+        end
+      }.compact
+    end
+
+    ##
+    # The upper limit of files to search at one time.  The value has
+    # no reason to select.  It seems to me that not too much, not too
+    # little to handle in one process to search.
+
+    LIMIT_OF_FILES = 20
+
+    ##
+    # When no timestamp pattern was given, invoke the searcher with
+    # the repository root path as its argument and the recursive
+    # searching option.  The search could be done in only one process.
+
+    def invoke_searcher_at_repo_root(searcher, pattern)
+      o, s = Open3.capture2(searcher, *find_searcher_options(searcher),
+                            pattern, @path)
+      output = []
+      output += o.lines.map(&:chomp) if s.success? && (! o.empty?)
+      output
+    end
+
+    ##
+    # When a timestamp pattern was given, at first, list target files,
+    # then invoke the searcher for those files.  Since the number of
+    # target files may be so much, it seems to be dangerous to pass
+    # all of them to a single search process at one time.
+    #
+    # One more thing to mention, the searcher, like `grep`, does not
+    # add the filename at the beginning of the search result line, if
+    # the target is one file.  This behavior is not suitable in this
+    # purpose.  The code below adds the filename when the target is
+    # one file.
+
+    def invoke_searcher_for_entries(searcher, pattern, entries)
+      output = []
+
+      num_of_entries = entries.size
+      if num_of_entries == 1
+        # If the search taget is one file, the output needs special
+        # treatment.
+        file = abspath(entries[0])
+        o, s = Open3.capture2(searcher, *find_searcher_options(searcher),
+                              pattern, file)
+        if s.success? && (! o.empty)
+          output += o.lines.map { |line|
+            # add filename at the beginning of the search result line
+            [file, line.chomp].join(":")
+          }
+        end
+      elsif num_of_entries > LIMIT_OF_FILES
+        output += invoke_searcher_for_entries(searcher, pattern, entries[0..(LIMIT_OF_FILES - 1)])
+        output += invoke_searcher_for_entries(searcher, pattern, entries[LIMIT_OF_FILES..-1])
+      else
+        # When the number of target is less than the upper limit,
+        # invoke the searcher with all of target files as its
+        # arguments.
+        files = find_files(entries)
+        o, s = Open3.capture2(searcher, *find_searcher_options(searcher),
+                              pattern, *files)
+        if s.success? && (! o.empty)
+          output += o.lines.map(&:chomp)
+        end
+      end
+
+      output
+    end
+
+    SEARCHER_OPTS = {
+      # case insensitive, print line number, recursive search, work as egrep
+      "grep"   => ["-i", "-n", "-R", "-E"],
+      # case insensitive, print line number, recursive search
+      "egrep"  => ["-i", "-n", "-R"],
+      # case insensitive, print line number, recursive search, work as gegrep
+      "ggrep"  => ["-i", "-n", "-R", "-E"],
+      # case insensitive, print line number, recursive search
+      "gegrep" => ["-i", "-n", "-R"],
+      # smart case, print line number, no color
+      "rg"     => ["-S", "-n", "--no-heading", "--color", "never"],
+    }
+
+    def find_searcher_options(searcher)
+      @searcher_options || SEARCHER_OPTS[File.basename(searcher)] || ""
+    end
+
+    def find_files(timestamps)
+      timestamps.map{|stamp| abspath(stamp)}
+    end
+
+    ##
+    # The argument must be an Array contains the searcher output.
+    # Each item is constructed from 3 parts:
+    #   "<pathname>:<integer>:<text>"
+    #
+    # For example, it may looks like:
+    #
+    #   "/somewhere/2020/11/20201101044300.md:18:foo is foo"
+    #
+    # Or it may contains more ":" in the text part as:
+    #
+    #   "/somewhere/2020/11/20201101044500.md:119:apple:orange:grape"
+    #
+    # In the latter case, `split(":")` will split it too much.  That is,
+    # the result will be:
+    #
+    #  ["/somewhere/2020/11/20201101044500.md", "119", "apple", "orange", "grape"]
+    #
+    # Text part must be joined with ":".
+
+    def construct_search_result(output)
+      output.map { |line|
+        begin
+          pathname, num, *match_text = line.split(":")
+          [Timestamp.parse_s(timestamp_str(pathname)),
+           num.to_i,
+           match_text.join(":")]
+        rescue InvalidTimestampStringError, TypeError => _
+          raise InvalidSearchResultError, [@searcher, @searcher_options.join(" ")].join(" ")
+        end
+      }.compact
+    end
+
+    def find_searcher(program = nil)
+      candidates = [FAVORITE_SEARCHER]
+      candidates.unshift(program) unless program.nil? || candidates.include?(program)
+      search_paths = ENV["PATH"].split(":")
+      candidates.map { |prog|
+        find_in_paths(prog, search_paths)
+      }[0]
+    end
+
+    def find_in_paths(prog, paths)
+      paths.each { |p|
+        abspath = File.expand_path(prog, p)
+        return abspath if FileTest.exist?(abspath) && FileTest.executable?(abspath)
       }
+      nil
     end
+    # :startdoc:
 
   end
 end

data/lib/textrepo/repository.rb

@@ -1,31 +1,72 @@
 module Textrepo
   class Repository
-    attr_reader :type, :name
+
+    ##
+    # Repository type.  It specifies which concrete repository class
+    # will instantiated.  For example, the type `:file_system` specifies
+    # `FileSystemRepository`.
+
+    attr_reader :type
+
+    ##
+    # Repository name.  The usage of the value of `name` depends on a
+    # concrete repository class.  For example, `FileSystemRepository`
+    # uses it as a part of the repository path.
+
+    attr_reader :name
+
+    ##
+    # Create a new repository.  The argument must be an object which
+    # can be accessed like a Hash object.
 
     def initialize(conf)
       @type = conf[:repository_type]
       @name = conf[:repository_name]
     end
 
+    ##
     # Stores text data into the repository with the specified timestamp.
     # Returns the timestamp.
+    #
+    # :call-seq:
+    #     create(Timestamp, Array) -> Timestamp
+
     def create(timestamp, text); timestamp; end
 
+    ##
     # Reads text data from the repository, which is associated to the
     # timestamp.  Returns an array which contains the text.
+    #
+    # :call-seq:
+    #     read(Timestamp) -> Array
+
     def read(timestamp); []; end
 
+    ##
     # Updates the content with text in the repository, which is
     # associated to the timestamp.  Returns the timestamp.
+    #
+    # :call-seq:
+    #     update(Timestamp, Array) -> Timestamp
+
     def update(timestamp, text); timestamp; end
 
+    ##
     # Deletes the content in the repository, which is associated to
     # the timestamp.  Returns an array which contains the deleted text.
+    #
+    # :call-seq:
+    #     delete(Timestamp) -> Array
+
     def delete(timestamp); []; end
 
+    ##
     # Finds all entries of text those have timestamps which mathes the
     # specified pattern of timestamp.  Returns an array which contains
-    # timestamps.  A pattern must be one of the following:
+    # instances of Timestamp.  If none of text was found, an empty
+    # array would be returned.
+    #
+    #  A pattern must be one of the following:
     #
     #     - yyyymoddhhmiss_lll : whole stamp
     #     - yyyymoddhhmiss     : omit millisecond part
@@ -37,17 +78,50 @@ module Textrepo
     # If `stamp_pattern` is omitted, the recent entries will be listed.
     # Then, how many entries are listed depends on the implementaiton
     # of the concrete repository class.
+    #
+    # :call-seq:
+    #     entries(String) -> Array of Timestamp instances
+
     def entries(stamp_pattern = nil); []; end
 
+    ##
+    # Check the existence of text which is associated with the given
+    # timestamp.
+    #
+    # :call-seq:
+    #     exist?(Timestamp) -> true or false
+
+    def exist?(timestamp); false; end
+
+    ##
+    # Searches a pattern (word or regular expression) in text those
+    # matches to a given timestamp pattern.  Returns an Array of
+    # search results.  If no match, returns an empty Array.
+    #
+    # See the document for Repository#entries about a timestamp
+    # pattern.  When nil is passed as a timestamp pattern, searching
+    # applies to all text in the repository.
+    #
+    # Each entry of the result Array is constructed from 3 items, (1)
+    # timestamp (Timestamp), (2) line number (Integer), (3) matched
+    # line (String).
+    #
+    # :call-seq:
+    #     search(String for pattern, String for Timestamp pattern) -> Array
+
+    def search(pattern, stamp_pattern = nil); []; end
+
   end
 
   require_relative 'file_system_repository'
 
+  ##
   # Returns an instance which derived from Textrepo::Repository class.
-  # `conf` must be a Hash object which has a value of
-  # `:repository_type` and `:repository_name` at least.  Some concrete
-  # class derived from Textrepo::Repository may require more key-value
-  # pairs in `conf`.
+  # `conf` must be an object which can be accessed like a Hash object.
+  # And it must also has a value of `:repository_type` and
+  # `:repository_name` at least.  Some concrete class derived from
+  # Textrepo::Repository may require more key-value pairs in `conf`.
+
   def init(conf)
     type = conf[:repository_type]
     klass_name = type.to_s.split(/_/).map(&:capitalize).join + "Repository"

data/lib/textrepo/timestamp.rb

@@ -1,17 +1,47 @@
 module Textrepo
+  ##
+  # Timestamp is generated from a Time object.  It converts a time to
+  # string in the obvious format, such "20201023122400".
+  #
+  # Since the obvious format contains only year, month, day, hour,
+  # minute, and second, the resolution of time is a second.  That is,
+  # two Time object those are different only in second will generates
+  # equal Timestamp objects.
+  #
+  # If a client program of Textrepo::Timestamp wants to distinguish
+  # those Time objects, an attribute `suffix` could be used.
+  #
+  # For example, the `suffix` will be converted into a 3 character
+  # string, such "012", "345", "678", ... etc.  So, millisecond part
+  # of a Time object will be suitable to pass as `suffix` when
+  # creating a Timestamp object.
+
   class Timestamp
     include Comparable
 
-    attr_reader :time, :suffix
+    ##
+    # Time object which generates the Timestamp object.
+
+    attr_reader :time
+
+    ##
+    # An integer specified in `new` method to create the Timestamp object.
+
+    attr_reader :suffix
+
+    ##
+    # Creates a Timestamp object from a Time object.  In addition, an
+    # Integer can be passed as a suffix use.
+    #
+    # :call-seq:
+    #   new(Time, Integer = nil) -> Timestamp
 
-    # time: a Time instance
-    # suffix: an Integer instance
     def initialize(time, suffix = nil)
       @time = time
       @suffix = suffix
     end
 
-    def <=>(other)
+    def <=>(other)              # :nodoc:
       result = (self.time <=> other.time)
 
       sfx = self.suffix || 0
@@ -20,44 +50,58 @@ module Textrepo
       result == 0 ? (sfx <=> osfx) : result
     end
 
-    #  %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"
+    ##
+    # Generate 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
       s = @time.strftime("%Y%m%d%H%M%S")
       s += "_#{"%03u" % @suffix}" unless @suffix.nil? || @suffix == 0
       s
     end
 
-    #  %Y   %m %d %H %M %S  suffix        %Y/%m/  %Y%m%d%H%M%S %L
-    # "2020-12-30 12:34:56  (0 | nil)" => "2020/12/20201230123456"
-    # "2020-12-30 12:34:56  (7)"       => "2020/12/20201230123456_007"
-    def to_pathname
-      @time.strftime("%Y/%m/") + self.to_s
-    end
-
     class << self
-      #  yyyymoddhhmiss sfx      yyyy    mo    dd    hh    mi    ss    sfx
-      # "20201230123456"     => "2020", "12", "30", "12", "34", "56"
-      # "20201230123456_789" => "2020", "12", "30", "12", "34", "56", "789"
+      ##
+      # Splits a string which represents a timestamp into components.
+      # Each component represents a part of constructs to instantiate
+      # a Time object.
+      #
+      #    yyyymoddhhmiss sfx      yyyy    mo    dd    hh    mi    ss    sfx
+      #   "20201230123456"     -> "2020", "12", "30", "12", "34", "56"
+      #   "20201230123456_789" -> "2020", "12", "30", "12", "34", "56", "789"
+      #
+      # Raises InvalidTimestampStringError if nil was passed as an arguemnt.
+
       def split_stamp(stamp_str)
+        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
       end
 
+      ##
+      # Generate a Timestamp object from a string which represents a
+      # timestamp, such "20201028163400".
+      #
+      # Raises InvalidTimestampStringError if cannot convert the
+      # argument into a Timestamp object.
+      #
+      # :call-seq:
+      #     parse_s("20201028163400") -> Timestamp
+      #     parse_s("20201028163529_034") -> Timestamp
+
       def parse_s(stamp_str)
-        year, mon, day, hour, min, sec , sfx = split_stamp(stamp_str).map(&:to_i)
-        Timestamp.new(Time.new(year, mon, day, hour, min, sec), sfx)
+        begin
+          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
+        end
       end
 
-      #                      (-2)
-      #  0       8           |(-1)
-      #  V       V           VV
-      # "2020/12/20201230123456" => "2020-12-30 12:34:56"
-      def parse_pathname(pathname)
-        parse_s(pathname[8..-1])
-      end
     end
   end
 end

data/lib/textrepo/version.rb

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

data/textrepo.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["mnbi@users.noreply.github.com"]
 
   spec.summary       = %q{A repository to store text with timestamp.}
-  spec.description   = %q{Textrepo is a repository to store text with timestamp.  It can manage text with the attached timestamp (read/update/delte).}
+  spec.description   = %q{Textrepo is a repository to store text with timestamp.  It can manage text with the attached timestamp (create/read/update/delete).}
   spec.homepage      = "https://github.com/mnbi/textrepo"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: textrepo
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - mnbi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-10-15 00:00:00.000000000 Z
+date: 2020-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.1'
 description: Textrepo is a repository to store text with timestamp.  It can manage
-  text with the attached timestamp (read/update/delte).
+  text with the attached timestamp (create/read/update/delete).
 email:
 - mnbi@users.noreply.github.com
 executables: []
@@ -36,7 +36,6 @@ files:
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile

data/Gemfile.lock

@@ -1,22 +0,0 @@
-PATH
-  remote: .
-  specs:
-    textrepo (0.4.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    minitest (5.14.2)
-    rake (13.0.1)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.1)
-  minitest (~> 5.0)
-  rake (~> 13.0)
-  textrepo!
-
-BUNDLED WITH
-   2.1.4