Smart::comments 方便的追踪调试程序

语法:

    use Smart::Comments;

    my $var = suspect_value();

    ### $var

    ### got: $var

    ### Now computing value...

    # and when looping:

    for my $big_num (@big_nums) {  ### Factoring...      done
        factor($big_num);
    }

    while ($error > $tolerance) {  ### Refining--->      done
        refine_approximation()
    }

    for (my $i=0; $i<$MAX_INT; $i++) {   ### Working===[%]     done
        do_something_expensive_with($i);
    }

描述：

Smart comments 提供简单的昂是插入调试追踪程序。 能够报告变量，追踪循环，验证数据。

最方便的是调试之后，无需移走这些。仅仅是正规的注释语句。可以以后特殊情况再次的使用这些调试。

通过注释调试：

最简单方式使用模块是为了进行调试。模块支持下列方式的的调试，打印到stderr中

### LABEL : EXPRESSION

The LABEL：之前的字符。 表达式是有效的任何包括简单变量的perl表达式。 打印这个表达式的到这个标签中。

例如：

### Expected: 2 * $prediction
###      Got: $result

结果打印:

    ### Expected: 42
    ###      Got: 13

### EXPRESSION

表达式是任何包括简单变量的perl的表达式，打印表达式的值。例如：

    ### 2 * $prediction
    ### $result

结果打印：

    ### 2 * $prediction: 42
    ### $result: 13

### TEXT...

The TEXT is any sequence of characters that end in three dots. When active, the comment just prints the text, including the dots. For example:

任何三个.符号结尾的字符，注视将打印这个文本包括.符号。例如

    ### Acquiring data...

    $data = get_data();

    ### Verifying data...

    verify_data($data);

    ### Assimilating data...

    assimilate_data($data);

    ### Tired now, having a little lie down...

    sleep 900;

设想打印:

    ### Acquiring data...

    ### Verifying data...

    ### Assimilating data...

    ### Tired now, having a little lie down...

每个注释阶段，尤其适用在精确的bug打印中。 也用于非调试环境中，尤其批处理环境，每个流程的反馈中。

在每个注释流程中，可以使用时间打印值用户调试和流程的监控。(<now>,<time> or<when> )

### [<now>] Acquiring data...

类似的输出结果：

### [Fri Nov 18 15:11:15 EST 2005] Acquiring data...

也有位置的输出符（<here>，<line> or <loc> or <place> or <where>）

### Acquiring data at <loc>...

输出结果例如：

### Acquiring data at "demo.pl", line 7...

当然你也能使用两个注释

通过注释检查声明条件

### require: BOOLEAN_EXPR### assert: BOOLEAN_EXPR### ensure: BOOLEAN_EXPR### insist: BOOLEAN_EXPR四个相同语法的行为。注释产生布尔值得表达式，如果为真，什么都不做。如果为假，注释将长生一个异常列出表达式实际失败的值。例如：

### require: $min < $result && $result < $max

如果表达式失败，打印下边的结果：

### $min < $result && $result < $max was not true at demo.pl line 86.
###     $min was: 7
###     $result was: 1000004
###     $max was: 99

进度条:

你能放置注释在任何下一个循环的同一行，如下循环：

    foreach my VAR ( LIST ) {       ### Progressing...   done

    for my VAR ( LIST ) {           ### Progressing...   done

    foreach ( LIST ) {              ### Progressing...   done

    for ( LIST ) {                  ### Progressing...   done

    while (CONDITION) {             ### Progressing...   done

    until (CONDITION) {             ### Progressing...   done

    for (INIT; CONDITION; INCR) {   ### Progressing...   done

任何一种循环下，模块动态产生生动态的符号.对于循环剩余的值。对于open 模式的循环（类似while 和c类型的循环），永远不能达到右边的值，只是置慢速的增长。

例如:

for (@candidates) {       ### Evaluating...     done

产生动态的下边的过程（产生在单独的一行，不是同一行）

    Evaluating                          done

    Evaluating......                    done

    Evaluating.............             done

    Evaluating...................       done

    Evaluating..........................done

模块动态产生的进度条的字符在注释符之后连续三个相同的字符，之后提供至少两个空格字符，因此你能指定不同的的字符作为进度条。例如：

for (@candidates) {       ### Evaluating:::     done

or:

for (@candidates) {       ### Evaluating===     done

or:

for (@candidates) {       ### Evaluating|||     done

如果在进度条之前出现非空字符，非空字符将产生前导进度字符。例如:

for (@candidates) {       ### Evaluating===|    done

结果如下：

    Evaluating|                         done

    Evaluating=====|                    done

    Evaluating============|             done

    Evaluating==================|       done

    Evaluating==========================done

如果%字符出现在任何位置，将产生百分号的进度提示。例如：

for (@candidates) {       ### Evaluating [===|    ] % done

结果如下：

    Evaluating [|                ]   0% done

    Evaluating [===|             ]  25% done

    Evaluating [========|        ]  50% done

    Evaluating [============|    ]  75% done

    Evaluating [=================] 100% done

对于while等未知据的循环，模块替代百分率的显示为迭代的次数。例如：

while ($next ne $target) {       ### Evaluating |===[%]    |

结果如下：

    Evaluating |[0]                        |

    Evaluating |=[2]                       |

    Evaluating |==[3]                      |

    Evaluating |===[5]                     |

    Evaluating |====[7]                    |

    Evaluating |=====[8]                   |

    Evaluating |======[11]                 |

配置和环境变量

模块能使用你shell的Smart_Comments环境变量。只被指定true or false（1 or 0）。

    Value of
    $ENV{Smart_Comments}          Equivalent Perl

            1                     use Smart::Comments;
            0                      no Smart::Comments;
        '###:####'                use Smart::Comments qw(### ####);
        '### ####'                use Smart::Comments qw(### ####);

为了使Smart_Comments环境变量生效，你需要使用-ENV参数来加载。

use Smart::Comments -ENV;