/ 
File-Codeowners-0.55
River stage one • 1 direct dependent • 1 total dependent
/ File::Codeowners

NAME

File::Codeowners - Read and write CODEOWNERS files

VERSION

version 0.55

DESCRIPTION

This module parses and generates CODEOWNERS files.

See CODEOWNERS syntax.

METHODS

new

$codeowners = File::Codeowners->new;

Construct a new File::Codeowners.

parse

$codeowners = File::Codeowners->parse($filepath, @options);
$codeowners = File::Codeowners->parse(*IO, @options);
$codeowners = File::Codeowners->parse(\@lines, @options);
$codeowners = File::Codeowners->parse(\$string, @options);

Parse a CODEOWNERS file.

This is a shortcut for the parse_from_* methods.

Possible options:

  • aliases - Parse lines that begin with "@" as aliases (default: false)

parse_from_filepath

$codeowners = File::Codeowners->parse_from_filepath($filepath, @options);

Parse a CODEOWNERS file from the filesystem.

parse_from_fh

$codeowners = File::Codeowners->parse_from_fh(*IO, @options);

Parse a CODEOWNERS file from an open filehandle.

parse_from_array

$codeowners = File::Codeowners->parse_from_array(\@lines, @options);

Parse a CODEOWNERS file stored as lines in an array.

parse_from_string

$codeowners = File::Codeowners->parse_from_string(\$string, @options);
$codeowners = File::Codeowners->parse_from_string($string, @options);

Parse a CODEOWNERS file stored as a string. String should be UTF-8 encoded.

write_to_filepath

$codeowners->write_to_filepath($filepath);

Write the contents of the file to the filesystem atomically.

write_to_fh

$codeowners->write_to_fh($fh);

Format the file contents and write to a filehandle.

write_to_string

\$string = $codeowners->write_to_string;

Format the file contents and return a reference to a formatted string.

write_to_array

\@lines = $codeowners->write_to_array;

Format the file contents as an arrayref of lines.

match

\%match = $codeowners->match($filepath, %options);

Match the given filepath against the available patterns and return just the owners for the matching pattern. Patterns are checked in the reverse order they were defined in the file.

Returns undef if no patterns match.

Possible options:

  • expand - Expand group aliases defined in the CODEOWNERS file.

owners

$owners = $codeowners->owners; # get all defined owners
$owners = $codeowners->owners($pattern);

Get an arrayref of owners defined in the file. If a pattern argument is given, only owners for the given pattern are returned (or empty arrayref if the pattern does not exist). If no argument is given, simply returns all owners defined in the file.

patterns

$patterns = $codeowners->patterns;
$patterns = $codeowners->patterns($owner);

Get an arrayref of all patterns defined.

aliases

\%aliases = $codeowners->aliases;

Get a hashref of all aliases defined.

projects

\@projects = $codeowners->projects;

Get an arrayref of all projects defined.

update_owners

$codeowners->update_owners($pattern => \@new_owners);

Set a new set of owners for a given pattern. If for some reason the file has multiple such patterns, they will all be updated.

Nothing happens if the file does not already have at least one such pattern.

update_owners_by_project

$codeowners->update_owners_by_project($project => \@new_owners);

Set a new set of owners for all patterns under the given project.

Nothing happens if the file does not have a project with the given name.

rename_owner

$codeowners->rename_owner($old_name => $new_name);

Rename an owner.

Nothing happens if the file does not have an owner with the old name.

rename_project

$codeowners->rename_project($old_name => $new_name);

Rename a project.

Nothing happens if the file does not have a project with the old name.

append

$codeowners->append(comment => $str);
$codeowners->append(pattern => $pattern, owners => \@owners);
$codeowners->append();     # blank line

Append a new line.

prepend

$codeowners->prepend(comment => $str);
$codeowners->prepend(pattern => $pattern, owners => \@owners);
$codeowners->prepend();    # blank line

Prepend a new line.

unowned

\@filepaths = $codeowners->unowned;

Get the list of filepaths in the "unowned" section.

This parser supports an "extension" to the CODEOWNERS file format which lists unowned files at the end of the file. This list can be useful to have in order to figure out what files we know are unowned versus what files we don't know are unowned.

add_unowned

$codeowners->add_unowned($filepath, ...);

Add one or more filepaths to the "unowned" list.

This method does not check to make sure the filepath(s) actually do not match any patterns in the file, so you might want to call "match" first.

See "unowned" for an explanation.

remove_unowned

$codeowners->remove_unowned($filepath, ...);

Remove one or more filepaths from the "unowned" list.

Silently ignores filepaths that are already not listed.

See "unowned" for an explanation.

is_unowned

$bool = $codeowners->is_unowned($filepath);

Test whether a filepath is in the "unowned" list.

See "unowned" for an explanation.

clear_unowned

$codeowners->clear_unowned;

Remove all filepaths from the "unowned" list.

See "unowned" for an explanation.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/File-Codeowners/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Charles McGarvey <chazmcgarvey@brokenzipper.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Charles McGarvey.

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