Stow.pm: reformat comments
Some methods had comments with a prefix which made the paragraph inconveniently narrow, and made refilling it really awkward. So switch to a more natural comment style.
This commit is contained in:
parent
11d4ff01d7
commit
1be40c0532
1 changed files with 144 additions and 130 deletions
274
lib/Stow.pm.in
274
lib/Stow.pm.in
|
@ -334,16 +334,17 @@ sub plan_stow {
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : within_target_do()
|
# Name : within_target_do()
|
||||||
# Purpose : execute code within target directory, preserving cwd
|
# Purpose : execute code within target directory, preserving cwd
|
||||||
# Parameters: $code => anonymous subroutine to execute within target dir
|
# Parameters: $code => anonymous subroutine to execute within target dir
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : This is done to ensure that the consumer of the Stow interface
|
#
|
||||||
# : doesn't have to worry about (a) what their cwd is, and
|
# This is done to ensure that the consumer of the Stow interface
|
||||||
# : (b) that their cwd might change.
|
# doesn't have to worry about (a) what their cwd is, and (b) that
|
||||||
#============================================================================
|
# their cwd might change.
|
||||||
|
# ============================================================================
|
||||||
sub within_target_do {
|
sub within_target_do {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($code) = @_;
|
my ($code) = @_;
|
||||||
|
@ -359,7 +360,7 @@ sub within_target_do {
|
||||||
debug(3, 0, "cwd restored to $cwd");
|
debug(3, 0, "cwd restored to $cwd");
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : stow_contents()
|
# Name : stow_contents()
|
||||||
# Purpose : stow the contents of the given directory
|
# Purpose : stow the contents of the given directory
|
||||||
# Parameters: $stow_path => relative path from current (i.e. target) directory
|
# Parameters: $stow_path => relative path from current (i.e. target) directory
|
||||||
|
@ -376,10 +377,11 @@ sub within_target_do {
|
||||||
# : to symlink source
|
# : to symlink source
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : a fatal error if directory cannot be read
|
# Throws : a fatal error if directory cannot be read
|
||||||
# Comments : stow_node() and stow_contents() are mutually recursive.
|
#
|
||||||
# : $source and $target are used for creating the symlink
|
# stow_node() and stow_contents() are mutually recursive. $source and
|
||||||
# : $path is used for folding/unfolding trees as necessary
|
# $target are used for creating the symlink $path is used for
|
||||||
#============================================================================
|
# folding/unfolding trees as necessary
|
||||||
|
# ============================================================================
|
||||||
sub stow_contents {
|
sub stow_contents {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($stow_path, $package, $target, $source) = @_;
|
my ($stow_path, $package, $target, $source) = @_;
|
||||||
|
@ -435,7 +437,7 @@ sub stow_contents {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : stow_node()
|
# Name : stow_node()
|
||||||
# Purpose : stow the given node
|
# Purpose : stow the given node
|
||||||
# Parameters: $stow_path => relative path from current (i.e. target) directory
|
# Parameters: $stow_path => relative path from current (i.e. target) directory
|
||||||
|
@ -447,10 +449,11 @@ sub stow_contents {
|
||||||
# : $source => relative path to symlink source from the dir of target
|
# : $source => relative path to symlink source from the dir of target
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal exception if a conflict arises
|
# Throws : fatal exception if a conflict arises
|
||||||
# Comments : stow_node() and stow_contents() are mutually recursive.
|
#
|
||||||
# : $source and $target are used for creating the symlink
|
# stow_node() and stow_contents() are mutually recursive. $source and
|
||||||
# : $path is used for folding/unfolding trees as necessary
|
# $target are used for creating the symlink $path is used for
|
||||||
#============================================================================
|
# folding/unfolding trees as necessary
|
||||||
|
# ============================================================================
|
||||||
sub stow_node {
|
sub stow_node {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($stow_path, $package, $target, $source) = @_;
|
my ($stow_path, $package, $target, $source) = @_;
|
||||||
|
@ -586,16 +589,17 @@ sub stow_node {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : should_skip_target()
|
# Name : should_skip_target()
|
||||||
# Purpose : determine whether target is a stow directory which should
|
# Purpose : determine whether target is a stow directory which should
|
||||||
# : not be stowed to or unstowed from
|
# : not be stowed to or unstowed from
|
||||||
# Parameters: $target => relative path to symlink target from the current directory
|
# Parameters: $target => relative path to symlink target from the current directory
|
||||||
# Returns : true iff target is a stow directory
|
# Returns : true iff target is a stow directory
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : cwd must be the top-level target directory, otherwise
|
#
|
||||||
# : marked_stow_dir() won't work.
|
# cwd must be the top-level target directory, otherwise
|
||||||
#============================================================================
|
# marked_stow_dir() won't work.
|
||||||
|
# ============================================================================
|
||||||
sub should_skip_target {
|
sub should_skip_target {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($target) = @_;
|
my ($target) = @_;
|
||||||
|
@ -632,16 +636,17 @@ sub marked_stow_dir {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : unstow_contents_orig()
|
# Name : unstow_contents_orig()
|
||||||
# Purpose : unstow the contents of the given directory
|
# Purpose : unstow the contents of the given directory
|
||||||
# Parameters: $package => the package whose contents are being unstowed
|
# Parameters: $package => the package whose contents are being unstowed
|
||||||
# : $target => relative path to symlink target from the current directory
|
# : $target => relative path to symlink target from the current directory
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : a fatal error if directory cannot be read
|
# Throws : a fatal error if directory cannot be read
|
||||||
# Comments : unstow_node_orig() and unstow_contents_orig() are mutually recursive
|
#
|
||||||
# : Here we traverse the target tree, rather than the source tree.
|
# unstow_node_orig() and unstow_contents_orig() are mutually recursive.
|
||||||
#============================================================================
|
# Here we traverse the target tree, rather than the source tree.
|
||||||
|
# ============================================================================
|
||||||
sub unstow_contents_orig {
|
sub unstow_contents_orig {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($package, $target) = @_;
|
my ($package, $target) = @_;
|
||||||
|
@ -676,15 +681,16 @@ sub unstow_contents_orig {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : unstow_node_orig()
|
# Name : unstow_node_orig()
|
||||||
# Purpose : unstow the given node
|
# Purpose : unstow the given node
|
||||||
# Parameters: $package => the package containing the node being stowed
|
# Parameters: $package => the package containing the node being stowed
|
||||||
# : $target => relative path to symlink target from the current directory
|
# : $target => relative path to symlink target from the current directory
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal error if a conflict arises
|
# Throws : fatal error if a conflict arises
|
||||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
#
|
||||||
#============================================================================
|
# unstow_node() and unstow_contents() are mutually recursive.
|
||||||
|
# ============================================================================
|
||||||
sub unstow_node_orig {
|
sub unstow_node_orig {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($package, $target) = @_;
|
my ($package, $target) = @_;
|
||||||
|
@ -752,16 +758,17 @@ sub unstow_node_orig {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : unstow_contents()
|
# Name : unstow_contents()
|
||||||
# Purpose : unstow the contents of the given directory
|
# Purpose : unstow the contents of the given directory
|
||||||
# Parameters: $package => the package whose contents are being unstowed
|
# Parameters: $package => the package whose contents are being unstowed
|
||||||
# : $target => relative path to symlink target from the current directory
|
# : $target => relative path to symlink target from the current directory
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : a fatal error if directory cannot be read
|
# Throws : a fatal error if directory cannot be read
|
||||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
#
|
||||||
# : Here we traverse the source tree, rather than the target tree.
|
# unstow_node() and unstow_contents() are mutually recursive.
|
||||||
#============================================================================
|
# Here we traverse the source tree, rather than the target tree.
|
||||||
|
# ============================================================================
|
||||||
sub unstow_contents {
|
sub unstow_contents {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($package, $target) = @_;
|
my ($package, $target) = @_;
|
||||||
|
@ -809,15 +816,16 @@ sub unstow_contents {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : unstow_node()
|
# Name : unstow_node()
|
||||||
# Purpose : unstow the given node
|
# Purpose : unstow the given node
|
||||||
# Parameters: $package => the package containing the node being unstowed
|
# Parameters: $package => the package containing the node being unstowed
|
||||||
# : $target => relative path to symlink target from the current directory
|
# : $target => relative path to symlink target from the current directory
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal error if a conflict arises
|
# Throws : fatal error if a conflict arises
|
||||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
#
|
||||||
#============================================================================
|
# unstow_node() and unstow_contents() are mutually recursive.
|
||||||
|
# ============================================================================
|
||||||
sub unstow_node {
|
sub unstow_node {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($package, $target) = @_;
|
my ($package, $target) = @_;
|
||||||
|
@ -915,7 +923,7 @@ sub unstow_node {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : link_owned_by_package()
|
# Name : link_owned_by_package()
|
||||||
# Purpose : determine whether the given link points to a member of a
|
# Purpose : determine whether the given link points to a member of a
|
||||||
# : stowed package
|
# : stowed package
|
||||||
|
@ -923,8 +931,9 @@ sub unstow_node {
|
||||||
# : $source => where that link points to
|
# : $source => where that link points to
|
||||||
# Returns : the package iff link is owned by stow, otherwise ''
|
# Returns : the package iff link is owned by stow, otherwise ''
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : lossy wrapper around find_stowed_path()
|
#
|
||||||
#============================================================================
|
# lossy wrapper around find_stowed_path().
|
||||||
|
# ============================================================================
|
||||||
sub link_owned_by_package {
|
sub link_owned_by_package {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($target, $source) = @_;
|
my ($target, $source) = @_;
|
||||||
|
@ -934,7 +943,7 @@ sub link_owned_by_package {
|
||||||
return $package;
|
return $package;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : find_stowed_path()
|
# Name : find_stowed_path()
|
||||||
# Purpose : determine whether the given symlink within the target directory
|
# Purpose : determine whether the given symlink within the target directory
|
||||||
# : is a stowed path pointing to a member of a package under the
|
# : is a stowed path pointing to a member of a package under the
|
||||||
|
@ -959,10 +968,11 @@ sub link_owned_by_package {
|
||||||
# : to the stow directory; and $package is the name of the
|
# : to the stow directory; and $package is the name of the
|
||||||
# : package; or ('', '', '') if link is not owned by stow.
|
# : package; or ('', '', '') if link is not owned by stow.
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : cwd must be the top-level target directory, otherwise
|
#
|
||||||
# : find_containing_marked_stow_dir() won't work.
|
# cwd must be the top-level target directory, otherwise
|
||||||
# : Allow for stow dir not being under target dir.
|
# find_containing_marked_stow_dir() won't work. Allow for stow dir
|
||||||
#============================================================================
|
# not being under target dir.
|
||||||
|
# ============================================================================
|
||||||
sub find_stowed_path {
|
sub find_stowed_path {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($target, $ldest) = @_;
|
my ($target, $ldest) = @_;
|
||||||
|
@ -999,13 +1009,13 @@ sub find_stowed_path {
|
||||||
return ('', '', '');
|
return ('', '', '');
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : link_dest_within_stow_dir
|
# Name : link_dest_within_stow_dir
|
||||||
# Purpose : detect whether symlink destination is within current stow dir
|
# Purpose : detect whether symlink destination is within current stow dir
|
||||||
# Parameters: $ldest - destination of the symlink relative
|
# Parameters: $ldest - destination of the symlink relative
|
||||||
# Returns : ($package, $path) - package within the current stow dir
|
# Returns : ($package, $path) - package within the current stow dir
|
||||||
# : and subpath within that package which the symlink points to
|
# : and subpath within that package which the symlink points to
|
||||||
#=============================================================================
|
# =============================================================================
|
||||||
sub link_dest_within_stow_dir {
|
sub link_dest_within_stow_dir {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($ldest) = @_;
|
my ($ldest) = @_;
|
||||||
|
@ -1025,7 +1035,7 @@ sub link_dest_within_stow_dir {
|
||||||
return ($package, $path);
|
return ($package, $path);
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : find_containing_marked_stow_dir
|
# Name : find_containing_marked_stow_dir
|
||||||
# Purpose : detect whether path is within a marked stow directory
|
# Purpose : detect whether path is within a marked stow directory
|
||||||
# Parameters: $path => path to directory to check
|
# Parameters: $path => path to directory to check
|
||||||
|
@ -1034,9 +1044,10 @@ sub link_dest_within_stow_dir {
|
||||||
# : as a Stow directory, and $package is the containing package;
|
# : as a Stow directory, and $package is the containing package;
|
||||||
# : or ('', '') if no containing directory is marked as a stow
|
# : or ('', '') if no containing directory is marked as a stow
|
||||||
# : directory.
|
# : directory.
|
||||||
# Comments : cwd must be the top-level target directory, otherwise
|
#
|
||||||
# : marked_stow_dir() won't work.
|
# cwd must be the top-level target directory, otherwise
|
||||||
#=============================================================================
|
# marked_stow_dir() won't work.
|
||||||
|
# =============================================================================
|
||||||
sub find_containing_marked_stow_dir {
|
sub find_containing_marked_stow_dir {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1061,20 +1072,21 @@ sub find_containing_marked_stow_dir {
|
||||||
return ('', '');
|
return ('', '');
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : cleanup_invalid_links()
|
# Name : cleanup_invalid_links()
|
||||||
# Purpose : clean up orphaned links that may block folding
|
# Purpose : clean up orphaned links that may block folding
|
||||||
# Parameters: $dir => path to directory to check
|
# Parameters: $dir => path to directory to check
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : no exceptions
|
# Throws : no exceptions
|
||||||
# Comments : This is invoked by unstow_contents().
|
#
|
||||||
# : We only clean up links which are both orphaned and owned by
|
# This is invoked by unstow_contents(). We only clean up links which
|
||||||
# : Stow, i.e. they point to a non-existent location within a
|
# are both orphaned and owned by Stow, i.e. they point to a
|
||||||
# : Stow package. These can block tree folding, and they can
|
# non-existent location within a Stow package. These can block tree
|
||||||
# : easily occur when a file in Stow package is renamed or removed,
|
# folding, and they can easily occur when a file in Stow package is
|
||||||
# : so the benefit should outweigh the low risk of actually someone
|
# renamed or removed, so the benefit should outweigh the low risk of
|
||||||
# : wanting to keep an orphaned link to within a Stow package.
|
# actually someone wanting to keep an orphaned link to within a Stow
|
||||||
#=============================================================================
|
# package.
|
||||||
|
# =============================================================================
|
||||||
sub cleanup_invalid_links {
|
sub cleanup_invalid_links {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($dir) = @_;
|
my ($dir) = @_;
|
||||||
|
@ -1146,15 +1158,16 @@ sub cleanup_invalid_links {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : foldable()
|
# Name : foldable()
|
||||||
# Purpose : determine whether a tree can be folded
|
# Purpose : determine whether a tree can be folded
|
||||||
# Parameters: $target => path to a directory
|
# Parameters: $target => path to a directory
|
||||||
# Returns : path to the parent dir iff the tree can be safely folded
|
# Returns : path to the parent dir iff the tree can be safely folded
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : the path returned is relative to the parent of $target,
|
#
|
||||||
# : that is, it can be used as the source for a replacement symlink
|
# The path returned is relative to the parent of $target, i.e. it can
|
||||||
#============================================================================
|
# be used as the source for a replacement symlink.
|
||||||
|
# ============================================================================
|
||||||
sub foldable {
|
sub foldable {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($target) = @_;
|
my ($target) = @_;
|
||||||
|
@ -1216,15 +1229,16 @@ sub foldable {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : fold_tree()
|
# Name : fold_tree()
|
||||||
# Purpose : fold the given tree
|
# Purpose : fold the given tree
|
||||||
# Parameters: $source => link to the folded tree source
|
# Parameters: $source => link to the folded tree source
|
||||||
# : $target => directory that we will replace with a link to $source
|
# : $target => directory that we will replace with a link to $source
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : only called iff foldable() is true so we can remove some checks
|
#
|
||||||
#============================================================================
|
# Only called iff foldable() is true so we can remove some checks.
|
||||||
|
# ============================================================================
|
||||||
sub fold_tree {
|
sub fold_tree {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($target, $source) = @_;
|
my ($target, $source) = @_;
|
||||||
|
@ -1249,15 +1263,14 @@ sub fold_tree {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : conflict()
|
# Name : conflict()
|
||||||
# Purpose : handle conflicts in stow operations
|
# Purpose : handle conflicts in stow operations
|
||||||
# Parameters: $package => the package involved with the conflicting operation
|
# Parameters: $package => the package involved with the conflicting operation
|
||||||
# : $message => a description of the conflict
|
# : $message => a description of the conflict
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub conflict {
|
sub conflict {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($action, $package, $message) = @_;
|
my ($action, $package, $message) = @_;
|
||||||
|
@ -1326,7 +1339,7 @@ sub get_action_count {
|
||||||
return $self->{action_count};
|
return $self->{action_count};
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : ignore
|
# Name : ignore
|
||||||
# Purpose : determine if the given path matches a regex in our ignore list
|
# Purpose : determine if the given path matches a regex in our ignore list
|
||||||
# Parameters: $stow_path => the stow directory containing the package
|
# Parameters: $stow_path => the stow directory containing the package
|
||||||
|
@ -1335,8 +1348,7 @@ sub get_action_count {
|
||||||
# : relative to its package directory
|
# : relative to its package directory
|
||||||
# Returns : true iff the path should be ignored
|
# Returns : true iff the path should be ignored
|
||||||
# Throws : no exceptions
|
# Throws : no exceptions
|
||||||
# Comments : none
|
# =============================================================================
|
||||||
#=============================================================================
|
|
||||||
sub ignore {
|
sub ignore {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($stow_path, $package, $target) = @_;
|
my ($stow_path, $package, $target) = @_;
|
||||||
|
@ -1512,14 +1524,13 @@ sub get_default_global_ignore_regexps {
|
||||||
return $class->get_ignore_regexps_from_fh(\*DATA);
|
return $class->get_ignore_regexps_from_fh(\*DATA);
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : defer
|
# Name : defer
|
||||||
# Purpose : determine if the given path matches a regex in our defer list
|
# Purpose : determine if the given path matches a regex in our defer list
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : no exceptions
|
# Throws : no exceptions
|
||||||
# Comments : none
|
# =============================================================================
|
||||||
#=============================================================================
|
|
||||||
sub defer {
|
sub defer {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1530,14 +1541,13 @@ sub defer {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ================================================================
|
# ===== METHOD ================================================================
|
||||||
# Name : override
|
# Name : override
|
||||||
# Purpose : determine if the given path matches a regex in our override list
|
# Purpose : determine if the given path matches a regex in our override list
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : no exceptions
|
# Throws : no exceptions
|
||||||
# Comments : none
|
# =============================================================================
|
||||||
#=============================================================================
|
|
||||||
sub override {
|
sub override {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1555,14 +1565,13 @@ sub override {
|
||||||
#
|
#
|
||||||
##############################################################################
|
##############################################################################
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : process_tasks()
|
# Name : process_tasks()
|
||||||
# Purpose : process each task in the tasks list
|
# Purpose : process each task in the tasks list
|
||||||
# Parameters: none
|
# Parameters: none
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal error if tasks list is corrupted or a task fails
|
# Throws : fatal error if tasks list is corrupted or a task fails
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub process_tasks {
|
sub process_tasks {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
|
|
||||||
|
@ -1584,16 +1593,17 @@ sub process_tasks {
|
||||||
debug(2, 0, "Processing tasks... done");
|
debug(2, 0, "Processing tasks... done");
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : process_task()
|
# Name : process_task()
|
||||||
# Purpose : process a single task
|
# Purpose : process a single task
|
||||||
# Parameters: $task => the task to process
|
# Parameters: $task => the task to process
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal error if task fails
|
# Throws : fatal error if task fails
|
||||||
# Comments : Must run from within target directory.
|
#
|
||||||
# : Task involve either creating or deleting dirs and symlinks
|
# Must run from within target directory. Task involve either creating
|
||||||
# : an action is set to 'skip' if it is found to be redundant
|
# or deleting dirs and symlinks an action is set to 'skip' if it is
|
||||||
#============================================================================
|
# found to be redundant
|
||||||
|
# ============================================================================
|
||||||
sub process_task {
|
sub process_task {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($task) = @_;
|
my ($task) = @_;
|
||||||
|
@ -1640,14 +1650,13 @@ sub process_task {
|
||||||
internal_error("bad task action: $task->{action}");
|
internal_error("bad task action: $task->{action}");
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : link_task_action()
|
# Name : link_task_action()
|
||||||
# Purpose : finds the link task action for the given path, if there is one
|
# Purpose : finds the link task action for the given path, if there is one
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : 'remove', 'create', or '' if there is no action
|
# Returns : 'remove', 'create', or '' if there is no action
|
||||||
# Throws : a fatal exception if an invalid action is found
|
# Throws : a fatal exception if an invalid action is found
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub link_task_action {
|
sub link_task_action {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1665,14 +1674,13 @@ sub link_task_action {
|
||||||
return $action;
|
return $action;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : dir_task_action()
|
# Name : dir_task_action()
|
||||||
# Purpose : finds the dir task action for the given path, if there is one
|
# Purpose : finds the dir task action for the given path, if there is one
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : 'remove', 'create', or '' if there is no action
|
# Returns : 'remove', 'create', or '' if there is no action
|
||||||
# Throws : a fatal exception if an invalid action is found
|
# Throws : a fatal exception if an invalid action is found
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub dir_task_action {
|
sub dir_task_action {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1690,15 +1698,14 @@ sub dir_task_action {
|
||||||
return $action;
|
return $action;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : parent_link_scheduled_for_removal()
|
# Name : parent_link_scheduled_for_removal()
|
||||||
# Purpose : determine whether the given path or any parent thereof
|
# Purpose : determine whether the given path or any parent thereof
|
||||||
# : is a link scheduled for removal
|
# : is a link scheduled for removal
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub parent_link_scheduled_for_removal {
|
sub parent_link_scheduled_for_removal {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1718,15 +1725,16 @@ sub parent_link_scheduled_for_removal {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : is_a_link()
|
# Name : is_a_link()
|
||||||
# Purpose : determine if the given path is a current or planned link
|
# Purpose : determine if the given path is a current or planned link
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : returns false if an existing link is scheduled for removal
|
#
|
||||||
# : and true if a non-existent link is scheduled for creation
|
# Returns false if an existing link is scheduled for removal and true
|
||||||
#============================================================================
|
# if a non-existent link is scheduled for creation.
|
||||||
|
# ============================================================================
|
||||||
sub is_a_link {
|
sub is_a_link {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1754,16 +1762,17 @@ sub is_a_link {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : is_a_dir()
|
# Name : is_a_dir()
|
||||||
# Purpose : determine if the given path is a current or planned directory
|
# Purpose : determine if the given path is a current or planned directory
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : returns false if an existing directory is scheduled for removal
|
#
|
||||||
# : and true if a non-existent directory is scheduled for creation
|
# Returns false if an existing directory is scheduled for removal and
|
||||||
# : we also need to be sure we are not just following a link
|
# true if a non-existent directory is scheduled for creation. We also
|
||||||
#============================================================================
|
# need to be sure we are not just following a link.
|
||||||
|
# ============================================================================
|
||||||
sub is_a_dir {
|
sub is_a_dir {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1789,16 +1798,17 @@ sub is_a_dir {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : is_a_node()
|
# Name : is_a_node()
|
||||||
# Purpose : determine whether the given path is a current or planned node
|
# Purpose : determine whether the given path is a current or planned node
|
||||||
# Parameters: $path
|
# Parameters: $path
|
||||||
# Returns : Boolean
|
# Returns : Boolean
|
||||||
# Throws : none
|
# Throws : none
|
||||||
# Comments : returns false if an existing node is scheduled for removal
|
#
|
||||||
# : true if a non-existent node is scheduled for creation
|
# Returns false if an existing node is scheduled for removal true if a
|
||||||
# : we also need to be sure we are not just following a link
|
# non-existent node is scheduled for creation. we also need to be
|
||||||
#============================================================================
|
# sure we are not just following a link.
|
||||||
|
# ============================================================================
|
||||||
sub is_a_node {
|
sub is_a_node {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1861,15 +1871,14 @@ sub is_a_node {
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : read_a_link()
|
# Name : read_a_link()
|
||||||
# Purpose : return the source of a current or planned link
|
# Purpose : return the source of a current or planned link
|
||||||
# Parameters: $path => path to the link target
|
# Parameters: $path => path to the link target
|
||||||
# Returns : a string
|
# Returns : a string
|
||||||
# Throws : fatal exception if the given path is not a current or planned
|
# Throws : fatal exception if the given path is not a current or planned
|
||||||
# : link
|
# : link
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub read_a_link {
|
sub read_a_link {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($path) = @_;
|
my ($path) = @_;
|
||||||
|
@ -1894,15 +1903,16 @@ sub read_a_link {
|
||||||
internal_error("read_a_link() passed a non link path: $path\n");
|
internal_error("read_a_link() passed a non link path: $path\n");
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : do_link()
|
# Name : do_link()
|
||||||
# Purpose : wrap 'link' operation for later processing
|
# Purpose : wrap 'link' operation for later processing
|
||||||
# Parameters: $oldfile => the existing file to link to
|
# Parameters: $oldfile => the existing file to link to
|
||||||
# : $newfile => the file to link
|
# : $newfile => the file to link
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : error if this clashes with an existing planned operation
|
# Throws : error if this clashes with an existing planned operation
|
||||||
# Comments : cleans up operations that undo previous operations
|
#
|
||||||
#============================================================================
|
# Cleans up operations that undo previous operations.
|
||||||
|
# ============================================================================
|
||||||
sub do_link {
|
sub do_link {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($oldfile, $newfile) = @_;
|
my ($oldfile, $newfile) = @_;
|
||||||
|
@ -1972,14 +1982,15 @@ sub do_link {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : do_unlink()
|
# Name : do_unlink()
|
||||||
# Purpose : wrap 'unlink' operation for later processing
|
# Purpose : wrap 'unlink' operation for later processing
|
||||||
# Parameters: $file => the file to unlink
|
# Parameters: $file => the file to unlink
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : error if this clashes with an existing planned operation
|
# Throws : error if this clashes with an existing planned operation
|
||||||
# Comments : will remove an existing planned link
|
#
|
||||||
#============================================================================
|
# Will remove an existing planned link.
|
||||||
|
# ============================================================================
|
||||||
sub do_unlink {
|
sub do_unlink {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($file) = @_;
|
my ($file) = @_;
|
||||||
|
@ -2027,16 +2038,18 @@ sub do_unlink {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : do_mkdir()
|
# Name : do_mkdir()
|
||||||
# Purpose : wrap 'mkdir' operation
|
# Purpose : wrap 'mkdir' operation
|
||||||
# Parameters: $dir => the directory to remove
|
# Parameters: $dir => the directory to remove
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal exception if operation fails
|
# Throws : fatal exception if operation fails
|
||||||
# Comments : outputs a message if 'verbose' option is set
|
#
|
||||||
# : does not perform operation if 'simulate' option is set
|
# Outputs a message if 'verbose' option is set.
|
||||||
# Comments : cleans up operations that undo previous operations
|
# Does not perform operation if 'simulate' option is set.
|
||||||
#============================================================================
|
#
|
||||||
|
# Cleans up operations that undo previous operations.
|
||||||
|
# ============================================================================
|
||||||
sub do_mkdir {
|
sub do_mkdir {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($dir) = @_;
|
my ($dir) = @_;
|
||||||
|
@ -2090,15 +2103,16 @@ sub do_mkdir {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : do_rmdir()
|
# Name : do_rmdir()
|
||||||
# Purpose : wrap 'rmdir' operation
|
# Purpose : wrap 'rmdir' operation
|
||||||
# Parameters: $dir => the directory to remove
|
# Parameters: $dir => the directory to remove
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : fatal exception if operation fails
|
# Throws : fatal exception if operation fails
|
||||||
# Comments : outputs a message if 'verbose' option is set
|
#
|
||||||
# : does not perform operation if 'simulate' option is set
|
# Outputs a message if 'verbose' option is set.
|
||||||
#============================================================================
|
# Does not perform operation if 'simulate' option is set.
|
||||||
|
# ============================================================================
|
||||||
sub do_rmdir {
|
sub do_rmdir {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($dir) = @_;
|
my ($dir) = @_;
|
||||||
|
@ -2144,15 +2158,16 @@ sub do_rmdir {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
#===== METHOD ===============================================================
|
# ===== METHOD ===============================================================
|
||||||
# Name : do_mv()
|
# Name : do_mv()
|
||||||
# Purpose : wrap 'move' operation for later processing
|
# Purpose : wrap 'move' operation for later processing
|
||||||
# Parameters: $src => the file to move
|
# Parameters: $src => the file to move
|
||||||
# : $dst => the path to move it to
|
# : $dst => the path to move it to
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : error if this clashes with an existing planned operation
|
# Throws : error if this clashes with an existing planned operation
|
||||||
# Comments : alters contents of package installation image in stow dir
|
#
|
||||||
#============================================================================
|
# Alters contents of package installation image in stow dir.
|
||||||
|
# ============================================================================
|
||||||
sub do_mv {
|
sub do_mv {
|
||||||
my $self = shift;
|
my $self = shift;
|
||||||
my ($src, $dst) = @_;
|
my ($src, $dst) = @_;
|
||||||
|
@ -2198,14 +2213,13 @@ sub do_mv {
|
||||||
# FIXME: Ideally these should be in a separate module.
|
# FIXME: Ideally these should be in a separate module.
|
||||||
|
|
||||||
|
|
||||||
#===== PRIVATE SUBROUTINE ===================================================
|
# ===== PRIVATE SUBROUTINE ===================================================
|
||||||
# Name : internal_error()
|
# Name : internal_error()
|
||||||
# Purpose : output internal error message in a consistent form and die
|
# Purpose : output internal error message in a consistent form and die
|
||||||
# Parameters: $message => error message to output
|
# Parameters: $message => error message to output
|
||||||
# Returns : n/a
|
# Returns : n/a
|
||||||
# Throws : n/a
|
# Throws : n/a
|
||||||
# Comments : none
|
# ============================================================================
|
||||||
#============================================================================
|
|
||||||
sub internal_error {
|
sub internal_error {
|
||||||
my ($format, @args) = @_;
|
my ($format, @args) = @_;
|
||||||
my $error = sprintf($format, @args);
|
my $error = sprintf($format, @args);
|
||||||
|
|
Loading…
Reference in a new issue