[[!tag patch]]
The available [[ikiwiki/pagespec/sorting]] methods are currently hard-coded in
IkiWiki.pm, making it difficult to add any extra sorting mechanisms. I've
prepared a branch which adds 'sort' as a hook type and uses it to implement a
new meta_title sort type.
Someone could use this hook to make \[[!inline sort=title]] prefer the meta
title over the page name, but for compatibility, I'm not going to (I do wonder
whether it would be worth making sort=name an alias for the current sort=title,
and changing the meaning of sort=title in 4.0, though).
[sort-hooks branch now withdrawn in favour of sort-package --s]
I briefly tried to turn all the current sort types into hook functions, and
have some of them pre-registered, but decided that probably wasn't a good idea.
That earlier version of the branch is also available for comparison:
[also withdrawn in favour of sort-package --s]
I wonder if IkiWiki would benefit from the concept of a "sortspec", like a [[ikiwiki/PageSpec]] but dedicated to sorting lists of pages rather than defining lists of pages? Rather than defining a sort-hook, define a SortSpec class, and enable people to add their own sort methods as functions defined inside that class, similarly to the way they can add their own pagespec definitions. --[[KathrynAndersen]]
[[!template id=gitbranch branch=smcv/sort-package author="[[Simon_McVittie|smcv]]"]]
I'd be inclined to think that's overkill, but it wasn't very hard to
implement, and in a way is more elegant. I set it up so sort mechanisms
share the IkiWiki::PageSpec package, but with a cmp_ prefix. Gitweb:
http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-package
I agree it seems more elegant, so I have focused on it.
I don't know about reusing IkiWiki::PageSpec for this.
--[[Joey]]
Fair enough, IkiWiki::SortSpec::cmp_foo would be just
as easy, or IkiWiki::Sorting::cmp_foo if you don't like
introducing "sort spec" in the API. I took a cue from
[[ikiwiki/pagespec/sorting]] being a subpage of
[[ikiwiki/pagespec]], and decided that yes, sorting is
a bit like a pagespec :-) Which name would you prefer? --s
I would be inclined to drop the check_ stuff. --J
It basically exists to support title_natural, to avoid
firing up the whole import mechanism on every cmp
(although I suppose that could just be a call to a
memoized helper function). It also lets sort specs that
must have a parameter, like
[[field|plugins/contrib/field/discussion]], fail early
(again, not so valuable).
The former function could be achieved at a small
compatibility cost by putting title_natural in a new
sortnatural plugin (that fails to load if you don't
have title_natural), if you'd prefer - that's what would
have happened if title_natural was written after this
code had been merged, I suspect. Would you prefer this? --s
Wouldn't it make sense to have meta(title) instead
of meta_title? --J
Yes, you're right. I added parameters to support field,
and didn't think about making meta use them too.
However, title does need a special case to make it
default to the basename instead of the empty string.
Another special case for title is to use titlesort
first (the name titlesort is derived from Ogg/FLAC
tags, which can have titlesort and artistsort).
I could easily extend that to other metas, though;
in fact, for e.g. book lists it would be nice for
field(bookauthor) to behave similarly, so you can
display "Douglas Adams" but sort by "Adams, Douglas".
meta_title is also meant to be a prototype of how
sort=title could behave in 4.0 or something - sorting
by page name (which usually sorts in approximately the
same place as the meta-title, but occasionally not), while
displaying meta-titles, does look quite odd. --s
As I read the regexp in cmpspec_translate, the "command"
is required to have params. They should be optional,
to match the documentation and because most sort methods
do not need parameters. --J
No, $2 is either \w+\([^\)]*\) or [^\s]+ (with the
latter causing an error later if it doesn't also match \w+).
This branch doesn't add any parameterized sort methods,
in fact, although I did provide one on
[[field's_discussion_page|plugins/contrib/report/discussion]]. --s
I wonder if it would make sense to add some combining keywords, so
a sortspec reads like sort="age then ascending title"
In a way, this reduces the amount of syntax that needs to be learned.
I like the "then" (and it could allow other operations than
simple combination, if any others make sense). Not so sure about the
"ascending", which could be "reverse" instead, but "descending age" and
"ascending age" both seem useful to be able to explicitly specify.
--[[Joey]]
Perhaps. I do like the simplicity of [[KathrynAndersen]]'s syntax
from [[plugins/contrib/report]] (which I copied verbatim, except for
turning sort-by-field into a parameterized spec), and I can't really
think of any sensible way to combine sort specs other than "sort by a,
break ties by b, ...", possibly with some reversals thrown in.
If no other combinations do make sense, is your proposal that "then"
is entirely redundant (easy, just make it a predefined sort spec that
returns 0!), or that it's mandatory "punctuation" (add an explicit
check, or make "then" expand to "||" and let Perl fail to compile
the generated code if it's omitted)?
It is a little unfortunate that reversal has to move into the sort
spec - I prefer reverse=yes - but that's necessary for multi-level
sorting. I can see your point about ascending/descending being more
obvious to look at, but they're also considerably more verbose.
Unfortunately, sort="ascending mtime" actually sorts by descending
timestamp (butsort=age is fine, because age could be defined as
now minus ctime). sort=freshness isn't right either, because
"sort by freshness" seems as though it ought to mean freshest first,
but "sort by ascending freshness" means put the least fresh first. If
we have ascending and descending keywords which are optional, I don't
think we really want different sort types to have different default
directions - it seems clearer to have ascending always be a no-op,
and descending always negate.
Perhaps we could borrow from meta updated and use update_age?
updateage would perhaps be a more normal IkiWiki style - but that
makes me think that updateage is a quantity analagous to tonnage or
voltage, with more or less recently updated pages being said to have
more or less updateage. I don't know whether that's good or bad :-)
I'm sure there's a much better word, but I can't see it. Do you have
a better idea? --s
Documentation from sort-package branch
meta_title sort order (conditionally added to [[ikiwiki/pagespec/sorting]])
Multiple sort orders (added to [[ikiwiki/pagespec/sorting]])
In addition, you can combine several sort orders and/or reverse the order of
sorting, with a string like age -title (which would sort by age, then by
title in reverse order if two pages have the same age).
meta title sort parameter (added to [[ikiwiki/directive/meta]])
An optional sort parameter will be used preferentially when
[[ikiwiki/pagespec/sorting]] by meta_title:
\[[!meta title="The Beatles" sort="Beatles, The"]]
\[[!meta title="David Bowie" sort="Bowie, David"]]
Sorting plugins (added to [[plugins/write]])
Similarly, it's possible to write plugins that add new functions as
[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
the IkiWiki::PageSpec package named cmp_foo, which will be used when sorting
by foo or foo(...) is requested.
The function will be passed three or more parameters. The first two are
page names, and the third is undef if invoked as foo, or the parameter
"bar" if invoked as foo(bar). It may also be passed additional, named
parameters.
It should return the same thing as Perl's cmp and <=> operators: negative
if the first argument is less than the second, positive if the first argument
is greater, or zero if they are considered equal. It may also raise an
error using error, for instance if it needs a parameter but one isn't
provided.
You can also define a function called check_cmp_foo in the same package.
If you do, it will be called while preparing to sort by foo or foo(bar),
with argument undef or "bar" respectively; it may raise an error using
error, if sorting like that isn't going to work.
|
