public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [pve-devel] [PATCH v1 pve-common 0/4] Introduce and Package PVE::Path & PVE::Filesystem
@ 2024-12-19 18:31 Max Carrara
  2024-12-19 18:31 ` [pve-devel] [PATCH v1 pve-common 1/4] introduce PVE::Path Max Carrara
                   ` (4 more replies)
  0 siblings, 5 replies; 8+ messages in thread
From: Max Carrara @ 2024-12-19 18:31 UTC (permalink / raw)
  To: pve-devel

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



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel


^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2024-12-20 18:55 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-12-19 18:31 [pve-devel] [PATCH v1 pve-common 0/4] Introduce and Package PVE::Path & PVE::Filesystem Max Carrara
2024-12-19 18:31 ` [pve-devel] [PATCH v1 pve-common 1/4] introduce PVE::Path Max Carrara
2024-12-19 18:31 ` [pve-devel] [PATCH v1 pve-common 2/4] add tests for PVE::Path Max Carrara
2024-12-19 19:08   ` Thomas Lamprecht
2024-12-20 11:06     ` Max Carrara
2024-12-19 18:31 ` [pve-devel] [PATCH v1 pve-common 3/4] introduce PVE::Filesystem Max Carrara
2024-12-19 18:31 ` [pve-devel] [PATCH v1 pve-common 4/4] debian: introduce package libproxmox-fs-path-utils-perl Max Carrara
2024-12-20 18:55 ` [pve-devel] [PATCH v1 pve-common 0/4] Introduce and Package PVE::Path & PVE::Filesystem Max Carrara

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal