bio 1.0.0 → 1.1.0

data/lib/bio/db/nexus.rb

@@ -0,0 +1,1854 @@
+#
+# = bio/db/nexus.rb - Nexus Standard phylogenetic tree parser / formatter
+#
+# Copyright::  Copyright (C) 2006        Christian M Zmasek <cmzmasek@yahoo.com>
+#
+# License::    The Ruby License
+#
+# $Id: nexus.rb,v 1.3 2007/04/05 23:35:40 trevor Exp $
+#
+# == Description
+#
+# This file contains classes that implement a parser for NEXUS formatted
+# data as well as objects to store, access, and write the parsed data.
+#
+# The following five blocks:
+# taxa, characters, distances, trees, data
+# are recognizable and parsable.
+#
+# The parser can deal with (nested) comments (indicated by square brackets),
+# unless the comments are inside a command or data item (e.g. 
+# "Dim[comment]ensions" or inside a matrix).
+#
+# Single or double quoted TaxLabels are processed as follows (by way
+# of example): "mus musculus" -> mus_musculus
+#
+#
+# == USAGE
+#
+#   require 'bio/db/nexus'
+#
+#   # Create a new parser:
+#   nexus = Bio::Nexus.new( nexus_data_as_string )
+#
+#   # Get first taxa block:   
+#   taxa_block = nexus.get_taxa_blocks[ 0 ]
+#   # Get number of taxa:
+#   number_of_taxa = taxa_block.get_number_of_taxa.to_i
+#   # Get name of first taxon:
+#   first_taxon = taxa_block.get_taxa[ 0 ]
+#
+#   # Get first data block:   
+#   data_block = nexus.get_data_blocks[ 0 ]
+#   # Get first characters name:
+#   seq_name = data_block.get_row_name( 0 )
+#   # Get first characters row named "taxon_2" as Bio::Sequence sequence:
+#   seq_tax_2 = data_block.get_sequences_by_name( "taxon_2" )[ 0 ]
+#   # Get third characters row as Bio::Sequence sequence:
+#   seq_2 = data_block.get_sequence( 2 )
+#   # Get first characters row named "taxon_3" as String:   
+#   string_tax_3 = data_block.get_characters_strings_by_name( "taxon_3" )
+#   # Get name of first taxon:
+#   taxon_0 = data_block.get_taxa[ 0 ]
+#   # Get characters matrix as Bio::Nexus::NexusMatrix (names are in column 0)
+#   characters_matrix = data_block.get_matrix
+#
+#   # Get first characters block (same methods as Nexus::DataBlock except
+#   # it lacks get_taxa method):   
+#   characters_block = nexus.get_characters_blocks[ 0 ]
+#   
+#   # Get trees block(s):   
+#   trees_block = nexus.get_trees_blocks[ 0 ]
+#   # Get first tree named "best" as String:
+#   string_fish = trees_block.get_tree_strings_by_name( "best" )[ 0 ]
+#   # Get first tree named "best" as Bio::Db::Newick object:
+#   tree_fish = trees_block.get_trees_by_name( "best" )[ 0 ]
+#   # Get first tree as Bio::Db::Newick object:
+#   tree_first = trees_block.get_tree( 0 )
+#
+#   # Get distances block(s):   
+#   distances_blocks = nexus.get_distances_blocks
+#   # Get matrix as Bio::Nexus::NexusMatrix object:
+#   matrix = distances_blocks[ 0 ].get_matrix
+#   # Get value (column 0 are names):
+#   val = matrix.get_value( 1, 5 )
+#
+#   # Get blocks for which no class exists (private blocks):
+#   private_blocks = nexus.get_blocks_by_name( "my_block" )
+#   # Get first block names "my_block":
+#   my_block_0 = private_blocks[ 0 ]
+#   # Get first token in first block names "my_block":
+#   first_token = my_block_0.get_tokens[ 0 ]
+#
+#
+# == References
+#
+# * Maddison DR, Swofford DL, Maddison WP (1997). NEXUS: an extensible file
+#   format for systematic information. 
+#   Syst Biol. 1997 46(4):590-621. 
+#
+
+require 'bio/sequence'
+require 'bio/tree'
+require 'bio/db/newick'
+
+module Bio
+  
+  # == DESCRIPTION
+  # Bio::Nexus is a parser for nexus formatted data.
+  # It contains classes and constants enabling the representation and
+  # processing of nexus data.
+  #
+  # == USAGE
+  #
+  #   # Parsing a nexus formatted string str:
+  #   nexus = Bio::Nexus.new( nexus_str )
+  #   
+  #   # Obtaining of the nexus blocks as array of GenericBlock or
+  #   # any of its subclasses (such as DistancesBlock):
+  #   blocks = nexus.get_blocks
+  #
+  #   # Getting a block by name:
+  #   my_blocks = nexus.get_blocks_by_name( "my_block" )
+  #
+  #   # Getting distance blocks:
+  #   distances_blocks = nexus.get_distances_blocks
+  #
+  #   # Getting trees blocks:
+  #   trees_blocks = nexus.get_trees_blocks
+  #
+  #   # Getting data blocks:
+  #   data_blocks = nexus.get_data_blocks
+  #
+  #   # Getting characters blocks: 
+  #   character_blocks = nexus.get_characters_blocks
+  #
+  #   # Getting taxa blocks: 
+  #   taxa_blocks = nexus.get_taxa_blocks
+  #
+  class Nexus
+    
+   
+    END_OF_LINE      = "\n"
+    INDENTENTION     = " "
+    DOUBLE_QUOTE     = "\""
+    SINGLE_QUOTE     = "'"
+    
+    
+    BEGIN_NEXUS      = "#NEXUS"
+    DELIMITER        = ";"
+    BEGIN_BLOCK      = "Begin"
+    END_BLOCK        = "End" + DELIMITER
+    BEGIN_COMMENT    = "["
+    END_COMMENT      = "]"
+    
+    
+    TAXA             = "Taxa"
+    CHARACTERS       = "Characters"
+    DATA             = "Data"
+    DISTANCES        = "Distances"
+    TREES            = "Trees"
+    TAXA_BLOCK       = TAXA + DELIMITER
+    CHARACTERS_BLOCK = CHARACTERS + DELIMITER
+    DATA_BLOCK       = DATA + DELIMITER
+    DISTANCES_BLOCK  = DISTANCES + DELIMITER
+    TREES_BLOCK      = TREES + DELIMITER
+    
+    
+    DIMENSIONS       = "Dimensions"
+    FORMAT           = "Format"
+    NTAX             = "NTax"
+    NCHAR            = "NChar"
+    DATATYPE         = "DataType"
+    TAXLABELS        = "TaxLabels"
+    MATRIX           = "Matrix"
+    # End of constants.
+    
+ 
+    # Nexus parse error class, 
+    # indicates error during parsing of nexus formatted data.
+    class NexusParseError < RuntimeError; end
+
+    # Creates a new nexus parser for 'nexus_str'.  
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _nexus_str_: String - nexus formatted data
+    def initialize( nexus_str )
+      @blocks             = Array.new
+      @current_cmd        = nil
+      @current_subcmd     = nil
+      @current_block_name = nil
+      @current_block      = nil
+      parse( nexus_str )
+    end
+  
+   
+    # Returns an Array of all blocks found in the String 'nexus_str'
+    # set via Bio::Nexus.new( nexus_str ).
+    #
+    # ---
+    # *Returns*:: Array of GenericBlocks or any of its subclasses  
+    def get_blocks
+      @blocks
+    end
+    
+    # A convenience methods which returns an array of
+    # all nexus blocks for which the name equals 'name' found
+    # in the String 'nexus_str' set via Bio::Nexus.new( nexus_str ).
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _name_: String
+    # *Returns*:: Array of GenericBlocks or any of its subclasses 
+    def get_blocks_by_name( name )
+      found_blocks = Array.new
+      @blocks.each do | block |
+        if ( name == block.get_name )
+          found_blocks.push( block )
+        end
+      end
+      found_blocks
+    end
+    
+    # A convenience methods which returns an array of
+    # all data blocks.
+    #
+    # ---
+    # *Returns*:: Array of DataBlocks 
+    def get_data_blocks
+      get_blocks_by_name( DATA_BLOCK.chomp( ";").downcase )
+    end
+    
+    # A convenience methods which returns an array of
+    # all characters blocks.
+    #
+    # ---
+    # *Returns*:: Array of CharactersBlocks
+    def get_characters_blocks
+      get_blocks_by_name( CHARACTERS_BLOCK.chomp( ";").downcase )
+    end
+    
+    # A convenience methods which returns an array of
+    # all trees blocks.
+    #
+    # ---
+    # *Returns*:: Array of TreesBlocks
+    def get_trees_blocks
+      get_blocks_by_name( TREES_BLOCK.chomp( ";").downcase )
+    end
+    
+    # A convenience methods which returns an array of
+    # all distances blocks.
+    #
+    # ---
+    # *Returns*:: Array of DistancesBlock   
+    def get_distances_blocks
+      get_blocks_by_name( DISTANCES_BLOCK.chomp( ";").downcase )
+    end
+    
+    # A convenience methods which returns an array of
+    # all taxa blocks.
+    #
+    # ---
+    # *Returns*:: Array of TaxaBlocks
+    def get_taxa_blocks
+      get_blocks_by_name( TAXA_BLOCK.chomp( ";").downcase )
+    end
+  
+    # Returns a String listing how many of each blocks it parsed.
+    #
+    # ---
+    # *Returns*:: String 
+    def to_s
+      str = String.new
+      if get_blocks.length < 1
+        str << "empty"
+      else 
+        str << "number of blocks: " << get_blocks.length.to_s
+        if get_characters_blocks.length > 0
+          str << " [characters blocks: " << get_characters_blocks.length.to_s << "] "
+        end  
+        if get_data_blocks.length > 0
+          str << " [data blocks: " << get_data_blocks.length.to_s << "] "
+        end
+        if get_distances_blocks.length > 0
+          str << " [distances blocks: " << get_distances_blocks.length.to_s << "] "
+        end  
+        if get_taxa_blocks.length > 0
+          str << " [taxa blocks: " << get_taxa_blocks.length.to_s << "] "
+        end    
+        if get_trees_blocks.length > 0
+          str << " [trees blocks: " << get_trees_blocks.length.to_s << "] "
+        end        
+      end
+      str
+    end
+    alias to_str to_s
+  
+    private
+    
+    # The master method for parsing.
+    # Stores the resulting block in array @blocks.
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _str_: String - the String to be parsed
+    def parse( str )
+      str = str.chop if str[-1..-1] == ';'
+      ary = str.split(/[\s+=]/)
+      ary.collect! { |x| x.strip!; x.empty? ? nil : x }
+      ary.compact!
+      in_comment = false
+      comment_level = 0
+     
+      # Main loop
+      while token = ary.shift
+        # Quotes:
+        if ( token.index( SINGLE_QUOTE ) == 0 ||
+             token.index( DOUBLE_QUOTE ) == 0 )
+          token << "_" << ary.shift
+          token = token.chop if token[-1..-1] == ';'
+          token = token.slice( 1, token.length - 2 )
+        end
+        # Comments: 
+        open = token.count( BEGIN_COMMENT )
+        close = token.count( END_COMMENT )
+        comment = comment_level > 0
+        comment_level = comment_level + open - close
+        if ( open > 0 && open == close  )
+          next
+        elsif comment_level > 0 || comment
+          next
+        elsif equal?( token, END_BLOCK )
+          end_block()
+        elsif equal?( token, BEGIN_BLOCK )
+          begin_block()
+          @current_block_name = token = ary.shift
+          @current_block_name.downcase!
+          @current_block = create_block()
+          @blocks.push( @current_block )
+        elsif ( @current_block_name != nil )  
+          process_token( token.chomp( DELIMITER ), ary )
+        end
+      end # main loop
+      @blocks.compact!
+    end # parse
+    
+    # Operations required when beginnig of block encountered.
+    # 
+    # --- 
+    def begin_block() 
+      if @current_block_name != nil
+        raise NexusParseError, "Cannot have nested nexus blocks (\"end;\" might be missing)"
+      end
+      reset_command_state()
+    end
+    
+    # Operations required when ending of block encountered.
+    # 
+    # ---
+    def end_block()
+      if @current_block_name == nil
+        raise NexusParseError, "Cannot have two or more \"end;\" tokens in sequence"
+      end
+      @current_block_name = nil
+    end
+    
+    # This calls various process_token_for_<name>_block methods
+    # depeding on state of @current_block_name.
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array
+    def process_token( token, ary )
+      case @current_block_name
+        when TAXA_BLOCK.downcase
+          process_token_for_taxa_block( token )
+        when CHARACTERS_BLOCK.downcase
+          process_token_for_character_block( token, ary )
+        when DATA_BLOCK.downcase
+          process_token_for_data_block( token, ary )
+        when DISTANCES_BLOCK.downcase
+          process_token_for_distances_block( token, ary )
+        when TREES_BLOCK.downcase  
+          process_token_for_trees_block( token, ary )
+        else
+          process_token_for_generic_block( token )  
+      end
+    end
+    
+    # Resets @current_cmd and @current_subcmd to nil.
+    #
+    # ---
+    def reset_command_state()
+      @current_cmd    = nil
+      @current_subcmd = nil
+    end
+    
+    # Creates GenericBlock (or any of its subclasses) the type of
+    # which is determined by the state of @current_block_name.
+    #
+    # ---
+    # *Returns*:: GenericBlock (or any of its subclasses) object
+    def create_block()
+      case @current_block_name
+        when TAXA_BLOCK.downcase
+          return Bio::Nexus::TaxaBlock.new( @current_block_name )
+        when CHARACTERS_BLOCK.downcase
+          return Bio::Nexus::CharactersBlock.new( @current_block_name )
+        when DATA_BLOCK.downcase
+          return Bio::Nexus::DataBlock.new( @current_block_name )
+        when DISTANCES_BLOCK.downcase
+          return Bio::Nexus::DistancesBlock.new( @current_block_name )
+        when TREES_BLOCK.downcase
+          return Bio::Nexus::TreesBlock.new( @current_block_name )
+        else
+          return Bio::Nexus::GenericBlock.new( @current_block_name )
+      end 
+    end 
+  
+    # This processes the tokens (between Begin Taxa; and End;) for a taxa block 
+    # Example of a currently parseable taxa block:
+    # Begin Taxa;
+    #  Dimensions NTax=4;
+    #  TaxLabels fish [comment] 'african frog' "rat snake" 'red mouse';
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    def process_token_for_taxa_block( token )
+      if ( equal?( token, DIMENSIONS ) )
+        @current_cmd    = DIMENSIONS
+        @current_subcmd = nil
+      elsif ( equal?( token, TAXLABELS ) )
+        @current_cmd    = TAXLABELS
+        @current_subcmd = nil
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NTAX ) )
+        @current_subcmd = NTAX
+      elsif ( cmds_equal_to?( DIMENSIONS, NTAX ) )
+        @current_block.set_number_of_taxa( token )
+      elsif ( cmds_equal_to?( TAXLABELS, nil ) )
+        @current_block.add_taxon( token )
+      end
+    end
+    
+    # This processes the tokens (between Begin Taxa; and End;) for a character
+    # block 
+    # Example of a currently parseable character block:
+    # Begin Characters;
+    # Dimensions NChar=20
+    #             NTax=4;
+    # Format DataType=DNA
+    # Missing=x
+    # Gap=- MatchChar=.;
+    # Matrix
+    # fish  ACATA GAGGG TACCT CTAAG
+    # frog  ACTTA GAGGC TACCT CTAGC
+    # snake ACTCA CTGGG TACCT TTGCG
+    # mouse ACTCA GACGG TACCT TTGCG;
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array
+    def process_token_for_character_block( token, ary )
+      if ( equal?( token, DIMENSIONS ) )
+        @current_cmd    = DIMENSIONS
+        @current_subcmd = nil
+      elsif ( equal?( token, FORMAT ) )
+        @current_cmd    = FORMAT
+        @current_subcmd = nil  
+      elsif ( equal?( token, MATRIX ) )
+        @current_cmd    = MATRIX
+        @current_subcmd = nil
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NTAX ) )
+        @current_subcmd = NTAX
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NCHAR ) )
+        @current_subcmd = NCHAR
+      elsif ( @current_cmd == FORMAT && equal?( token, DATATYPE ) )
+        @current_subcmd = DATATYPE
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::MISSING ) )
+        @current_subcmd = CharactersBlock::MISSING 
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::GAP ) )
+        @current_subcmd = CharactersBlock::GAP
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::MATCHCHAR ) )
+        @current_subcmd = CharactersBlock::MATCHCHAR  
+      elsif ( cmds_equal_to?( DIMENSIONS, NTAX ) )
+        @current_block.set_number_of_taxa( token )
+      elsif ( cmds_equal_to?( DIMENSIONS, NCHAR ) )
+        @current_block.set_number_of_characters( token )  
+      elsif ( cmds_equal_to?( FORMAT, DATATYPE ) )
+        @current_block.set_datatype( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::MISSING ) )
+        @current_block.set_missing( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::GAP ) )
+        @current_block.set_gap_character( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::MATCHCHAR ) )
+        @current_block.set_match_character( token )  
+      elsif ( cmds_equal_to?( MATRIX, nil ) )
+        @current_block.set_matrix( make_matrix( token, ary,
+                                   @current_block.get_number_of_characters, true ) )
+      end
+    end
+    
+    # This processes the tokens (between Begin Trees; and End;) for a trees block 
+    # Example of a currently parseable taxa block:
+    # Begin Trees;
+    # Tree best=(fish,(frog,(snake, mouse)));
+    # Tree other=(snake,(frog,( fish, mouse)));
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array 
+    def process_token_for_trees_block( token, ary )
+      if ( equal?( token, TreesBlock::TREE ) )
+        @current_cmd    = TreesBlock::TREE
+        @current_subcmd = nil
+      elsif ( cmds_equal_to?( TreesBlock::TREE, nil ) )
+        @current_block.add_tree_name( token )
+        tree_string = ary.shift
+        while ( tree_string.index( ";" ) == nil )
+          tree_string << ary.shift
+        end
+        @current_block.add_tree( tree_string )
+        @current_cmd    = nil
+      end  
+    end
+    
+    # This processes the tokens (between Begin Taxa; and End;) for a character
+    # block. 
+    # Example of a currently parseable character block:
+    # Begin Distances;
+    #  Dimensions nchar=20 ntax=5;
+    #  Format Triangle=Upper;
+    #  Matrix
+    #  taxon_1 0.0 1.0 2.0 4.0 7.0
+    #  taxon_2 1.0 0.0 3.0 5.0 8.0
+    #  taxon_3 3.0 4.0 0.0 6.0 9.0
+    #  taxon_4 7.0 3.0 1.0 0.0 9.5
+    #  taxon_5 1.2 1.3 1.4 1.5 0.0;
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array 
+    def process_token_for_distances_block( token, ary )
+      if ( equal?( token, DIMENSIONS ) )
+        @current_cmd    = DIMENSIONS
+        @current_subcmd = nil
+      elsif ( equal?( token, FORMAT ) )
+        @current_cmd    = FORMAT
+        @current_subcmd = nil  
+      elsif ( equal?( token, MATRIX ) )
+        @current_cmd    = MATRIX
+        @current_subcmd = nil
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NTAX ) )
+        @current_subcmd = NTAX
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NCHAR ) )
+        @current_subcmd = NCHAR
+      elsif ( @current_cmd == FORMAT && equal?( token, DATATYPE ) )
+        @current_subcmd = DATATYPE
+      elsif ( @current_cmd == FORMAT && equal?( token, DistancesBlock::TRIANGLE ) )
+        @current_subcmd = DistancesBlock::TRIANGLE   
+      elsif ( cmds_equal_to?( DIMENSIONS, NTAX ) )
+        @current_block.set_number_of_taxa( token )
+      elsif ( cmds_equal_to?( DIMENSIONS, NCHAR ) )
+        @current_block.set_number_of_characters( token )  
+      elsif ( cmds_equal_to?( FORMAT, DistancesBlock::TRIANGLE ) )
+        @current_block.set_triangle( token )
+      elsif ( cmds_equal_to?( MATRIX, nil ) )
+        @current_block.set_matrix( make_matrix( token, ary,
+                                   @current_block.get_number_of_taxa, false ) )
+      end
+    end
+    
+    # This processes the tokens (between Begin Taxa; and End;) for a data
+    # block. 
+    # Example of a currently parseable data block:
+    # Begin Data;
+    # Dimensions ntax=5 nchar=14;
+    # Format Datatype=RNA gap=# MISSING=x MatchChar=^;
+    # TaxLabels ciona cow [comment] ape 'purple urchin' "green lizard";
+    # Matrix
+    # taxon_1 A- CCGTCGA-GTTA
+    # taxon_2 T- CCG-CGA-GATA
+    # taxon_3 A- C-GTCGA-GATA
+    # taxon_4 A- CCTCGA--GTTA
+    # taxon_5 T- CGGTCGT-CTTA;
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array
+    def process_token_for_data_block( token, ary )
+      if ( equal?( token, DIMENSIONS ) )
+        @current_cmd    = DIMENSIONS
+        @current_subcmd = nil
+      elsif ( equal?( token, FORMAT ) )
+        @current_cmd    = FORMAT
+        @current_subcmd = nil
+      elsif ( equal?( token, TAXLABELS ) )
+        @current_cmd    = TAXLABELS
+        @current_subcmd = nil  
+      elsif ( equal?( token, MATRIX ) )
+        @current_cmd    = MATRIX
+        @current_subcmd = nil
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NTAX ) )
+        @current_subcmd = NTAX
+      elsif ( @current_cmd == DIMENSIONS && equal?( token, NCHAR ) )
+        @current_subcmd = NCHAR
+      elsif ( @current_cmd == FORMAT && equal?( token, DATATYPE ) )
+        @current_subcmd = DATATYPE
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::MISSING ) )
+        @current_subcmd = CharactersBlock::MISSING 
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::GAP ) )
+        @current_subcmd = CharactersBlock::GAP
+      elsif ( @current_cmd == FORMAT && equal?( token, CharactersBlock::MATCHCHAR ) )
+        @current_subcmd = CharactersBlock::MATCHCHAR  
+      elsif ( cmds_equal_to?( DIMENSIONS, NTAX ) )
+        @current_block.set_number_of_taxa( token )
+      elsif ( cmds_equal_to?( DIMENSIONS, NCHAR ) )
+        @current_block.set_number_of_characters( token )  
+      elsif ( cmds_equal_to?( FORMAT, DATATYPE ) )
+        @current_block.set_datatype( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::MISSING ) )
+        @current_block.set_missing( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::GAP ) )
+        @current_block.set_gap_character( token )
+      elsif ( cmds_equal_to?( FORMAT, CharactersBlock::MATCHCHAR ) )
+        @current_block.set_match_character( token )
+      elsif ( cmds_equal_to?( TAXLABELS, nil ) )
+        @current_block.add_taxon( token ) 
+      elsif ( cmds_equal_to?( MATRIX, nil ) )
+        @current_block.set_matrix( make_matrix( token, ary,
+                                   @current_block.get_number_of_characters, true ) )
+      end
+    end
+    
+    # Makes a NexusMatrix out of token from token Array ary
+    # Used by process_token_for_X_block methods which contain
+    # data in a matrix form. Column 0 contains names.
+    # This will shift tokens from ary.
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _ary_: Array
+    # * (required) _size_: Integer
+    # * (optional) _scan_token_: true or false 
+    # *Returns*:: NexusMatrix
+    def make_matrix( token, ary, size, scan_token = false )
+      matrix = NexusMatrix.new
+      col = -1
+      row = 0
+      done = false
+      while ( !done )
+        if ( col == -1 )
+          # name
+          col = 0
+          matrix.set_value( row, col, token ) # name is in col 0  
+        else
+          # values
+          col = add_token_to_matrix( token, scan_token, matrix, row, col )
+          if ( col == size.to_i  )
+            col = -1
+            row += 1
+          end
+        end
+        token = ary.shift
+        if ( token.index( DELIMITER ) != nil )
+          col = add_token_to_matrix( token.chomp( ";" ), scan_token, matrix, row, col )
+          done = true
+        end
+      end # while
+      matrix
+    end
+    
+    # Helper method for make_matrix.
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    # * (required) _scan_token_: true or false - add whole token
+    #                                            or
+    #                                            scan into chars
+    # * (required) _matrix_: NexusMatrix  - the matrix to which to add token
+    # * (required) _row_: Integer - the row for matrix
+    # * (required) _col_: Integer - the starting row
+    # *Returns*:: Integer - ending row
+    def add_token_to_matrix( token, scan_token, matrix, row, col )
+      if ( scan_token )
+        token.scan(/./) { |w|
+        col += 1
+        matrix.set_value( row, col, w )
+      }
+      else
+        col += 1
+        matrix.set_value( row, col, token )
+      end
+      col
+    end
+    
+    # This processes the tokens (between Begin Taxa; and End;) for a block
+    # for which a specific parser is not available.
+    # Example of a currently parseable generic block:
+    # Begin Taxa;
+    #  token1 token2 token3 ...
+    # End;
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _token_: String
+    def process_token_for_generic_block( token )
+        @current_block.add_token( token )
+    end
+    
+    # Returns true if Strings str1 and str2 are
+    # equal - ignoring case.
+    #
+    # ---
+    # *Arguments*:
+    # * (required) _str1_: String
+    # * (required) _str2_: String
+    # *Returns*:: true or false 
+    def equal?( str1, str2 )
+      if ( str1 == nil || str2 == nil )
+        return false
+      else
+        return ( str1.downcase == str2.downcase )
+      end
+    end
+    
+    # Returns true if @current_cmd == command
+    # and @current_subcmd == subcommand, false otherwise
+    # ---
+    # *Arguments*:
+    # * (required) _command_: String
+    # * (required) _subcommand_: String
+    # *Returns*:: true or false
+    def cmds_equal_to?( command, subcommand )
+      return ( @current_cmd == command && @current_subcmd == subcommand )
+    end
+    
+    # Classes to represent nexus data follow.
+    
+    # ==  DESCRIPTION
+    # Bio::Nexus::GenericBlock represents a generic nexus block.
+    # It is mainly intended to be extended into more specific classes,
+    # although it is used for blocks not represented by more specific
+    # block classes.
+    # It has a name and a array for the tokenized content of a
+    # nexus block.   
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #   # Get blocks for which no class exists (private blocks)
+    #   as Nexus::GenericBlock:
+    #   private_blocks = nexus.get_blocks_by_name( "my_block" )
+    #   # Get first block names "my_block":
+    #   my_block_0 = private_blocks[ 0 ]
+    #   # Get first token in first block names "my_block":
+    #   first_token = my_block_0.get_tokens[ 0 ]
+    #   # Get name of block (would return "my_block" in this case):
+    #   name = my_block_0.get_name
+    #   # Return data of block as nexus formatted String:
+    #   name = my_block_0.to_nexus
+    #
+    class GenericBlock
+      
+      # Creates a new GenericBlock object named 'name'.  
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      def initialize( name )
+        @name = name.chomp(";") 
+        @tokens = Array.new
+      end
+      
+      # Gets the name of this block.
+      #
+      # ---
+      # *Returns*:: String 
+      def get_name
+        @name
+      end
+      
+      # Returns contents as Array of Strings.
+      #
+      # ---
+      # *Returns*:: Array
+      def get_tokens
+        @tokens
+      end
+      
+      # Same as to_nexus.
+      #
+      # ---
+      # *Returns*:: String 
+      def to_s
+        to_nexus
+      end
+      alias to_str to_s
+      
+      # Should return a String describing this block as nexus formatted data.
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        str = "generic block \"" + get_name + "\" [do not know how to write in nexus format]"
+      end
+      
+      # Adds a token to this.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _token_: String
+      def add_token( token )
+        @tokens.push( token )
+      end
+      
+    end # class GenericBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::TaxaBlock represents a taxa nexus block.
+    #
+    # = Example of Taxa block:
+    # Begin Taxa;
+    #  Dimensions NTax=4;
+    #  TaxLabels fish [comment] 'african frog' "rat snake" 'red mouse';
+    # End;
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #   # Get first taxa block:   
+    #   taxa_block = nexus.get_taxa_blocks[ 0 ]
+    #   # Get number of taxa:
+    #   number_of_taxa = taxa_block.get_number_of_taxa.to_i
+    #   # Get name of first taxon:
+    #   first_taxon = taxa_block.get_taxa[ 0 ]
+    #
+    class TaxaBlock < GenericBlock
+      
+      # Creates a new TaxaBlock object named 'name'.  
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      def initialize( name )
+        super( name )
+        @number_of_taxa = 0
+        @taxa = Array.new
+      end
+      
+      # Returns a String describing this block as nexus formatted data.
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        line_1 = String.new
+        line_1 << DIMENSIONS 
+        if ( Nexus::Util::larger_than_zero( get_number_of_taxa  ) )
+          line_1 << " " <<  NTAX << "=" << get_number_of_taxa
+        end
+        line_1 << DELIMITER
+        line_2 = String.new
+        line_2 << TAXLABELS << " " << Nexus::Util::array_to_string( get_taxa ) << DELIMITER
+        Nexus::Util::to_nexus_helper( TAXA_BLOCK, [ line_1, line_2 ] )
+      end
+      
+      # Gets the "number of taxa" property.
+      #
+      # ---
+      # *Returns*:: Integer 
+      def get_number_of_taxa
+        @number_of_taxa
+      end
+      
+      # Gets the taxa of this block.
+      #
+      # ---
+      # *Returns*:: Array
+      def get_taxa
+        @taxa
+      end
+      
+      # Sets the "number of taxa" property.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _number_of_taxa_: Integer
+      def set_number_of_taxa( number_of_taxa )
+        @number_of_taxa = number_of_taxa
+      end
+      
+      # Adds a taxon name to this block.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _taxon_: String
+      def add_taxon( taxon )
+        @taxa.push( taxon )
+      end
+      
+    end # class TaxaBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::CharactersBlock represents a characters nexus block.
+    #
+    # = Example of Characters block:
+    # Begin Characters;
+    #  Dimensions NChar=20
+    #             NTax=4;
+    #  Format DataType=DNA
+    #  Missing=x
+    #  Gap=- MatchChar=.;
+    #  Matrix
+    #   fish  ACATA GAGGG TACCT CTAAG
+    #   frog  ACTTA GAGGC TACCT CTAGC
+    #   snake ACTCA CTGGG TACCT TTGCG
+    #   mouse ACTCA GACGG TACCT TTGCG;
+    # End;
+    #
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #
+    #   # Get first characters block (same methods as Nexus::DataBlock except
+    #   # it lacks get_taxa method):   
+    #   characters_block = nexus.get_characters_blocks[ 0 ]
+    #  
+    class CharactersBlock < GenericBlock
+      
+      MISSING    = "Missing"
+      GAP        = "Gap"
+      MATCHCHAR  = "MatchChar"
+      
+      # Creates a new CharactersBlock object named 'name'.  
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      def initialize( name )
+        super( name )
+        @number_of_taxa = 0
+        @number_of_characters = 0
+        @data_type = String.new
+        @gap_character = String.new
+        @missing = String.new
+        @match_character = String.new
+        @matrix = NexusMatrix.new
+      end
+      
+      # Returns a String describing this block as nexus formatted data.
+      #
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        line_1 = String.new
+        line_1 << DIMENSIONS  
+        if ( Nexus::Util::larger_than_zero( get_number_of_taxa ) )
+          line_1 << " " <<  NTAX << "=" << get_number_of_taxa
+        end
+        if ( Nexus::Util::larger_than_zero( get_number_of_characters ) )
+          line_1 << " " <<  NCHAR << "=" << get_number_of_characters
+        end
+        line_1 << DELIMITER
+        
+        line_2 = String.new
+        line_2 << FORMAT  
+        if ( Nexus::Util::longer_than_zero( get_datatype ) )
+          line_2 << " " <<  DATATYPE << "=" << get_datatype
+        end
+        if ( Nexus::Util::longer_than_zero( get_missing ) )
+          line_2 << " " <<  MISSING << "=" << get_missing
+        end
+        if ( Nexus::Util::longer_than_zero( get_gap_character ) )
+          line_2 << " " <<  GAP << "=" << get_gap_character
+        end
+        if ( Nexus::Util::longer_than_zero( get_match_character ) )
+          line_2 << " " <<  MATCHCHAR << "=" << get_match_character
+        end
+        line_2 << DELIMITER
+        
+        line_3 = String.new
+        line_3 << MATRIX 
+        Nexus::Util::to_nexus_helper( CHARACTERS_BLOCK, [ line_1, line_2, line_3 ] +
+                                      get_matrix.to_nexus_row_array  )
+      end
+      
+      # Gets the "number of taxa" property.
+      #
+      # ---
+      # *Returns*:: Integer
+      def get_number_of_taxa
+        @number_of_taxa
+      end
+      
+      # Gets the "number of characters" property.
+      #
+      # ---
+      # *Returns*:: Integer
+      def get_number_of_characters
+        @number_of_characters
+      end
+      
+      # Gets the "datatype" property.
+      # ---
+      # *Returns*:: String
+      def get_datatype
+        @data_type
+      end
+      
+      # Gets the "gap character" property.
+      # ---
+      # *Returns*:: String
+      def get_gap_character
+        @gap_character
+      end
+      
+      # Gets the "missing" property.
+      # ---
+      # *Returns*:: String
+      def get_missing
+        @missing
+      end
+      
+      # Gets the "match character" property.
+      # ---
+      # *Returns*:: String
+      def get_match_character 
+        @match_character 
+      end
+      
+      # Gets the matrix.
+      # ---
+      # *Returns*:: Bio::Nexus::NexusMatrix
+      def get_matrix
+        @matrix 
+      end
+      
+      # Returns character data as Bio::Sequence object Array
+      # for matrix rows named 'name'.
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      # *Returns*:: Bio::Sequence
+      def get_sequences_by_name( name )
+        seq_strs = get_characters_strings_by_name( name )
+        seqs = Array.new
+        seq_strs.each do | seq_str |
+          seqs.push( create_sequence( seq_str, name ) )
+        end
+        seqs
+      end
+      
+      # Returns the characters in the matrix at row 'row' as
+      # Bio::Sequence object. Column 0 of the matrix is set as
+      # the definition of the Bio::Sequence object.
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # *Returns*:: Bio::Sequence
+      def get_sequence( row )
+        create_sequence( get_characters_string( row ), get_row_name( row )  )
+      end
+      
+      # Returns the String in the matrix at row 'row' and column 0,
+      # which usually is interpreted as a sequence name (if the matrix
+      # contains molecular sequence characters).
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # *Returns*:: String
+      def get_row_name( row )
+        get_matrix.get_name( row )
+      end
+      
+      # Returns character data as String Array
+      # for matrix rows named 'name'.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      # *Returns*:: Array of Strings
+      def get_characters_strings_by_name( name )
+        get_matrix.get_row_strings_by_name( name, "" )
+      end
+      
+      # Returns character data as String
+      # for matrix row 'row'.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # *Returns*:: String
+      def get_characters_string( row )
+        get_matrix.get_row_string( row, "" )
+      end
+      
+      # Sets the "number of taxa" property.
+      # ---
+      # *Arguments*:
+      # * (required) _number_of_taxa_: Integer
+      def set_number_of_taxa( number_of_taxa )
+        @number_of_taxa = number_of_taxa
+      end
+      
+      # Sets the "number of characters" property.
+      # ---
+      # *Arguments*:
+      # * (required) _number_of_characters_: Integer
+      def set_number_of_characters( number_of_characters )
+        @number_of_characters = number_of_characters
+      end
+      
+      # Sets the "data type" property.
+      # ---
+      # *Arguments*:
+      # * (required) _data_type_: String
+      def set_datatype( data_type )
+        @data_type = data_type
+      end
+      
+      # Sets the "gap character" property.
+      # ---
+      # *Arguments*:
+      # * (required) _gap_character_: String
+      def set_gap_character( gap_character )
+        @gap_character = gap_character
+      end
+      
+      # Sets the "missing" property.
+      # ---
+      # *Arguments*:
+      # * (required) _missing_: String
+      def set_missing( missing )
+        @missing = missing
+      end
+      
+      # Sets the "match character" property.
+      # ---
+      # *Arguments*:
+      # * (required) _match_character_: String
+      def set_match_character( match_character )
+        @match_character = match_character
+      end
+      
+      # Sets the matrix.
+      # ---
+      # *Arguments*:
+      # * (required) _matrix_: Bio::Nexus::NexusMatrix
+      def set_matrix( matrix )
+        @matrix = matrix
+      end
+      
+      private
+      
+      # Creates a Bio::Sequence object with sequence 'seq_str'
+      # and definition 'definition'.
+      # ---
+      # *Arguments*:
+      # * (required) _seq_str_: String
+      # * (optional) _defintion_: String
+      # *Returns*:: Bio::Sequence
+      def create_sequence( seq_str, definition = "" )
+        seq = Bio::Sequence.auto( seq_str )
+        seq.definition = definition
+        seq
+      end  
+      
+    end # class CharactersBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::DataBlock represents a data nexus block.
+    # A data block is a Bio::Nexus::CharactersBlock with the added
+    # capability to store taxa names.
+    #
+    # = Example of Data block:
+    # Begin Data;
+    #  Dimensions ntax=5 nchar=14;
+    #  Format Datatype=RNA gap=# MISSING=x MatchChar=^;
+    #  TaxLabels ciona cow [comment] ape 'purple urchin' "green lizard";
+    #  Matrix
+    #   taxon_1 A- CCGTCGA-GTTA
+    #   taxon_2 T- CCG-CGA-GATA
+    #   taxon_3 A- C-GTCGA-GATA
+    #   taxon_4 A- CCTCGA--GTTA
+    #   taxon_5 T- CGGTCGT-CTTA;
+    # End;
+    #
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #
+    #   # Get first data block:   
+    #   data_block = nexus.get_data_blocks[ 0 ]
+    #   # Get first characters name:
+    #   seq_name = data_block.get_row_name( 0 )
+    #   # Get first characters row named "taxon_2" as Bio::Sequence sequence:
+    #   seq_tax_2 = data_block.get_sequences_by_name( "taxon_2" )[ 0 ]
+    #   # Get third characters row as Bio::Sequence sequence:
+    #   seq_2 = data_block.get_sequence( 2 )
+    #   # Get first characters row named "taxon_3" as String:   
+    #   string_tax_3 = data_block.get_characters_strings_by_name( "taxon_3" )
+    #   # Get name of first taxon:
+    #   taxon_0 = data_block.get_taxa[ 0 ]
+    #   # Get characters matrix as Bio::Nexus::NexusMatrix (names are in column 0)
+    #   characters_matrix = data_block.get_matrix
+    #
+    class DataBlock < CharactersBlock
+      
+      # Creates a new DataBlock object named 'name'.  
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      def initialize( name )
+        super( name )
+        @taxa = Array.new
+      end
+      
+      # Returns a String describing this block as nexus formatted data.
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        line_1 = String.new
+        line_1 << DIMENSIONS  
+        if ( Nexus::Util::larger_than_zero( get_number_of_taxa ) )
+          line_1 << " " <<  NTAX << "=" << get_number_of_taxa
+        end
+        if ( Nexus::Util::larger_than_zero( get_number_of_characters ) )
+          line_1 << " " <<  NCHAR << "=" << get_number_of_characters
+        end
+        line_1 << DELIMITER
+        
+        line_2 = String.new
+        line_2 << FORMAT  
+        if ( Nexus::Util::longer_than_zero( get_datatype ) )
+          line_2 << " " <<  DATATYPE << "=" << get_datatype
+        end
+        if ( Nexus::Util::longer_than_zero( get_missing ) )
+          line_2 << " " <<  MISSING << "=" << get_missing
+        end
+        if ( Nexus::Util::longer_than_zero( get_gap_character ) )
+          line_2 << " " <<  GAP << "=" << get_gap_character
+        end
+        if ( Nexus::Util::longer_than_zero( get_match_character ) )
+          line_2 << " " <<  MATCHCHAR << "=" << get_match_character
+        end
+        line_2 << DELIMITER
+        
+        line_3 = String.new
+        line_3 << TAXLABELS << " " << Nexus::Util::array_to_string( get_taxa )
+        line_3 << DELIMITER
+        
+        line_4 = String.new
+        line_4 << MATRIX 
+        Nexus::Util::to_nexus_helper( DATA_BLOCK, [ line_1, line_2, line_3, line_4 ] +
+                                      get_matrix.to_nexus_row_array  )
+      end
+      
+      # Gets the taxa of this block. 
+      # ---
+      # *Returns*:: Array
+      def get_taxa
+        @taxa
+      end
+      
+      # Adds a taxon name to this block. 
+      # ---
+      # *Arguments*:
+      # * (required) _taxon_: String
+      def add_taxon( taxon )
+        @taxa.push( taxon )
+      end
+       
+    end # class DataBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::DistancesBlock represents a distances nexus block.
+    #
+    # = Example of Distances block:
+    # Begin Distances;
+    #  Dimensions nchar=20 ntax=5;
+    #  Format Triangle=Upper;
+    #  Matrix
+    #   taxon_1 0.0 1.0 2.0 4.0 7.0
+    #   taxon_2 1.0 0.0 3.0 5.0 8.0
+    #   taxon_3 3.0 4.0 0.0 6.0 9.0
+    #   taxon_4 7.0 3.0 1.0 0.0 9.5
+    #   taxon_5 1.2 1.3 1.4 1.5 0.0;
+    # End;
+    #
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #   # Get distances block(s):   
+    #   distances_blocks = nexus.get_distances_blocks
+    #   # Get matrix as Bio::Nexus::NexusMatrix object:
+    #   matrix = distances_blocks[ 0 ].get_matrix
+    #   # Get value (column 0 are names):
+    #   val = matrix.get_value( 1, 5 )
+    #
+    class DistancesBlock < GenericBlock
+      TRIANGLE = "Triangle"
+      
+      # Creates a new DistancesBlock object named 'name'.  
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      def initialize( name )
+        super( name )        
+        @number_of_taxa = 0
+        @number_of_characters = 0
+        @triangle = String.new
+        @matrix = NexusMatrix.new
+      end
+      
+      # Returns a String describing this block as nexus formatted data.
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        line_1 = String.new
+        line_1 << DIMENSIONS  
+        if ( Nexus::Util::larger_than_zero( get_number_of_taxa ) )
+          line_1 << " " <<  NTAX << "=" << get_number_of_taxa
+        end
+        if ( Nexus::Util::larger_than_zero( get_number_of_characters ) )
+          line_1 << " " <<  NCHAR << "=" << get_number_of_characters
+        end
+        line_1 << DELIMITER
+        
+        line_2 = String.new
+        line_2 << FORMAT  
+        if ( Nexus::Util::longer_than_zero( get_triangle ) )
+          line_2 << " " << TRIANGLE << "=" << get_triangle
+        end
+        line_2 << DELIMITER
+        
+        line_3 = String.new
+        line_3 << MATRIX 
+        Nexus::Util::to_nexus_helper( DISTANCES_BLOCK, [ line_1, line_2, line_3 ] +
+                                      get_matrix.to_nexus_row_array( " " ) )
+      end
+      
+      # Gets the "number of taxa" property.
+      # ---
+      # *Returns*:: Integer
+      def get_number_of_taxa
+        @number_of_taxa
+      end
+      
+      # Gets the "number of characters" property.
+      # ---
+      # *Returns*:: Integer
+      def get_number_of_characters
+        @number_of_characters
+      end
+      
+      # Gets the "triangle" property.
+      # ---
+      # *Returns*:: String
+      def get_triangle
+        @triangle
+      end
+      
+      # Gets the matrix.
+      # ---
+      # *Returns*:: Bio::Nexus::NexusMatrix
+      def get_matrix
+        @matrix
+      end
+      
+      # Sets the "number of taxa" property.
+      # ---
+      # *Arguments*:
+      # * (required) _number_of_taxa_: Integer
+      def set_number_of_taxa( number_of_taxa )
+        @number_of_taxa = number_of_taxa
+      end
+      
+      # Sets the "number of characters" property.
+      # ---
+      # *Arguments*:
+      # * (required) _number_of_characters_: Integer
+      def set_number_of_characters( number_of_characters )
+        @number_of_characters = number_of_characters
+      end
+      
+      # Sets the "triangle" property.
+      # ---
+      # *Arguments*:
+      # * (required) _triangle_: String
+      def set_triangle( triangle )
+        @triangle = triangle
+      end
+      
+      # Sets the matrix.
+      # ---
+      # *Arguments*:
+      # * (required) _matrix_: Bio::Nexus::NexusMatrix
+      def set_matrix( matrix )
+        @matrix = matrix
+      end
+      
+    end # class DistancesBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::TreesBlock represents a trees nexus block.
+    #
+    # = Example of Trees block:
+    # Begin Trees;
+    #  Tree best=(fish,(frog,(snake, mouse)));
+    #  Tree other=(snake,(frog,( fish, mouse)));
+    # End;
+    #
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #
+    #   Get trees block(s):   
+    #   trees_block = nexus.get_trees_blocks[ 0 ]
+    #   # Get first tree named "best" as String:
+    #   string_fish = trees_block.get_tree_strings_by_name( "best" )[ 0 ]
+    #   # Get first tree named "best" as Bio::Db::Newick object:
+    #   tree_fish = trees_block.get_trees_by_name( "best" )[ 0 ]
+    #   # Get first tree as Bio::Db::Newick object:
+    #   tree_first = trees_block.get_tree( 0 )
+    #
+    class TreesBlock < GenericBlock
+      TREE  = "Tree"
+      def initialize( name )
+        super( name ) 
+        @trees      = Array.new
+        @tree_names = Array.new
+      end
+      
+      # Returns a String describing this block as nexus formatted data.
+      # ---
+      # *Returns*:: String
+      def to_nexus
+        trees_ary = Array.new
+        for i in 0 .. @trees.length - 1
+          trees_ary.push( TREE + " " + @tree_names[ i ] + "=" + @trees[ i ] )
+        end
+        Nexus::Util::to_nexus_helper( TREES_BLOCK, trees_ary  )
+      end
+      
+      # Returns an array of strings describing trees
+      # ---
+      # *Returns*:: Array
+      def get_tree_strings
+        @trees  
+      end
+      
+      # Returns an array of tree names.
+      # ---
+      # *Returns*:: Array
+      def get_tree_names
+        @tree_names 
+      end
+      
+      # Returns an array of strings describing trees
+      # for which name matches the tree name.
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      # *Returns*:: Array
+      def get_tree_strings_by_name( name )
+        found_trees = Array.new
+        i = 0
+        @tree_names.each do | n |
+          if ( n == name )
+            found_trees.push( @trees[ i ] )
+          end
+          i += 1
+        end
+        found_trees
+      end
+      
+      # Returns tree i (same order as in nexus data) as
+      # newick parsed tree object.
+      # ---
+      # *Arguments*:
+      # * (required) _i_: Integer
+      # *Returns*:: Bio::Newick
+      def get_tree( i )
+        newick = Bio::Newick.new( @trees[ i ] )
+        tree = newick.tree
+        tree
+      end
+      
+      # Returns an array of newick parsed tree objects
+      # for which name matches the tree name.
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String
+      # *Returns*:: Array of Bio::Newick
+      def get_trees_by_name( name )
+        found_trees = Array.new
+        i = 0
+        @tree_names.each do | n |
+          if ( n == name )
+            found_trees.push( get_tree( i ) )
+          end
+          i += 1
+        end
+        found_trees
+      end  
+      
+      # Adds a tree name to this block. 
+      # ---
+      # *Arguments*:
+      # * (required) _tree_name_: String
+      def add_tree_name( tree_name )
+        @tree_names.push( tree_name )
+      end
+     
+      # Adds a tree to this block. 
+      # ---
+      # *Arguments*:
+      # * (required) _tree_as_string_: String
+      def add_tree( tree_as_string )
+        @trees.push( tree_as_string )
+      end
+      
+    end # class TreesBlock
+    
+    
+    # == DESCRIPTION
+    # Bio::Nexus::NexusMatrix represents a characters or distance matrix,
+    # where the names are stored in column zero.
+    #
+    #
+    # == USAGE
+    #
+    #   require 'bio/db/nexus'
+    #
+    #   # Create a new parser:
+    #   nexus = Bio::Nexus.new( nexus_data_as_string )
+    #   # Get distances block(s):   
+    #   distances_block = nexus.get_distances_blocks[ 0 ]
+    #   # Get matrix as Bio::Nexus::NexusMatrix object:
+    #   matrix = distances_blocks.get_matrix
+    #   # Get value (column 0 are names):
+    #   val = matrix.get_value( 1, 5 )
+    #   # Return first row as String (all columns except column 0),
+    #   # values are separated by "_":
+    #   row_str_0 = matrix.get_row_string( 0, "_" )
+    #   # Return all rows named "ciona" as String (all columns except column 0),
+    #   # values are separated by "+":
+    #   ciona_rows = matrix.get_row_strings_by_name( "ciona", "+" ) 
+    class NexusMatrix
+      
+      # Nexus matrix error class.
+      class NexusMatrixError < RuntimeError; end
+      
+       # Creates new NexusMatrix.
+      def initialize()
+        @rows = Hash.new
+        @max_row = -1
+        @max_col = -1
+      end
+  
+      # Sets the value at row 'row' and column 'col' to 'value'.
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # * (required) _col_: Integer
+      # * (required) _value_: Object
+      def set_value( row, col, value ) 
+        if ( ( row < 0 ) || ( col < 0 ) )
+            raise( NexusTableError, "attempt to use negative values for row or column" )
+        end
+        if ( row > get_max_row() ) 
+          set_max_row( row )
+        end
+        if ( col > get_max_col() ) 
+          set_max_col( col )
+        end
+        row_map = nil
+        if ( @rows.has_key?( row ) ) 
+          row_map = @rows[ row ]
+        else 
+          row_map = Hash.new
+          @rows[ row ] = row_map
+        end
+        row_map[ col ] = value
+      end
+  
+      # Returns the value at row 'row' and column 'col'.
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # * (required) _col_: Integer
+      # *Returns*:: Object
+      def get_value( row, col )
+        if ( ( row > get_max_row() ) || ( row < 0 ) ) 
+          raise( NexusMatrixError, "value for row (" + row.to_s +
+            ") is out of range [max row: " + get_max_row().to_s + "]" )
+        elsif ( ( col > get_max_col() ) || ( row < 0 ) )
+          raise( NexusMatrixError, "value for column (" + col.to_s +
+           ") is out of range [max column: " + get_max_col().to_s + "]" )
+        end
+        r = @rows[ row ]
+        if ( ( r == nil ) || ( r.length < 1 ) ) 
+          return nil
+        end
+        r[ col ]
+      end
+  
+      # Returns the maximal columns number.
+      # ---
+      # *Returns*:: Integer
+      def get_max_col 
+        return @max_col
+      end
+  
+      # Returns the maximal row number.
+      # ---
+      # *Returns*:: Integer
+      def get_max_row 
+        return @max_row
+      end
+      
+      # Returns true of matrix is empty.
+      #
+      # ---
+      # *Returns*:: true or false
+      def is_empty?
+        return get_max_col < 0 || get_max_row < 0
+      end
+      
+      # Convenience method which return the value of
+      # column 0 and row 'row' which is usually the name.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer 
+      # *Returns*:: String
+      def get_name( row )
+        get_value( row, 0 ).to_s
+      end
+      
+      # Returns the values of columns 1 to maximal column length
+      # in row 'row' concatenated as string. Individual values can be
+      # separated by 'spacer'.
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer  
+      # * (optional) _spacer_: String
+      # *Returns*:: String
+      def get_row_string( row, spacer = "" )
+        row_str = String.new
+        if is_empty?
+          return row_str
+        end
+        for col in 1 .. get_max_col
+          row_str << get_value( row, col ) << spacer
+        end
+        row_str
+      end
+      
+      # Returns all rows as Array of Strings separated by 'spacer'
+      # for which column 0 is 'name'.
+      # ---
+      # *Arguments*:
+      # * (required) _name_: String  
+      # * (optional) _spacer_: String
+      # *Returns*:: Array
+      def get_row_strings_by_name( name, spacer = "" )
+        row_strs = Array.new
+        if is_empty?
+          return row_strs
+        end
+        for row in 0 .. get_max_row
+          if ( get_value( row, 0 ) == name )
+            row_strs.push( get_row_string( row, spacer ) )  
+          end
+        end
+        row_strs
+      end
+   
+      # Returns matrix as String, returns "empty" if empty.
+      # ---
+      # *Returns*:: String
+      def to_s
+        if is_empty?
+          return "empty"  
+        end
+        str = String.new
+        row_array = to_nexus_row_array( spacer = " ", false )
+        row_array.each do | row |
+          str << row << END_OF_LINE
+        end
+        str
+      end
+      alias to_str to_s
+      
+      # Helper method to produce nexus formatted data.
+      # ---
+      # *Arguments*:
+      # * (optional) _spacer_: String
+      # * (optional) _append_delimiter_: true or false
+      # *Returns*:: Array
+      def to_nexus_row_array( spacer = "", append_delimiter = true )
+        ary = Array.new
+        if is_empty?
+          return ary
+        end
+        max_length = 10
+        for row in 0 .. get_max_row
+          l = get_value( row, 0 ).length
+          if ( l > max_length )
+            max_length = l
+          end
+        end  
+        for row in 0 .. get_max_row
+          row_str = String.new
+          ary.push( row_str )
+          name = get_value( row, 0 )
+          name = name.ljust( max_length + 1 )
+          row_str << name << " " << get_row_string( row, spacer )
+          if ( spacer != nil && spacer.length > 0 )
+            row_str.chomp!( spacer )
+          end
+          if ( append_delimiter && row == get_max_row )
+            row_str << DELIMITER 
+          end
+        end
+        ary
+      end
+      
+
+      private
+  
+      # Returns row data as Array.
+      # ---
+      # *Arguments*:
+      # * (required) _row_: Integer
+      # *Returns*:: Array
+      def get_row( row ) 
+        return @rows[ row ]
+      end
+      
+      # Sets maximal column number.
+      # ---
+      # *Arguments*:
+      # * (required) _max_col_: Integer
+      def set_max_col( max_col ) 
+        @max_col = max_col
+      end
+      
+      # Sets maximal row number.
+      # ---
+      # *Arguments*:
+      # * (required) _max_row_: Integer
+      def set_max_row( max_row ) 
+        @max_row = max_row
+      end
+      
+    end # NexusMatrix
+  
+    # End of classes to represent nexus data.
+    
+    # = DESCRIPTION
+    # Bio::Nexus::Util is a class containing static helper methods
+    #
+    class Util
+      
+      # Helper method to produce nexus formatted data.
+      # ---
+      # *Arguments*:
+      # * (required) _block_: Nexus:GenericBlock or its subclasses
+      # * (required) _block_: Array
+      # *Returns*:: String
+      def Util::to_nexus_helper( block, lines )
+        str = String.new
+        str << BEGIN_BLOCK << " " << block << END_OF_LINE
+        lines.each do | line |
+          if ( line != nil )
+            str << INDENTENTION << line << END_OF_LINE
+          end
+        end # do
+        str << END_BLOCK << END_OF_LINE
+        str
+      end
+      
+      # Returns string as array separated by " ".
+      # ---
+      # *Arguments*:
+      # * (required) _ary_: Array  
+      # *Returns*:: String
+      def Util::array_to_string( ary )
+        str = String.new
+        ary.each do | e |
+          str << e << " "
+        end
+        str.chomp!( " " )
+        str  
+      end
+      
+      # Returns true if Integer i is not nil and larger than 0.
+      # ---
+      # *Arguments*:
+      # * (required) _i_: Integer 
+      # *Returns*:: true or false
+      def Util::larger_than_zero( i )
+        return ( i != nil && i.to_i > 0 )
+      end
+        
+      # Returns true if String str is not nil and longer than 0.
+      # ---
+      # *Arguments*:
+      # * (required) _str_: String 
+      # *Returns*:: true or false
+      def Util::longer_than_zero( str )
+        return ( str != nil && str.length > 0 )
+      end
+      
+    end # class Util
+      
+  end # class Nexus
+    
+end #module Bio
+
+