[lucy-dev] Upcoming API changes

[Nick Wellnhofer <we...@aevum.de>]

Lucifers,

I decided to postpone my work on Clownfish interfaces and make some necessary 
changes to Lucy first. Rationale:

1. The sooner Lucy users can start to use new APIs or get deprecation
    warnings, the better.

2. Clownfish interfaces aren't strictly needed to address the main issue
    which is to simplify host language extensions.

All the changes revolve around removing ivars from Lucy classes that should be 
extensible from host languages. Here's a list of all such classes I could find.

Analyzer: Doesn't have any ivars.

Highlighter: Deprecate subclassing of Highlighter and provide a class like 
HighlightFormat with Encode and Highlight methods.

IndexManager: AFAICS, only the Recycle method is supposed to be overridden. 
I'd deprecate subclassing of IndexManager. We could add a class like 
MergePolicy, but it's probably enough if users can limit the number of 
documents that are merged after an indexing session with a method like 
Set_Merge_Limit.

Lock/LockFactory: I doubt that there are users who extend these classes from 
Perl, and I already reworked/removed them in my improve-locking branch.

Query/Compiler/Matcher: Query only has a `boost` ivar. This can be moved to an 
intermediate class like BoostQuery. Compiler can be changed to not inherit 
from Query. All its ivars can be moved to an intermediate class or to its 
subclasses. We can emulate the old ivars in Perl with inside-out variables, so 
that old code doesn't require any changes. Matcher has no ivars.

QueryParser: AFAICS, only the Parse method is supposed to be overridden. We 
could add a separate base class for custom query parsers that only contains 
the abstract Parse method. Ideally, the base class would be named QueryParser 
and the current QueryParser renamed to DefaultQueryParser, but this would 
cause too much breakage.

Schema/FieldType: AFAICS, Schema is only subclassed to populate it during 
construction. This could be deprecated. I'm not sure how FieldType is supposed 
to be extended. There's no documentation.

Searcher: Subclassed internally by SearchClient and ClusterSearcher which I 
think can be made standalone classes.

Similarity: Only has a `norm_decoder` ivar. If we remove the ability to 
override Encode_Norm and Decode_Norm, this can be moved to a global variable. 
Otherwise, we could add a separate base class for custom similarities. I guess 
that there aren't many users who subclass Similarity [1], so maybe we could 
rename Similarity to LuceneSimilarity.

Are there other classes I missed? Or better ways to handle the migration?

Maybe it's a good idea to also ask on lucy-user how our users extend Lucy 
classes from Perl.

Nick


[1] Almost all methods of Similarity are undocumented. This should be fixed.

Re: [lucy-dev] Upcoming API changes

[Peter Karman <pe...@peknet.com>]

Nick Wellnhofer wrote on 3/9/17 7:05 AM:

> I decided to postpone my work on Clownfish interfaces and make some necessary
> changes to Lucy first.

+1


> Maybe it's a good idea to also ask on lucy-user how our users extend Lucy
> classes from Perl.


+1


-- 
Peter Karman  .  https://peknet.com/  .  https://keybase.io/peterkarman