NAME
    ModelSim::List - Analyse the 'list' output of the ModelSim simulator

VERSION
    This document describes ModelSim::List 0.06 released on 2 June, 2007.

SYNOPSIS
        use ModelSim::List;
        $list = ModelSim::List->new;

        # ram.lst is generated by ModelSim
        # simulator (via the "write list" command)
        $list->parse('ram.lst') or
            die $list->error();

        # get the value of signal /ram/address at time 100:
        $value = $list->strobe('/ram/address', 100);

        # get the time when signal /alu/rdy get the value 1:
        $time = $list->time_of('/alu/rdy', 1);

        # specify regex rather than actual value:
        $time = $list->time_of('/processor/bus_data', qr/^z+$/i);

        $time = $list->time_of($signal, $value, $start_time);
        $time = $list->time_of($signal, $value, $start_time, $end_time);
        die $list->error() unless defined $time;

DESCRIPTION
    This module provides a class named "ModelSim::List" with which the EDA
    tester can easily check in the signals contained in the files generated
    by ModelSim's "write list" command in a programming manner.

METHODS
    "$list = ModelSim::List->new()"
        This is the constructor of the "ModelSim::List" class.

    "$list->parse($file_name)"
        This method gets the object parse the list file specified as
        $file_name. You can invoke the parse method on the same object
        several times. Once you specify a list file, the new file will
        override the old one completely. No matter whether you use an
        "-event" option in your "write list" command to generate the file or
        not, the object will recognize the list format automatically.

        I'd like to give one example for each of the two file format here:

                 ns       /ram/mfc
                  delta       /ram/bus_data
                  0  +2          1 xxxxxxxx
                  0  +3          0 zzzzzzzz
                 10  +0          1 0000aaaa
                 10  +1          0 0000abcd
                 29  +0          1 0000abcd
                 38  +0          0 0000abcd
                 38  +2          0 zzzzzzzz
                 86  +0          1 zzzzzzzz
                 86  +1          1 0000abcd

        and if you use the "-event" option in the "write list" command, the
        list file will like follows:

            @0 +0
            /ram/mfc x
            /ram/mfc 0
            /ram/bus_data zzzzzzzz
            /ram/bus_data zzzzzzzz
            @10 +0
            /ram/bus_data 0000abcd
            @29 +0
            /ram/mfc 1
            @38 +0
            /ram/mfc 0
            @38 +2

        The method returns 1 to indicate success. When it returns undef, it
        is recommended to check the error info via the "error()" method.

    "$list->error()"
        Returns the error message for the last failed operation.

    "$list->strobe($signal, $time)"
        The *strobe* method are used to get the value of a signal named
        $signal at any given time instant, $time. The object will preserve
        the original signal value format used in the list file. No format
        conversion will happen.

        When "strobe()" returns undef, it is recommended to check the
        detailed info via the "error()" method if you feel surprised.

        CAUTION: The delta number will be totally ignored. Therefore, if
        signal /module/a becomes 0 at "0 ns +0", and changes to 1 at "0 ns
        +1", thus "$obj->strobe('/module/a', 0)" will return 1 rather than
        0.

    "$list->time_of($signal, $value, ?$start, ?$end)"
        You can utilize the *time_of* method to get the time instant when
        $signal first gained the value $value within the time interval
        specified by $tart and $end. Both the last two arguments are
        optional. In the case that $start is missing, the initial time 0
        will be assumed. If the signal fails to achieve $value, *time_of*
        will return undef.

        If the $value argument is a regex ref, *time_of* will perform
        pattern matching instead of string comparing.

        When "time_of()" returns undef, it is recommended to check the
        detailed info via the "error()" method if you feel surprised.

VERSION CONTROL
    You can always get the latest source from the following Subversion
    repository:

    <http://svn.openfoundry.org/modlesimlist>

    which has anonymous access to all.

    If you do want a commit bit, please let me know.

BUGS
    There must be some serious bugs lurking somewhere. If you find one,
    please consider firing off a report to <http://rt.cpan.org>.

CODE COVERAGE
    I use Devel::Cover to test the code coverage of this module and here is
    the report:

     ---------------------------- ------ ------ ------ ------ ------ ------ ------
     File                           stmt   bran   cond    sub    pod   time  total
     ---------------------------- ------ ------ ------ ------ ------ ------ ------
     blib/lib/ModelSim/List.pm      89.4   82.8   77.8   91.7   40.0   99.7   85.0
     ---------------------------- ------ ------ ------ ------ ------ ------ ------

AUTHOR
    Agent Zhang (<agentzh@gmail.com>)

COPYRIGHT
    Copyright (C) 2005-2007 by Agent Zhang. All rights reserved.

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

SEE ALSO
    ModelSim Command Reference