SWISH:...Common(3pm)

💖 SWISH::API::Common — SWISH Document Indexing Made Easy 💖

okay bestie, gather round, because this is the page for SWISH::API::Common (you'll see it shortened to SWISH:...Common(3pm) in your man pager, but the real name is the full module name, iykyk). It's the soft-launch, easy-mode front door to the Swish index engine, and honestly? It's giving "just let me search my docs, please." 🦋

---

✨ SYNOPSIS ✨

use SWISH::API::Common;

my $swish = SWISH::API::Common->new();

    # Index all files in a directory and its subdirectories
$swish->index("/usr/local/share/doc");

    # After indexing once (it's persistent), fire up as many
    # queries as you like:

    # Search documents containing both "swish" and "install"
for my $hit ($swish->search("swish AND install")) {
    print $hit->path(), "\n";
}

like, that's it. that's the whole vibe. index once, query forever. 👑

---

🌸 DESCRIPTION 🌸

SWISH::API::Common offers an easy interface to the Swish index engine. So like, SWISH::API is the full-on, everything-included, no-notes version — and SWISH::API::Common is the curated playlist that focusses on ease of use. 💅

⚠️ THIS MODULE IS CURRENTLY UNDER DEVELOPMENT. THE API MIGHT CHANGE AT ANY TIME. not me warning you that your code could get a glow-up overnight 😭 — please be aware, bestie.

Currently, SWISH::API::Common just allows for indexing documents in a single directory and any of its subdirectories. Also, don't run index() and search() in parallel yet — fr fr, they're not ready to share the aux cord. 🙈

---

🎀 INSTALLATION 🎀

SWISH::API::Common requires SWISH::API and the swish engine to be installed. Please download the latest release from

http://swish-e.org/distribution/swish-e-2.4.3.tar.gz

and untar it, type

./configure
make
make install

and then install SWISH::API which is contained in the distribution:

cd perl
perl Makefile.PL
make
make install

okay so it's a little bit of a two-step, but you got this. 💪✨

🫶 METHODS 🫶

• $sw = SWISH::API::Common->new() — Constructor. Takes many options, but the defaults are usually fine. (main character energy: does a lot, asks for almost nothing.)

Available options and their defaults:

        # Where SWISH::API::Common stores index files etc.
    swish_adm_dir   "$ENV{HOME}/.swish-common"

        # The path to swish-e, relative is OK
    swish_exe       "swish-e"

        # Swish index file
    swish_idx_file  "$self->{swish_adm_dir}/default.idx"

        # Swish configuration file
    swish_cnf_file  "$self->{swish_adm_dir}/default.cnf"

        # SWISH Stemming
    swish_fuzzy_indexing_mode => "Stemming_en"

        # Maximum amount of data (in bytes) extracted
        # from a single file
    file_len_max 100_000

        # Preserve every indexed file's atime
    atime_preserve

• $sw->index($dir, ...) — Generate a new index of all text documents under directory $dir. One or more directories can be specified. yes you CAN pass several, she's flexible like that 🌈
• $sw->search("foo AND bar"); — Searches the index, using the given search expression. Returns a list hits, which can be asked for their path:

        # Search documents containing
        # both "foo" and "bar"
    for my $hit ($swish->search("foo AND bar")) {
        print $hit->path(), "\n";
    }

• index_remove — Permanently delete the current index. 💀 Permanently. Gone. No undo, no recycle bin, no "wait I didn't mean it." Be so sure.

⭐ TODO List ⭐

the to-do list, the manifesting board, the "we'll get to it" — currently it reads:

1. More than one index directory
1. Remove documents from index
1. Iterator for search hits

one day. 👑✨

---

🧚 LEGALESE 🧚

Copyright 2005 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. (aka: share it, remix it, keep the receipts. 🫶)

---

💜 AUTHOR 💜

2005, Mike Schilli <cpan@perlmeister.com>

---

and that's a wrap, bestie! 🎉 this page is perl v5.34.0, dated 2022-06-18, and it was a whole vibe from SWISH:...Common(3pm) header to footer. go index something iconic. 💖🌸💅