---
name: "RG::Blast::Parser"
section: "3pm"
platform: "linux"
package: "librg-blast-parser-perl"
version: "0.03-9+b4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/RG::Blast::Parser"
---

# RG::Blast::Parser(3pm)

fast NCBI BLAST parser

## 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"); }
```

## DESCRIPTION

This package contains perl binding for a very fast C/C++ library for NCBI BLAST -m 0 (default) output parsing.  BLAST results are returned in a convenient hash structure.

Multiple results may be concatenated for input.  One result is parsed and returned at a time.

## CONSTRUCTOR

- new( \[FILEHANDLE, \[NAME\]\] )

  Creates an "RG::Blast::Parser".  Blast results are read from FILEHANDLE, STDIN by default.  The input stream may be named NAME in error messages (default: "STDIN").

## METHODS

- parse( \[TRACE\_PARSING, \[TRACE\_SCANNING\]\] )

  Parse one complete BLAST result and return it.  If no results on input stream, returns "undef".  In case of parser error it **die()**s with an (at present not very useful) error message.

  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.

- **result()**

  Returns the last BLAST result parsed or "undef" if no last result.

- **get\_trace\_scanning()**

  Returns scan trace state as a Boolean value.

- set\_trace\_scanning( BOOLEAN )

  Set scan trace - debugging aid.

## SEE ALSO

[**Zerg**(3pm)](/Zerg/3pm.md), [**Zerg::Report**(3pm)](/Zerg::Report/3pm.md)

## AUTHOR

Laszlo Kajan, \<lkajan@rostlab.org\>

## 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.