From: Simon McVittie <smcv@debian.org>
Date: Mon, 15 Sep 2014 20:15:31 +0000 (+0100)
Subject: Merge branch 'ready/document-success-reason'
X-Git-Tag: 3.20140916~15
X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/commitdiff_plain/7dcf18dba52674c8cd518aadaf68a2400196d592?hp=-c

Merge branch 'ready/document-success-reason'
---

7dcf18dba52674c8cd518aadaf68a2400196d592
diff --combined IkiWiki.pm
index 49ac97196,5bb89e6aa..f30a946bf
--- a/IkiWiki.pm
+++ b/IkiWiki.pm
@@@ -1819,8 -1819,7 +1819,8 @@@ sub loadindex () 
  			open ($in, "<", "$config{wikistatedir}/indexdb") || return;
  		}
  		else {
 -			$config{gettime}=1; # first build
 +			# gettime on first build
 +			$config{gettime}=1 unless defined $config{gettime};
  			return;
  		}
  	}
@@@ -2460,19 -2459,6 +2460,19 @@@ sub pagespec_match ($$;@) 
  	return $sub->($page, @params);
  }
  
 +# e.g. @pages = sort_pages("title", \@pages, reverse => "yes")
 +#
 +# Not exported yet, but could be in future if it is generally useful.
 +# Note that this signature is not the same as IkiWiki::SortSpec::sort_pages,
 +# which is "more internal".
 +sub sort_pages ($$;@) {
 +	my $sort = shift;
 +	my $list = shift;
 +	my %params = @_;
 +	$sort = sortspec_translate($sort, $params{reverse});
 +	return IkiWiki::SortSpec::sort_pages($sort, @$list);
 +}
 +
  sub pagespec_match_list ($$;@) {
  	my $page=shift;
  	my $pagespec=shift;
@@@ -2578,21 -2564,48 +2578,48 @@@ our @ISA = 'IkiWiki::SuccessReason'
  
  package IkiWiki::SuccessReason;
  
+ # A blessed array-ref:
+ #
+ # [0]: human-readable reason for success (or, in FailReason subclass, failure)
+ # [1]{""}:
+ #      - if absent or false, the influences of this evaluation are "static",
+ #        see the influences_static method
+ #      - if true, they are dynamic (not static)
+ # [1]{any other key}:
+ #      the dependency types of influences, as returned by the influences method
+ 
  use overload (
+ 	# in string context, it's the human-readable reason
  	'""'	=> sub { $_[0][0] },
+ 	# in boolean context, SuccessReason is 1 and FailReason is 0
  	'0+'	=> sub { 1 },
+ 	# negating a result gives the opposite result with the same influences
  	'!'	=> sub { bless $_[0], 'IkiWiki::FailReason'},
+ 	# A & B = (A ? B : A) with the influences of both
  	'&'	=> sub { $_[1]->merge_influences($_[0], 1); $_[1] },
+ 	# A | B = (A ? A : B) with the influences of both
  	'|'	=> sub { $_[0]->merge_influences($_[1]); $_[0] },
  	fallback => 1,
  );
  
+ # SuccessReason->new("human-readable reason", page => deptype, ...)
+ 
  sub new {
  	my $class = shift;
  	my $value = shift;
  	return bless [$value, {@_}], $class;
  }
  
+ # influences(): return a reference to a copy of the hash
+ # { page => dependency type } describing the pages that indirectly influenced
+ # this result, but would not cause a dependency through ikiwiki's core
+ # dependency logic.
+ #
+ # See [[todo/dependency_types]] for extensive discussion of what this means.
+ #
+ # influences(page => deptype, ...): remove all influences, replace them
+ # with the arguments, and return a reference to a copy of the new influences.
+ 
  sub influences {
  	my $this=shift;
  	$this->[1]={@_} if @_;
@@@ -2601,15 -2614,43 +2628,43 @@@
  	return \%i;
  }
  
+ # True if this result has the same influences whichever page it matches,
+ # For instance, whether bar matches backlink(foo) is influenced only by
+ # the set of links in foo, so its only influence is { foo => DEPEND_LINKS },
+ # which does not mention bar anywhere.
+ #
+ # False if this result would have different influences when matching
+ # different pages. For instance, when testing whether link(foo) matches bar,
+ # { bar => DEPEND_LINKS } is an influence on that result, because changing
+ # bar's links could change the outcome; so its influences are not the same
+ # as when testing whether link(foo) matches baz.
+ 
  sub influences_static {
  	return ! $_[0][1]->{""};
  }
  
+ # Change the influences of $this to be the influences of "$this & $other"
+ # or "$this | $other".
+ #
+ # If both $this and $other are either successful or have influences,
+ # or this is an "or" operation, the result has all the influences from
+ # either of the arguments. It has dynamic influences if either argument
+ # has dynamic influences.
+ #
+ # If this is an "and" operation, and at least one argument is a
+ # FailReason with no influences, the result has no influences, and they
+ # are not dynamic. For instance, link(foo) matching bar is influenced
+ # by bar, but enabled(ddate) has no influences. Suppose ddate is disabled;
+ # then (link(foo) and enabled(ddate)) not matching bar is not influenced by
+ # bar, because it would be false however often you edit bar.
+ 
  sub merge_influences {
  	my $this=shift;
  	my $other=shift;
  	my $anded=shift;
  
+ 	# This "if" is odd because it needs to avoid negating $this
+ 	# or $other, which would alter the objects in-place. Be careful.
  	if (! $anded || (($this || %{$this->[1]}) &&
  	                 ($other || %{$other->[1]}))) {
  		foreach my $influence (keys %{$other->[1]}) {
@@@ -2622,6 -2663,8 +2677,8 @@@
  	}
  }
  
+ # Change $this so it is not considered to be influenced by $torm.
+ 
  sub remove_influence {
  	my $this=shift;
  	my $torm=shift;