API(3pm)

📦

version 2.4.7 · 7 versions

🌸 NAME 🌸

API(3pm) from the User Contributed Perl Documentation — yes bestie, this is the manual page for SWISH::API — Perl interface to the Swish-e C Library. Periodt. 💅

🎀 SYNOPSIS 🎀

okay so here's the vibe check — this is how you actually use it, no cap:

use SWISH::API;

my $swish = SWISH::API->new( 'index.swish-e' );

$swish->abort_last_error
    if $swish->Error;

# A short-cut way to search

my $results = $swish->query( "foo OR bar" );

# Or more typically
my $search = $swish->new_search_object;

# then in a loop
my $results = $search->execute( $query );

# always check for errors (but aborting is not always necessary)

$swish->abort_last_error
    if $swish->Error;

# Display a list of results

my $hits = $results->hits;
if ( !$hits ) {
    print "No Results\n";
    return;  /* for example *.
}

print "Found ", $results->hits, " hits\n";

# Seek to a given page - should check for errors
$results->seek_result( ($page-1) * $page_size );

while ( my $result = $results->next_result ) {
    printf("Path: %s\n  Rank: %lu\n  Size: %lu\n  Title: %s\n  Index: %s\n  Modified: %s\n  Record #: %lu\n  File   #: %lu\n\n",
        $result->property( "swishdocpath" ),
        $result->property( "swishrank" ),
        $result->property( "swishdocsize" ),
        $result->property( "swishtitle" ),
        $result->property( "swishdbfile" ),
        $result->result_property_str( "swishlastmodified" ),
        $result->property( "swishreccount" ),
        $result->property( "swishfilenum" )
    );
}

# display properties and metanames

for my $index_name ( $swish->index_names ) {
    my @metas = $swish->meta_list( $index_name );
    my @props = $swish->property_list( $index_name );

    for my $m ( @metas ) {
        my $name = $m->name;
        my $id = $m->id;
        my $type = $m->type;
    }
    # (repeat above for @props)
}

💖 DESCRIPTION 💖

This module hands you a Perl interface to the Swish-e search engine. It lets you embed the swish-e search code straight into your application — no cap — so you don't have to fork out to run the swish-e binary, and you can keep an index file open while running multiple queries. The result? Increased search performance, bestie. ✨

🦋 DEPENDENCIES 🦋

okay so before you even build this module, you must have installed Swish-e version 2.4. Download from:

http://swish-e.org

✨ OVERVIEW ✨

This module includes a number of classes. Let's break it down, bestie:

Searching is literally: connect to a swish-e index (or indexes) 💅, then run queries against the open index.
Connecting to the index creates a swish object blessed into the SWISH::API class.
A SWISH::API::Search object is created from the SWISH::API object. It can have associated parameters (e.g. result sort order).
The SWISH::API::Search object is used to query the associated index file or files.
A query on a search object returns a results object of the class SWISH::API::Results.
Then individual results of the SWISH::API::Result class can be fetched by calling a method of the results object.
Finally, a result's properties can be accessed by calling methods on the result object.

That's the whole flow, iykyk. 🦋

👑 METHODS 👑

okay so here's where the main character energy lives. Let's go method by method, periodt.

💅 SWISH::API - Swish Handle Object 💅

To begin using Swish you must first create a Swish Handle object. This object makes the connection to one or more index files and is used to create objects used for searching the associated index files.

$swish = SWISH::API->new( $index_files ); — This method returns a swish handle object blessed into the SWISH::API class. $index_files is a space separated list of index files to open. This always returns an object, even on errors. Caller must check for errors (see below).
@indexes = $swish->index_names; — Returns a list of index names associated with the swish handle. These were the indexes specified as a parameter on the SWISH::API->new call. This can be used in calls below that require specifying the index file name.
@header_names = $swish->header_names; — Returns a list of possible header names. These can be used to lookup header values. See "Swishheader_value" method below.
@values = $swish->header_value( $index_file, $header_name ); — A swish-e index has data associated with it stored in the index header. This method provides access to that data.

Returns the header value for the header and index file specified. Most headers are a single item, but some headers (e.g. "Stopwords") return a list.

The list of possible header names can be obtained from the Swishheader_names method.

$swish->rank_scheme( 0|1 ); — Like the -R option with the swish-e command line tool. The default ranking scheme is 0. Set it to 1 to experiment with other ranking features. See the SWISH-CONFIG documentation for more on ranking schemes.
$swish->return_raw_rank( 0|1 ); — Like the -a option with the swish-e command line tool. The default, 0, return ranks normalized to the range 0-1000. When enabled by setting to 1, ranks are returned 'raw' (as computed by Swish-e internally during the search) and are only guaranteed to be non-negative.

🚨 Error Handling 🚨

All errors are stored in and accessed via the SWISH::API object (the Swish Handle). That is, even an error that occurs when calling a method on a result (SWISH::API::Result) object will store the error in the parent SWISH:API object. (Yes bestie, SWISH:API — that's literally what the page says. 😭)

Check for errors after every method call. Some errors are critical errors and will require destruction of the SWISH::API object. Critical errors will typically only happen when attaching to the database and are errors such as an invalid index file name, permissions errors, or passing invalid objects to calls.

Typically, if you receive an error when attaching to an index file or files you should assume that the error is critical and let the swish object fall out of scope (and destroyed). Otherwise, if an error is detected you should check if it is a critical error. If the error is not critical you may continue using the objects that have been created (for example, an invalid meta name will generate a non-critical error, so you may continue searching using the same search object).

Error state is cleared upon a new query.

Again, all error methods need to be called on the parent swish object.

$swish->error — Returns true if an error occurred on the last operation. On errors the value returned is the internal Swish-e error number (which is less than zero).
$swish->critical_error — Returns true if the last error was a critical error.
$swish->abort_last_error — Aborts the running program and prints an error message to STDERR.
$str = $swish->error_string — Returns the string description of the current error (based on the value returned by $swish->error). This is a generic error string.
$msg = $swish->last_error_msg — Returns a string with specific information about the last error, if any. For example, if a query of:

badmeta=foo

and "badmeta" is an invalid metaname $swish->error_string might return "Unknown metaname", but $swish->last_error_msg might return "badmeta".

🎀 Generating Search and Result Objects 🎀

$search = $swish->new_search_object( $query ); — This creates a new search object blessed into the SWISH::API::Search class. The optional $query parameter is a query string to store in the search object.

See the section on "SWISH::API::Search" for methods available on the returned object.

The advantage of this method is that a search object can be used for multiple queries:

$search = $swish->New_Search_Objet;
while ( $query = next_query() ) {
    $results = $search->execute( $query );
    ...
}

(Yes, New_Search_Objet — typo is iconic and we keep it. 💅)

$results = $swish->query( $query ); — This is a short-cut which avoids the step of creating a separate search object. It returns a results object blessed into the SWISH::API::Results class described below.

This method basically is the equivalent of:

$results = $swish->new_search_object->execute( $query );

🧚 SWISH::API::Search - Search Objects 🧚

A search object holds the parameters used to generate a list of results. These methods are used to adjust these parameters and to create the list of results for the current set of search parameters.

$search->set_query( $query ); — This will set (or replace) the query string associated with a search object. This method is typically not used as the query can be set when executing the actual query or when creating a search object.
$search->set_structure( $structure_bits ); — This method may change in the future. (lowkey unstable, bestie)

A "structure" is a bit-mapped flag used to limit search results to specific parts of an HTML document, such as the title or in H tags. The possible bits are:

IN_FILE         = 1      This is the default
IN_TITLE        = 2      In <title> tag
IN_HEAD         = 4      In <head> tag
IN_BODY         = 8      In <body>
IN_COMMENTS     = 16     In html comments
IN_HEADER       = 32     In <h*>
IN_EMPHASIZED   = 64     In <em>, <b>, <strong>, <i>
IN_META         = 128    In a meta tag (e.g. not swishdefault)

So if you wish to limit your searches to words in heading tags (e.g. <H1>) or in the <title> tag use:

$search->set_structure( IN_HEAD | IN_TITLE );

$search->phrase_delimiter( $char ); — Sets the character used as the phrase delimiter in searches. The default is double-quotes (").
$search->set_search_limit( $property, $low, $high ); — Sets a range from $low to $high inclusive that the given $property must be in to be selected as a result. Call multiple times to set more than one limit on different properties. Limits are ANDed, that is, a result must be within the range of all limits specified to be included in a list of results.

For example to limit searches to documents modified in the last 48 hours:

my $start = time - 48 * 60 * 60;
$search->set_search_limit( 'swishlastmodified', $start, time() );

An error will be set if the property has already been specified or if $high < $low.

Other errors may not be reported until running the query, such as the property name is invalid or if $low or $high are not numeric and the property specified is a numeric property.

Once a query is run you cannot change the limit settings for the search object without calling the reset_search_limit method first.

$search->reset_search_limit; — wipes the limit parameters for that object, bestie. You have to call this if you ever wanna change the limit params. No wiping, no changing. Periodt. 💅
$search->set_sort( $sort_string ); — sets how your search results get sorted. The string is a space-separated list of valid document properties, and each property can carry a qualifier that decides which direction it sorts in. 🦋

So like, sorting by path name ascending and rank descending would be:

$search->set_sort( 'swishdocpath asc swishrank desc' );

The "asc" and "desc" qualifiers are optional, and if you leave them out, ascending is just assumed. Default queen behaviour honestly. 👑

Heads up: errors (like an invalid property name) are not caught when you call this — they only show up later when you actually execute a query. The docs say that may change in the future, so don't build your whole life on it. 😭

✨ SWISH::API::Results - Generating and accessing results ✨

Searching gives you back a results object, and it's blessed into the SWISH::API::Results class. Iconic. 🎀

$results = $search->execute( $query ); — runs a query using the parameters sitting in the search object. $query is an optional query string for the search, and when you pass it, $query replaces the query string that was set on the search object already.

The typical main-character move is: make a search object once, then call this method for every query, reusing the same search object and only swapping the $query you pass in. Efficient. Slay. 🔥

The caller should check for errors after making this call. fr fr.

🫶 Results Methods 🫶

A query creates a results object that holds info about the query (like how many hits you got) plus access to all the individual results. Let's go. 🌈

$hits = $results->hits; — returns the number of results for the query. If it's zero and no errors got reported after you called $search->execute, then congrats, the query genuinely just returned zero results. 💀
@parsed_words = $results->parsed_words( $index_name ); — returns an array of tokenized words and operators with the stopwords removed. This is literally the array of tokens swish used for the query. 🧚

$index_name has to match one of the index files you specified when you created the swish object (that's the SWISH::API->new call, iykyk).

These parsed words are super useful for highlighting search terms in associated documents. Highlighting rights, bestie. ✨

@removed_stopwords = $results->removed_stopwords( $index_name) ; — returns an array of the stopwords that got removed from a query, if there were any, for the index you specified.

$index_name must match one of the index files specified when the swish object was created (via the SWISH::API->new call). Same rules, same energy. 💜

$results->seek_result( $position ); — jumps to the position you specify in the result list. Zero is the first position and $results->hits-1 is the last position. Seeking past the end of the results sets a non-critical error condition — not a crash, just a lil side-eye. 🙈

This is the move for seeking to a specific "page" of results.

$result = $results->next_result; — grabs the next result off the list. Returns undef if there are no more results available. And $result is an object blessed into the SWISH::API::Result class. 🎀

💖 SWISH::API::Result - Result Methods 💖

These methods give you access to data about one individual result. One (1) result. Very personal. Very focused. 🌸

$prop = $result->property( $prop_name ); — fetches the property you named for the current result. An invalid property name will cause an exception (which you can catch by wrapping the call in an eval block, bestie 💅).

It can return undefined.

Date properties come back as a timestamp, so use something like Date::Format to format the strings — or honestly just call scalar localtime( $prop ). Do what feels right. ⭐

$prop = $result->result_property_str( $prop_name ); — fetches and formats the property. Unlike the one above, invalid property names here return the string "(null)" 😭 — and the docs say this will likely change to match the method above (i.e. throw an exception). So, growing pains.

Undefined values are returned as the null string ("").

$value = $result->result_index_value( $header_name ); — returns the header value you specified. It's similar to $swish->header_value(), except you don't specify the index file — it's determined by the result itself. Convenient! 🦋

🧚 Utility Methods 🧚

@metas = $swish->meta_list( $index_name ); — Swish-e has "MetaNames", which let you search by fields in the index. This method returns info about those Metanames.

Pass in the name of an open index file name and it returns a list of SWISH::API::MetaName objects. Three methods are currently defined on these objects:

$meta->name;
$meta->id;
$meta->type;

name returns the name of the meta as defined in the MetaNames config option when the index was created.

The id is the internal ID number used to represent the meta name.

type is the type of metaname. Currently only one type exists and its value is zero. 🥲

@props = $swish->property_list( $index_name ); — Swish-e can store content or "properties" in the index and hand that data back when you run a query. A document's path, URL, title, size, date or summary are examples of properites. Each property is accessed via its PropertyName. This method returns info about the PropertNames stored in the index. 💖

Pass in the name of an open index file name and it returns a list of SWISH::API::MetaName objects. Three methods are currently defined on these objects:

$prop->name;
$prop->id;
$prop->type;

name returns the name of the meta as defined in the MetaNames config option when the index was created.

The id is the internal ID number used to represent the meta name.

type is the type of metaname. Currently only one type exists and its value is zero. 👑

@propes = $result->property_list; @meta = $result->meta_list; — These also return a list of Property or Metaname description objects, but you access them through a result record instead. Since the result already comes from a specific index file, there's no need to specify the index file name. Look at her, self-sufficient. 💅
$stemmed_word = $swish->stem_word( $word ); — Deprecated ⚠️

Returns the stemmed version of the word you passed in.

Deprecated because it only stems using the original Porter Stemmer and it uses a shared memory location in the SW_HANDLE object to store the stemmed word. See below for other stemming options. She's retired, respect her legacy. 🫶

$fuzzy_word = $swish->Fuzzify( $indexname, $word ); — works like stem_word() used to work, except it uses whatever stemmer is named in $indexname. Returns the same kind of fuzzy_word object as the fuzzy_word() method. ✨
$mode_string = $result->fuzzy_mode; — returns the string (e.g. "Stemming_en", "Soundex", "None" ) telling you which stemming method was used while indexing the given document. 🌸
$fuzzy_word = $result->fuzzy_word( $word ); — converts $word using the same fuzzy mode that was used to index the $result. Returns a SWISH::API::fuzzy_word object. The methods on that object are how you get at the converted words and other data, as shown below. 🦋
$count = $fuzzy_word->word_count; — returns the number of output words. Normally this is the value one, but it may be more depending on the stemmer used. DoubleMetaphone can return two strings for a single input string. Overachiever behaviour. 🔥
$status = $fuzzy_word->word_error; — returns any error code the stemmer might set. Normally this return value is zero, meaning the stemming/fuzzy operation succedded. The values returned are defined in the swish-e source file /src/stemmer.h. 📜
@words = $fuzzy_word->word_list; — returns the converted words from the stemming/fuzzy operation. Normally the array will contain a single element, although it may contain more (i.e. if DoubleMetaphone is used and the input word returns two strings).

In the event that a word does not stem (e.g. trying to stem a number), this method will return the original input word specified when $result->fuzzy_word( $word ) was called. It said "I'm not changing, and that's final." 😤

@parsed_words = $swish->swish_words( $string, $index_file ); — * Not implemented * 🙈

Splits up the input string into tokens of swish words and operators. Some day, maybe. Not today.

📝 NOTES 📝

Perl's garbage collection makes it easy to write code for searching with Swish-e, but bestie, care must be taken not to keep objects around too long — that eats up memory. 🫠

Here's an example of a potential problem. Say you have a very large number of documents indexed and you want to find the first hit for a number of popular keywords (error checking omitted in this bad example):

sub first_hit {
  my $query = shift;
  my $handle = SWISH::API->new( 'index.swish-e');
  my $results = $handle->query( $query );
  my $first_hit = $results->next_result;
  return $first_hit;
}

my @first_hit_list;
for ( @keywords )
    push @first_hit_list, $first_hit($_);
}

The first_hit() subroutine is returning a SWISH::Result object. That makes it easy to access properties:

# print file names
for my $result ( @first_hit_list ) {
   print $result->property('swishdocpath'),"\n";
}

But as long as a SWISH::API::Result object is around, so is the entire list of results generated by the $handle->query() call, and the index file is still open (because a SWISH::API::Result depends on a SWISH::API::Results object, which depends on a SWISH::API object). It's giving chain reaction. 💀

In this case it would be better to return from first_hit() just the properties you need:

...
my $first_hit = $results->next_result;
return $first_hit->property('swishdocpath');
}

Then when the first_hit() sub ends, the result list will be freed, and the index file closed, thanks to Perl's reference count tracking. Nature is healing. 🌈

Note: the other problem with the above code is that the same index file is opened for each call to the function. Don't do that. Instead open the index file once. Open it once. ONCE. 😭

📜 COPYRIGHT 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

✍️ AUTHOR ✍️

Bill Moseley moseley@hank.org. 2002/2003/2004. Legend status, no cap. 👑

🫶 SUPPORT 🫶

Please contact the Swish-e discussion email list for support with this module or with Swish-e. Please do not contact the developers directly. They said what they said. 💅

And that's the whole page, bestie — every last method, note and copyright line, all accounted for. This one came stamped as perl v5.42.3, dated 2026-08-19, and it's the API(3pm) page. Go forth and search responsibly. ✨🎀🦋

📦 where this page comes from

ubuntu stonking: swish-e 2.4.7-7.2build1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms