More documentation and tests
diff --git a/lib/Kalamar.pm b/lib/Kalamar.pm
index a19a916..58558ff 100644
--- a/lib/Kalamar.pm
+++ b/lib/Kalamar.pm
@@ -18,7 +18,7 @@
# Add additional plugin path
push(@{$self->plugins->namespaces}, __PACKAGE__ . '::Plugin');
- # korap.ids-mannheim.de specific
+ # korap.ids-mannheim.de specific path prefixing
$self->hook(
before_dispatch => sub {
my $c = shift;
@@ -30,6 +30,7 @@
}) if $self->mode eq 'production';
# Cache static assets
+ # (not necessary, as long as shipped by nginx or Apache)
$self->hook(
after_static => sub {
my $res = shift->res;
@@ -40,9 +41,9 @@
# Set secrets for signed cookies
if (-e (my $secret = $self->home . '/kalamar.secret')) {
- $self->secrets([
- b($secret)->slurp->split("\n")
- ]);
+
+ # Load file and split lines for multiple secrets
+ $self->secrets([b($secret)->slurp->split("\n")]);
}
else {
$self->log->warn('Please create a kalamar.secret file');
@@ -55,9 +56,10 @@
'Notifications', # Client notifications
'Search', # Abstract Search framework
'CHI', # Global caching mechanism
+ 'MailException' # Alert via Email on exception
'TagHelpers::Pagination', # Pagination widget
'TagHelpers::MailToChiffre', # Obfuscate email addresses
- 'KalamarHelpers' # Specific Helpers for Kalamar
+ 'KalamarHelpers', # Specific Helpers for Kalamar
) {
$self->plugin($_);
};
@@ -72,10 +74,10 @@
# Establish routes
my $r = $self->routes;
- # Base query page
+ # Base query route
$r->get('/')->to('search#query')->name('index');
- # Documentation
+ # Documentation routes
$r->get('/doc')->to('documentation#page', page => 'korap')->name('doc_start');
$r->get('/doc/:page')->to('documentation#page', scope => undef);
$r->get('/doc/*scope/:page')->to('documentation#page')->name('doc');
diff --git a/lib/Kalamar/Controller/Search.pm b/lib/Kalamar/Controller/Search.pm
index 13af8c5..913abc2 100644
--- a/lib/Kalamar/Controller/Search.pm
+++ b/lib/Kalamar/Controller/Search.pm
@@ -66,11 +66,12 @@
};
-
# Get information about a match
+# Note: This is called 'match_info' as 'match' is reserved
sub match_info {
my $c = shift;
+ # Old API foundry/layer usage
my $foundry = '*';
my %query = (foundry => '*');
if ($c->param('foundry')) {
@@ -83,6 +84,7 @@
};
};
+ # Async
$c->render_later;
# Use the API for fetching matching information non-blocking
@@ -136,7 +138,8 @@
=head1 DESCRIPTION
L<Kalamar::Controller::Search> is the controller class for
-search related endpoints in Kalamar.
+search related endpoints in Kalamar. Actions are released when routes
+match.
=head1 METHODS
@@ -144,39 +147,85 @@
L<Kalamar::Controller::Search> inherits all methods from
L<Mojolicious::Controller> and implements the following new ones.
-=head2 search
+=head2 query
-Action for all documentation pages.
+ GET /?q=Baum&ql=poliqarp
+
+Action for all queries to the system. Returns C<HTML> only for the moment.
+
+The following parameters are supported.
+
=head3 q
-Query parameter
+The query string. This may any query written in a supported query language.
=head3 ql
-Query language
+The query language. This may be any query language supported by the system,
+written as the API expects the string.
=head3 action
-May be C<inspect>.
+May be C<inspect>. In that case, the serialized request is mirrored instead of
+processed.
+
+B<This switch is experimental and may change without warnings!>
+
=head3 snippet
+If set, the query is returned in the snippet view template.
+
+B<This parameter is experimental and may change without warnings!>
+
+
=head3 cutoff
+If set, the query will be cut off after the matches.
+
+B<This parameter is directly forwarded to the API and may not be supported in the future.>
+
+
=head3 count
+If set, the query will be only return the given number of matches,
+in case the API supports it. Will fallback to the default number of matches defined
+by the API or the backend.
+
+B<This parameter is directly forwarded to the API and may not be supported in the future.>
+
+
=head3 p
-Number of page
+If set, the query will page to the given number of pages in the result set.
+Will default to 1.
+
+B<This parameter is directly forwarded to the API and may not be supported in the future.>
+
=head2 match
-/:corpus_id/:doc_id/:text_id/:match_id
+ /:corpus_id/:doc_id/:text_id/:match_id?foundry=*
+
+Returns information to a match either as a C<JSON> or an C<HTML> document.
+The path defines the concrete match, by corpus identifier, document identifier,
+text identifier (all information as given by DeReKo), and match identifier
+(essentially the position of the match in the document, including highlight information).
+
+The following parameters are supported.
+
=head3 foundry
+Expects a foundry definition for retrieved information.
+If not given, returns all annotations for the match.
+If given, returns only given layer information for the defined foundry.
+
+B<This parameter is experimental and may change without warnings!>
+
+
=head3 layer
=head3 spans
@@ -201,13 +250,13 @@
Author: L<Nils Diewald|http://nils-diewald.de/>
Kalamar is developed as part of the L<KorAP|http://korap.ids-mannheim.de/>
-Corpus Analysis Platform at the Institute for German Language
-(L<IDS|http://ids-mannheim.de/>),
-funded by the
+Corpus Analysis Platform at the
+L<Institute for the German Language (IDS)|http://ids-mannheim.de/>,
+member of the
L<Leibniz-Gemeinschaft|http://www.leibniz-gemeinschaft.de/en/about-us/leibniz-competition/projekte-2011/2011-funding-line-2/>
and supported by the L<KobRA|http://www.kobra.tu-dortmund.de> project,
-funded by the Federal Ministry of Education and Research
-(L<BMBF|http://www.bmbf.de/en/>).
+funded by the
+L<Federal Ministry of Education and Research (BMBF)|http://www.bmbf.de/en/>.
Kalamar is free software published under the
L<BSD-2 License|https://raw.githubusercontent.com/KorAP/Kalamar/master/LICENSE).