RG::Bl...:Parser(3pm)

💖 RG::Blast::Parser — bestie edition 💖

okay so. you know how NCBI BLAST -m 0 output is a LOT? yeah. this is the Perl binding for a very fast C/C++ library that eats that output and hands you back a nice lil hash. it's RG::Blast::Parser, it's in the user-contributed Perl docs (the 3pm crew), and it's lowkey iconic.

---

✨ NAME ✨

RG::Blast::Parser — fast NCBI BLAST parser 🧬⚡

---

✨ SYNOPSIS ✨

use Data::Dumper;
use RG::Blast::Parser;

my $parser = RG::Blast::Parser->new(); # read from STDIN

open( EXAMPLE, '<', '/usr/share/doc/librg-blast-parser-perl/examples/converged.ali' ) || confess($!);
my $parser = RG::Blast::Parser->new( \*EXAMPLE, "converged.ali" ); # read from EXAMPLE, use name "converged.ali" in error messages

while( my $res = $parser->parse() )
{
  print Dumper( $res );
}

eval {
  my $res = $parser->parse();
  # ...
};
if( $@ && $@ =~ /^parser error/ ) { warn("failed to parse blast result - exception caught"); }

like. look at her go. 🤩

---

✨ DESCRIPTION ✨

This package is the perl binding for a super fast C/C++ library that parses NCBI BLAST -m 0 (that's the default output format, bestie) results. And the results come back to you in a convenient hash structure, because we're not doing string scraping in this house 💅

You can absolutely concatenate multiple results and feed them in together — no problem. One result gets parsed and returned at a time. One at a time, gorgeous. 🌸

---

✨ CONSTRUCTOR ✨

new( [FILEHANDLE, [NAME]] )

Creates an RG::Blast::Parser 🎀 Blast results are read from FILEHANDLE, and it defaults to STDIN if you don't pass one. And get this — you can name your input stream NAME so that name shows up in error messages (default: "STDIN"). personalized error messages?? it's giving thoughtful ✨

---

✨ METHODS ✨

parse( [TRACE_PARSING, [TRACE_SCANNING]] )

Parses one complete BLAST result and returns it. If there's nothing left on the input stream, it returns undef (a graceful exit, we love to see it 🦋).

🚨 but if there's a parser error it die()s — and ngl the error message is "(at present not very useful)" so like. bring a snack. 😭

The following structure is returned in a hash reference:

{
  blast_version =>    STRING,
  references =>       [ STRING, ... ],
  rounds => [
      {
          oneline_idx =>      NUM,    # index of first one-line description of
                                      # this round in "onelines" array
          oneline_cnt =>      NUM,    # number of one-line descriptions of
                                      # this round
          hit_idx =>          NUM,    # index of first hit of this round in
                                      # "hits" array
          hit_cnt =>          NUM,    # number of hits of this round
          oneline_new_idx =>  NUM|undef# index of first new (not-seen-before)
                                      # one-line description of this round
                                      # in "onelines" array
          oneline_new_cnt =>  NUM     # number of new one-line descriptions of
                                      # this round
      }, ...
  ],
  q_name =>       STRING,
  q_desc =>       STRING|undef,
  q_length =>     NUM,
  db_name =>      STRING,
  db_nseq =>      NUM,
  db_nletter =>   NUM,
  onelines =>     [                   # one-line descriptions from all rounds
      {
          name =>         STRING,
          desc =>         STRING|undef,
          bit_score =>    NUM,
          e_value =>      NUM
      }, ...
  ],
  converged =>    BOOLEAN,
  hits =>         [                   # hits from all rounds
      {
          name =>         STRING,
          desc =>         STRING|undef,
          length =>       NUM,
          hsps =>         [
              {
                  bit_score =>    NUM,
                  raw_score =>    NUM,
                  e_value =>      NUM,
                  method =>       STRING,
                  identities =>   NUM,
                  positives =>    NUM,
                  gaps =>         NUM,
                  q_strand =>     STRING|undef,
                  s_strand =>     STRING|undef,
                  q_frame =>      NUM|undef,
                  s_frame =>      NUM|undef,
                  q_start =>      NUM,
                  q_ali =>        STRING,
                  q_end =>        NUM,
                  match_line =>   STRING,
                  s_start =>      NUM,
                  s_ali =>        STRING,
                  s_end =>        NUM
              }, ...
          ]
      }, ...
  ],
  tail =>         STRING              # bulk text after the last hit / one-line
                                      # description
}

If you want tracing for parsing and scanning, you can enable them using the parameters of this call. 👀 set those flags and watch the magic happen.

result()

Returns the last BLAST result parsed — or undef if there's no last result. no last result = no vibes. 🙈

get_trace_scanning()

Returns scan trace state as a Boolean value. true/false moment ✨

set_trace_scanning( BOOLEAN )

Set scan trace — it's a debugging aid. turn it on when things are weird, bestie 🔍

---

✨ SEE ALSO ✨

Zerg(3pm), Zerg::Report(3pm) — the whole friend group 🫶

---

✨ AUTHOR ✨

Laszlo Kajan, <lkajan@rostlab.org> — thank you for your service 👑

---

✨ COPYRIGHT AND LICENSE ✨

Copyright (C) 2012 by Laszlo Kajan

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

---

okay periodt, that's the whole page 💖 this one was documented with perl v5.42.3 on 2026-08-19, and I'm signing off bestie — go parse something gorgeous 🌈🌸💜