NAME

Kasago - A Perl source code indexer

SYNOPSIS

  my $kasago = Kasago->new({ dbh => $dbh });
  $kasago->init; # this creates the tables for you
  
  # import/update a directory
  $kasago->import($source, $dir);
  # delete a directory
  $kasago->delete($source);

  my @sources = $kasago->sources;
  my @files   = $kasago->files($source);
  my @tokens  = $kasago->tokens($source, $file);

  # search for a token
  foreach my $token ($kasago->search('orange')){
    print $token->source . "/"
      . $token->file . "@"
      . $token->col . ","
      . $token->row . ": "
      . $token->line . "\n";
  }

  # search for a token, merging lines
  foreach my $hit ($kasago->search_merged($search)) {
    print $hit->source . "/"
      . $hit->file . "@"
      . $hit->row . ": "
      . $hit->line . "\n";
    foreach my $token (@{ $hit->tokens }) {
      print "  @" . $token->col . ": " . $token->value . "\n";
    }
  }  

  # search for tokens
  foreach my $token ($kasago->search_more($search)) {
    print $token->source . "/"
      . $token->file . "@"
      . $token->col . ","
      . $token->row . ": "
      . $token->line . "\n";
  }

  # searh for tokens, merging lines
  foreach my $hit ($kasago->search_more_merged($search)) {
    print $hit->source . "/"
      . $hit->file . "@"
      . $hit->row . ": "
      . $hit->line . "\n";
    foreach my $token (@{ $hit->tokens }) {
      print "  @" . $token->col . ": " . $token->value . "\n";
    }
  }
  

DESCRIPTION

Kasago is a module for indexing Perl source code. You can index source trees, and then query the index for symbols, strings, and documentation.

Kasago uses the PPI module to parse Perl and stores the index in a PostegreSQL database. Thus you need to have DBD::Pg installed and a database available for Kasago.

Why is this called Kasago? Because that's the Japanese name for a beautiful fish.

METHODS

new

This is the constructor. It takes a DBI database handle as a parameter. This must be a valid dababase handle for a PostgreSQL database, constructed along the lines of 'my $dbh = DBI->connect("DBI:Pg:dbname=kasago", "", "")':

  my $kasago = Kasago->new({ dbh => $dbh });

delete

This deletes a source from the index:

  $kasago->delete($source);

files

Given a source, returns a list of the files indexed in that source:

  my @files   = $kasago->files($source);

import

This recursively imports a directory into Kasago. If the source is already indexed, the index is updated. You pass a source name and the directory path:

  $kasago->import($source, $dir);

init

This created the tables needed by Kasago in the database. You only need run this once. If you run this after initialisation, it will delete the index.

  $kasago->init;

search

This searches the index for an individual token:

    foreach my $token ($kasago->search('orange')){
      print $token->source . "/"
        . $token->file . "@"
        . $token->col . ","
        . $token->row . ": "
        . $token->line . "\n";
    }

search_merged

This searches the index for an individual token, but merges multiple tokens on the same line together:

    foreach my $hit ($kasago->search_merged($search)) {
      print $hit->source . "/"
        . $hit->file . "@"
        . $hit->row . ": "
        . $hit->line . "\n";
      foreach my $token (@{ $hit->tokens }) {
        print "  @" . $token->col . ": " . $token->value . "\n";
      }
    }  
    

search_more

This searches the index for tokens. "orange" would return all hits for orange, "orange leon" would return all hits for both "orange" and "leon". "orange -leon" shows all the hits for "orange" but without files that contain "leon", "+orange +leon" returns hits in files that contain both "orange" and "leon":

  foreach my $token ($kasago->search_more($search)) {
    print $token->source . "/"
      . $token->file . "@"
      . $token->col . ","
      . $token->row . ": "
      . $token->line . "\n";
  }
  

search_more_merged

This searches the index for tokens as search_more, but merges multiple tokens on the same line together:

  foreach my $hit ($kasago->search_more_merged($search)) {
    print $hit->source . "/"
      . $hit->file . "@"
      . $hit->row . ": "
      . $hit->line . "\n";
    foreach my $token (@{ $hit->tokens }) {
      print "  @" . $token->col . ": " . $token->value . "\n";
    }
  }

sources

This returns a list of the sources currently indexed:

  my @sources = $kasago->sources;
  

tokens

Given a source and a file, returns a list of the tokens indexed:

  my @tokens  = $kasago->tokens($source, $file);

AUTHOR

Leon Brocard <acme@astray.com>.

COPYRIGHT

Copyright (C) 2005, Leon Brocard

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.

cpanm Kasago

perl -MCPAN -e shell
install Kasago