[pve-devel] [PATCH v1 pve-common 0/4] Introduce and Package PVE::Path & PVE::Filesystem

[Max Carrara]

Introduce and Package PVE::Path & PVE::Filesystem
=================================================

tl;dr is at the bottom.

PVE::Path
---------

Concerns itself with file & directory path operations and does not
manipulate the filesystem.

This module adds a lot of functionalities that more modern path
libraries provide, mainly in order to address the shortcomings of the
Perl core modules. At the same time, this module takes a completely
functional approach, which means that anything it offers can just be
used ad hoc where needed.

The purpose of PVE::Path is to provide a "one-stop shop" for everything
that concerns file path operations. Additionally, none of the functions
it adds should have any "surprises" like a lot of Perl stuff inevitably
has. Inspiration is taken from more modern libraries like Rust's
`std::path` [1] and Python's `pathlib` [2].

I also want to address some questions that came up during development:

Q: How do you ensure that this module doesn't become another competing
   standard? [3]
A: The stuff in the core modules is either lacking or clunky (sorry for
   being blunt); PVE::Path makes things easier and actually implements
   many features that the core modules don't have, such as getting the
   parent directory of a path or checking if two paths are the same etc.

   Also, this will be very useful for things related to the storage API
   -- the frustrations of not being able to get the parent dir of a
   path are what actually prompted me to implement this.

Q: Are you testing this?
A: Yes, there are 1050 tests in total, because testing plain functions
   is easy and parameterizable.

Q: Why not use something from CPAN?
A: The (useful) modules from CPAN all use some kind of object-based
   abstraction, for which we would (probably) have to adapt a lot of
   code in order to be able to use those. This provides barely any
   benefit for the amount of churn that would be necessary. As mentioned
   above, PVE::Path strictly only consists of functions, so they can
   just be dropped in whenever some path operations need to be
   performed.

PVE::Filesystem
---------------

This module can be seen as the complement to PVE::Path that does
actually modify things on the filesystem, as the name implies.

Right now, this only adds two simple wrappers for two functions of the
Perl core modules, but is added here already to pave the way for further
expansion in the future, whenever the need to do so arises.

In the future this will go in the direction of Rust's `std::fs` [4] and
some other libraries I've seen out there, while sticking to the
functional-only, no-surprises approach like PVE::Path does.

TL;DR
-----

- PVE::Path implements basic file path manipulations that currently
  don't seem to exist and provides them in an accessible,
  non-surprising, straightforward, ergonomic manner
- PVE::Filesystem is for FS-altering utils, but is rather bare-bones at
  the moment, containing only two wrappers. The module is added solely
  so that it can be expanded when needed

Closing Remarks
---------------

Whether these modules are actually as fancy and ergonomic and $BUZZWORD
as I'm advertising here is of course left to be determined by my fellow
colleagues, so I'm really thankful for any feedback on this. <3

Every single function is documented, so it would be nice if I could get
some feedback on that as well. Even if there is just a little ambiguity,
please let me know -- I want these modules to be absolutely foolproof.

References
----------

[1]: https://doc.rust-lang.org/std/path/index.html
[2]: https://docs.python.org/3/library/pathlib.html
[3]: https://xkcd.com/927/
[4]: https://doc.rust-lang.org/std/fs/index.html

Summary of Changes
------------------

Max Carrara (4):
  introduce PVE::Path
  add tests for PVE::Path
  introduce PVE::Filesystem
  debian: introduce package libproxmox-fs-path-utils-perl

 debian/control                               |    6 +
 debian/libproxmox-fs-path-utils-perl.install |    2 +
 debian/libpve-common-perl.install            |   29 +
 src/Makefile                                 |    2 +
 src/PVE/Filesystem.pm                        |   78 +
 src/PVE/Path.pm                              |  956 +++++++++++++
 test/Makefile                                |    5 +-
 test/Path/Makefile                           |   20 +
 test/Path/path_basic_tests.pl                | 1331 ++++++++++++++++++
 test/Path/path_comparison_tests.pl           |  859 +++++++++++
 test/Path/path_file_ops_tests.pl             | 1220 ++++++++++++++++
 test/Path/path_join_tests.pl                 |  310 ++++
 test/Path/path_push_tests.pl                 |  159 +++
 13 files changed, 4976 insertions(+), 1 deletion(-)
 create mode 100644 debian/libproxmox-fs-path-utils-perl.install
 create mode 100644 debian/libpve-common-perl.install
 create mode 100644 src/PVE/Filesystem.pm
 create mode 100644 src/PVE/Path.pm
 create mode 100644 test/Path/Makefile
 create mode 100755 test/Path/path_basic_tests.pl
 create mode 100755 test/Path/path_comparison_tests.pl
 create mode 100755 test/Path/path_file_ops_tests.pl
 create mode 100755 test/Path/path_join_tests.pl
 create mode 100755 test/Path/path_push_tests.pl

--
2.39.5