reaching a milestone for unix_path.rb

Author: rwh

lib/compsci/unix_path.rb

@@ -1,30 +1,98 @@
 module CompSci
 
+  # This is a simplification of common Unix paths, as used in Linux, OS X, etc.
+  # It is intended to cover 99.9% of the "good use cases" and "best practices"
+  #   for path and filename conventions on Unix filesystems.
+
+  # Some primary distinctions:
+  #   1. Absolute vs Relative paths
+  #   2. File vs directory
+
+  # Absolute paths are indicated with a leading slash (/)
+  # Relative paths are primarily indicated with a leading dot-slash (./)
+  #   or they may omit the leading ./ for brevity.
+
+  # In string form, directories are indicated with a trailing slash (/).
+  # With no trailing slash, the last segment of a path is treated as a filename.
+  # Internally, there is a @filename string, and if it is empty, this has
+  #   semantic meaning: the UnixPath is a directory.
+
+  # For nonempty @filename, it may be further broken down into basename
+  #   and extension, with an overly simple rule:
+  #
+  #                    Look for the last dot.
+  #
+  # Everything up to the last dot is basename.  Possibly the entire filename.
+  # Possibly empty.
+  #
+  # Everything after the last dot is extension, including the last dot.
+  # Possibly the entire filename. Possibly empty.
+  #
+  # Concatenating basename and extension will always perfectly reconstruct
+  #   the filename.
+  #
+  # If @filename is empty, basename and extension are nil.
+
+  # Internal Representation
+  #   * abs: boolean indicating abspath vs relpath
+  #   * subdirs: array of strings, like %w[home user docs]
+  #   * filename: string, possibly empty
+
+  # Consume a string path with UnixPath.parse, creating a UnixPath instance.
+  # Emit a string with UnixPath#to_s.
+  # Relative paths are emitted with leading ./
+
+  # Combine path components with `slash`, aliased to /, yielding a UnixPath
+  #   * UnixPath.parse('/etc') / 'systemd' / 'system'
+  #   * UnixPath.parse('/etc').slash('passwd')
+  #   * UnixPath.parse('./') / 'a.out'
+  #
+  # Or just parse the full string:
+  #   * UnixPath.parse('/etc/systemd/system')
+  #
+  # Or construct by hand:
+  #   * UnixPath.new(abs: true, subdirs: %w[etc systemd system])
+
+  # Most of UnixPath is implemented via PathMixin and its FactoryMethods
+  # These modules are mixed in to base classes ImmutablePath and MutablePath.
+  # ImmutablePath is based on Ruby's Data.define, using Data.with for efficient
+  #   copies.
+  # MutablePath may be more efficient and has a simple implementation.
+  # UnixPath is itself a constant, currently referring to ImmutablePath.
+  # This pattern of assigning a constant can allow you to create your own Path
+  #   in your own context.  e.g. MyPath = CompSci::MutablePath
+
+  # Note that these are logical paths and have no connection to any filesystem.
+  # This library never looks at the local filesystem that it runs on.
+
   # ImmutablePath and MutablePath both mix in this module via include
   # N.B. @ivar references will not work with Data.define, so use self.ivar
   module PathMixin
     include Comparable
 
-    class Error < RuntimeError; end
-    class FilenameError < Error; end
-    class SlashError < Error; end
+    class FilenameError < RuntimeError; end
 
     SEP = '/'
     DOT = '.'
     CWD = DOT + SEP
 
-    # must be a String != '.'
+    # must be a String != DOT
     def self.valid_filename!(val)
       if !val.is_a?(String) or val == DOT
         raise(FilenameError, "illegal value: #{val.inspect}")
       end
       val
     end
 
+    #
+    # module FactoryMethods: create new Paths
+    #
+
     # ImmutablePath and MutablePath both mix in this module via extend
     # This ensures self.new refers to the base class and not the mixin (module)
     # This extension happens automatically via an included hook on PathMixin
     # PathMixin#slash calls FactoryMethods#parse
+    #
     module FactoryMethods
       # return a new Path from a string
       def parse(path_str)
@@ -54,6 +122,10 @@ def directory(path)
       end
     end
 
+    #
+    # module PathMixin: provides most of the Path instance behavior
+    #
+
     # the base class automatically gets FactoryMethods at the "class layer"
     def self.included(base) = base.extend(FactoryMethods)
 
@@ -91,7 +163,6 @@ def <=>(other)
     # Enable path building with slash method
     # !!! base class must implement Klass#slash_path !!!
     def slash(other)
-      raise(SlashError, "can only slash on dirs") unless self.dir?
       case other
       when String
         other.empty? ? self : self.slash_path(self.class.parse(other))
@@ -121,6 +192,11 @@ def extension
     def reconstruct_filename = [self.basename, self.extension].join
   end
 
+
+  #
+  # ImmutablePath (Data)
+  #
+
   class ImmutablePath < Data.define(:abs, :subdirs, :filename)
     include PathMixin # also extends PathMixin::FactoryMethods
 
@@ -131,8 +207,11 @@ def initialize(**kwargs)
 
     # rely on Data#with for efficient copying
     def slash_path(other)
-      raise(SlashError, "can't slash an absolute path") if other.abs?
-      self.with(subdirs: subdirs + other.subdirs, filename: other.filename)
+      # nonempty filename is now a subdir
+      dirs = self.subdirs
+      dirs << self.filename unless self.filename.empty?
+      dirs += other.subdirs
+      self.with(subdirs: dirs, filename: other.filename)
     end
   end
 
@@ -154,13 +233,16 @@ def filename=(val)
 
     # simple update
     def slash_path(other)
-      raise(SlashError, "can't slash an absolute path") if other.abs?
+      @subdirs << @filename unless @filename.empty?
       @subdirs += other.subdirs
       @filename = other.filename
       self
     end
   end
 
-  # UnixPath = ImmutablePath
-  UnixPath = MutablePath
+  # you can do this too, in your own context:
+  # MyUnixPath = CompSci::MutablePath
+
+  UnixPath = ImmutablePath
+  # UnixPath = MutablePath
 end

test/unix_path.rb

@@ -1,36 +1,89 @@
 require 'minitest/autorun'
-require 'compsci/unix_path_immutable'
+require 'compsci/unix_path'
 
 include CompSci
 
-CASES = {
-  '/'                      => [true, [], ''],
-  '/home/'                 => [true, %w[home], ''],
-  '/home/user/documents'   => [true, %w[home user], 'documents'],
-  '/home/user/documents/'  => [true, %w[home user documents], ''],
-  '/home/user/file.txt'    => [true, %w[home user], 'file.txt'],
-  'relative_dir/'          => [false, %w[relative_dir], ''],
-  'relative_file'          => [false, [], 'relative_file'],
-  'relative_dir/file.txt'  => [false, %w[relative_dir], 'file.txt'],
-  'relative_dir/file.txt/' => [false, %w[relative_dir file.txt], ''],
-  'file.txt'               => [false, [], 'file.txt'],
-  '.bashrc'                => [false, [], '.bashrc'],
-  '/home/user/.bashrc'     => [true, %w[home user], '.bashrc'],
-  '/home/user/.config/'    => [true, %w[home user .config], ''],
-  './file.txt'             => [false, [], 'file.txt'],
-  './.emacs'               => [false, [], '.emacs'],
-  './././././file.txt'     => [false, [], 'file.txt'],
-  '/././etc/passwd'        => [true, %w[etc], 'passwd'],
-}
+# Helper method to run parsing tests
+def assert_parsing(cases)
+  cases.each { |str, (abs, subdirs, filename)|
+    path = UnixPath.parse(str)
+    expect(path.abs).must_equal abs
+    expect(path.subdirs).must_equal subdirs
+    expect(path.filename).must_equal filename
+  }
+end
+
+def assert_filenames(cases)
+  cases.each do |filename, (base, ext)|
+    path = UnixPath.parse(filename)
+    expect(path.basename).must_equal base
+    expect(path.extension).must_equal ext
+  end
+end
 
 describe UnixPath do
-  it "parses the most common well-formed cases properly" do
-    CASES.each { |str, tuple|
-      path = UnixPath.parse(str)
-      expect(path.abs).must_equal tuple[0]
-      expect(path.subdirs).must_equal tuple[1]
-      expect(path.filename).must_equal tuple[2]
+  it "parses absolute paths with leading slash" do
+    cases = {
+      '/'                      => [true, [], ''],
+      '/home/'                 => [true, %w[home], ''],
+      '/home/user/documents'   => [true, %w[home user], 'documents'],
+      '/home/user/documents/'  => [true, %w[home user documents], ''],
+      '/home/user/file.txt'    => [true, %w[home user], 'file.txt'],
+      '/home/user/.bashrc'     => [true, %w[home user], '.bashrc'],
+      '/home/user/.config/'    => [true, %w[home user .config], ''],
+      '/././etc/passwd'        => [true, %w[etc], 'passwd'],
+    }
+    assert_parsing(cases)
+  end
+
+  it "parses relative paths with leading dot-slash" do
+    cases = {
+      './file.txt'             => [false, [], 'file.txt'],
+      './.emacs'               => [false, [], '.emacs'],
+      './././././file.txt'     => [false, [], 'file.txt'],
+    }
+    assert_parsing(cases)
+  end
+
+  it "parses relative paths with no leading slash" do
+    cases = {
+      'relative_dir/'          => [false, %w[relative_dir], ''],
+      'relative_file'          => [false, [], 'relative_file'],
+      'relative_dir/file.txt'  => [false, %w[relative_dir], 'file.txt'],
+      'relative_dir/file.txt/' => [false, %w[relative_dir file.txt], ''],
+      'file.txt'               => [false, [], 'file.txt'],
+      '.bashrc'                => [false, [], '.bashrc'],
     }
+    assert_parsing(cases)
+  end
+
+  it "parses directories with trailing slash; filename is empty" do
+    cases = {
+      '/'                      => [true, [], ''],
+      '/home/'                 => [true, %w[home], ''],
+      '/home/user/documents/'  => [true, %w[home user documents], ''],
+      'relative_dir/'          => [false, %w[relative_dir], ''],
+      'relative_dir/file.txt/' => [false, %w[relative_dir file.txt], ''],
+      '/home/user/.config/'    => [true, %w[home user .config], ''],
+    }
+    assert_parsing(cases)
+  end
+
+  it "parses filenames with no trailing slash; nonempty filename" do
+    cases = {
+      '/home/user/documents'   => [true, %w[home user], 'documents'],
+      '/home/user/file.txt'    => [true, %w[home user], 'file.txt'],
+      'relative_file'          => [false, [], 'relative_file'],
+      'relative_dir/file.txt'  => [false, %w[relative_dir], 'file.txt'],
+      'file.txt'               => [false, [], 'file.txt'],
+      '.bashrc'                => [false, [], '.bashrc'],
+      '/home/user/.bashrc'     => [true, %w[home user], '.bashrc'],
+      './file.txt'             => [false, [], 'file.txt'],
+      './.emacs'               => [false, [], '.emacs'],
+      './././././file.txt'     => [false, [], 'file.txt'],
+      '/././etc/passwd'        => [true, %w[etc], 'passwd'],
+    }
+    assert_parsing(cases)
   end
 
   it "leads with a dot for all relpaths" do
@@ -42,4 +95,88 @@
     path = UnixPath.new(abs: true, subdirs: %w[path to], filename: 'file.txt')
     expect(path.to_s.start_with? '/').must_equal true
   end
+
+  it "concatenates paths with chained slash calls" do
+    base = UnixPath.parse("./src/")
+    expect(base.abs?).must_equal false
+    expect(base.dir?).must_equal true
+
+    # check this out!
+    full = base / 'components' / 'forms' / 'LoginForm.js'
+
+    expect(full.abs?).must_equal false
+    expect(full.dir?).must_equal false
+
+    if base.is_a? MutablePath
+      expect(base).must_equal full
+    elsif base.is_a? ImmutablePath
+      expect(base).wont_equal full
+    end
+
+    expect(full.to_s).must_equal "./src/components/forms/LoginForm.js"
+  end
+
+  describe 'empty filename' do
+    it "indicates a directory when empty" do
+      path = UnixPath.parse("/home/user/docs/")
+      expect(path.dir?).must_equal true
+      expect(path.filename).must_equal ""
+    end
+
+    it "has neither basename nor extension" do
+      path = UnixPath.parse("/home/user/docs/")
+      expect(path.basename).must_be_nil
+      expect(path.extension).must_be_nil
+    end
+  end
+
+  describe 'nonempty filename' do
+    it "is illegal to be a single dot" do
+      expect { UnixPath.parse('.') }.must_raise
+      expect { UnixPath.parse('/etc/.') }.must_raise
+
+      # . is fine as dir
+      expect(UnixPath.parse('/etc/./').to_s).must_equal '/etc/'
+    end
+
+    it "extracts basename for regular files" do
+      path = UnixPath.parse("file.txt")
+      expect(path.basename).must_equal "file"
+    end
+
+    it "extracts basename for dotfiles" do
+      path = UnixPath.parse(".bashrc")
+      expect(path.basename).must_equal ""
+    end
+
+    it "extracts basename for multiple extensions" do
+      path = UnixPath.parse("archive.tar.gz")
+      expect(path.basename).must_equal "archive.tar"
+    end
+
+    it "extracts basename for files without extensions" do
+      path = UnixPath.parse("/etc/passwd")
+      expect(path.basename).must_equal "passwd"
+    end
+
+    it "extracts extension for regular files" do
+      path = UnixPath.parse("file.txt")
+      expect(path.extension).must_equal ".txt"
+    end
+
+    it "extracts extension for dotfiles" do
+      path = UnixPath.parse(".bashrc")
+      expect(path.extension).must_equal ".bashrc"
+    end
+
+    it "extracts extension for multiple extensions" do
+      path = UnixPath.parse("archive.tar.gz")
+      expect(path.extension).must_equal ".gz"
+    end
+
+    it "extracts empty extension for files without extensions" do
+      path = UnixPath.parse("/etc/passwd")
+      expect(path.extension).must_equal ""
+    end
+  end
 end