NAME

       SVN::Hooks::CheckStructure - Check the structure of a repository.

VERSION

       version 1.36

SYNOPSIS

       This SVN::Hooks plugin checks if the files and directories added to the repository are allowed by its
       structure definition. If they don't, the commit is aborted.

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

       It's configured by the following directive.

   CHECK_STRUCTURE(STRUCT_DEF)
       This directive enables the checking, causing the commit to abort if it doesn't comply.

       The STRUCT_DEF argument specify the repository strucure with a recursive data structure consisting of one
       of:

       ARRAY REF
           An  array  ref specifies the contents of a directory. The referenced array must contain a pair number
           of elements. Each pair consists of a NAME_DEF and a STRUCT_DEF. The NAME_DEF specifies  the  name  of
           the component contained in the directory and the STRUCT_DEF specifies recursively what it must 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 may 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 this case,  if  the  STRUCT_DEF  is  a
               string it is used as a help message shown to the user.

           If  no  NAME_DEF  matches  the  component  being looked for, then it is 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 aborts the commit.

       Now that we have this semi-formal definition off 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,
                       ],
                   ],
               );

       The  structure's  first  level  consists of the three usual directories: "trunk", "tags", and "branches".
       Anything else in 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 the
       use of the $project_struct variable. Moreover, we impose some restrictions on the names of the  tags  and
       the branches.

EXPORT

   check_structure(STRUCT_DEF, PATH)
       SVN::Hooks::CheckStructure  exports  a  function to allow for the verification of path structures outside
       the context of a Subversion hook. (It would probably be better to take this function to  its  own  module
       and use that module here. We'll take care of that eventually.)

       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.

       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.

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.

perl v5.36.0                                       2022-09-11                    SVN::Hooks::CheckStructure(3pm)