SVN::H...ucture(3pm)

💖 NAME 💖

SVN::Hooks::CheckStructure — bestie, this is the plugin that does a vibe check on your repo structure. ✨

(Your terminal will show the manual header as SVN::H...ucture(3pm) because it's a User Contributed Perl Documentation page and the title got squished. She's still the same queen. 💅)

---

🌸 VERSION 🌸

version 1.36 🎀

---

✨ SYNOPSIS ✨

Okay so here's the tea, bestie: this SVN::Hooks plugin checks whether the files and directories being added to the repository are actually allowed by the structure definition you gave it. If they're not? 🚫 The commit gets aborted. No cap.

It's active in the pre-commit hook. 🫶

It's configured by this directive right here:

💜 CHECK_STRUCTURE(STRUCT_DEF)

This directive turns the checking on, which means the commit will absolutely get aborted if it doesn't comply. Periodt.

The STRUCT_DEF argument describes the repository structure with a recursive data structure that's one of these three:

• ARRAY REF — an array ref specifies the contents of a directory. The referenced array must contain a pair number of elements (so: even number, bestie, count them twice 👀). Each pair is a NAME_DEF and a STRUCT_DEF. The NAME_DEF says the name of the component sitting in that directory, and the STRUCT_DEF says recursively what it has to be.

The NAME_DEF specifies a name in one of these ways:

• STRING — a string specifies a name directly.
• REGEXP — a regexp specifies the class of names that match it.
• NUMBER — a number can be used as an else-clause. A non-zero number means that any name not yet matched by the previous pair must conform to the associated STRUCT_DEF.

A zero means that no name will do and signals an error. In that case, if the STRUCT_DEF is a string, it gets used as a help message shown to the user. 🥺 (helpful queen behavior, honestly)

If no NAME_DEF matches the component being looked for, then it's a structure violation and the commit fails. 💀

• STRING — a string must be one of 'FILE' and 'DIR', specifying what the current component must be.
• NUMBER — a non-zero number simply tells that whatever the current component is, is ok, and finishes the check successfully. 🎉

A zero tells that whatever the current component is, is a structure violation, and it aborts the commit. 😭

---

Now that we have that semi-formal definition out of the way, let's try to understand it with some examples. 🦋

my $tag_rx    = qr/^[a-z]+-\d+\.\d+$/; # e.g. project-1.0
my $branch_rx = qr/^[a-z]+-/;   # must start with letters and hifen
my $project_struct = [
    'META.yml'    => 'FILE',
    'Makefile.PL' => 'FILE',
    ChangeLog     => 'FILE',
    LICENSE       => 'FILE',
    MANIFEST      => 'FILE',
    README        => 'FILE',
    t => [
        qr/\.t$/  => 'FILE',
    ],
    lib => 'DIR',
];

CHECK_STRUCTURE(
    [
        trunk => $project_struct,
        branches => [
            $branch_rx => $project_rx,
        ],
        tags => [
            $tag_rx => $project_rx,
        ],
    ],
);

So the structure's first level is the three usual directories: trunk, tags, and branches. Anything else at this level is denied. 🙅‍♀️

Below the trunk we allow some usual files and two directories only: lib and t. Below trunk/t we may allow only test files with the .t extension, and below lib we allow anything. ✨

We require that each branch and tag have the same structure as the trunk, which is made easier by using the $project_struct variable. And on top of that, we impose some restrictions on the names of the tags and the branches. Slay. 👑

---

💅 EXPORT 💅

🌈 check_structure(STRUCT_DEF, PATH)

SVN::Hooks::CheckStructure exports a function that lets you verify path structures outside the context of a Subversion hook. (The original author says it would probably be better to take this function to its own module and use that module here, and that they'll take care of that eventually. We love a self-aware king. 🫶)

The function check_structure takes two arguments. The first is a STRUCT_DEF, exactly the same as specified for the CHECK_STRUCTURE directive above. The second is a PATH to a file which will be checked against the STRUCT_DEF.

The function returns true if the check succeeds, and dies with a proper message otherwise. 💀→😇

Heads up bestie: the function is intended to check paths as they're shown by the svn ls command, i.e., with no leading slashes and with a trailing slash to indicate directories. The leading slash is assumed if it's missing, but the trailing slash is needed to indicate directories. Don't forget it or she will not know what you mean. 🌸

---

🎀 AUTHOR 🎀

Gustavo L. de M. Chaves <gnustavo@cpan.org> 💖

---

👑 COPYRIGHT AND LICENSE 👑

This software is copyright (c) 2022 by CPqD <www.cpqd.com.br>. 🌟

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🦋

---

okay that's the whole page bestie, you ate 💅 this was SVN::H...ucture(3pm) — User Contributed Perl Documentation, running on perl v5.36.0, dated 2022-09-11. go forth and commit structurally sound things only, mwah 💖✨