From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 3EE251FF16F for ; Thu, 19 Dec 2024 19:32:18 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C99C4E59E; Thu, 19 Dec 2024 19:32:17 +0100 (CET) From: Max Carrara To: pve-devel@lists.proxmox.com Date: Thu, 19 Dec 2024 19:31:39 +0100 Message-Id: <20241219183143.526267-1-m.carrara@proxmox.com> X-Mailer: git-send-email 2.39.5 MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.031 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH v1 pve-common 0/4] Introduce and Package PVE::Path & PVE::Filesystem X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "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