NAME
    Devel::Hints - Access compile-time hints at runtime

VERSION
    This document describes version 0.20 of Devel::Hints, released November
    8, 2010.

SYNOPSIS
        use Devel::Hints ':all';

        LABEL:
        print cop_label();      # 'LABEL'
        # cop_label is only settable on Perl 5.8 or below
        cop_label(0 => 'FOO');  # "goto FOO;" is valid after this point!

        print cop_file();       # same as __FILE__
        print cop_filegv();     # same as \$::{'_<' . __FILE__}
        print cop_stashpv();    # same as __PACKAGE__
        print cop_stash();      # same as \%{__PACKAGE__ . '::'}
        print cop_seq();        # an integer
        print cop_line();       # same as __LINE__

        # cop_arybase() is only settable on Perl 5.8 or below
        print cop_arybase();    # same as $[

        # cop_warnings() is only available to Perl 5.8 or below
        use warnings;
        print cop_warnings();   # same as compile-time ${^WARNING_BITS}

        # cop_io() is only available to Perl 5.7 and Perl 5.8
        use open IO => ':utf8';
        print cop_io();         # same as compile-time ${^OPEN}

        {
            use IO => ':raw';
            print cop_io(1);    # access one uplevel; still ":utf8\0:utf8"
        }

DESCRIPTION
    This module exports the "cop" (code operator) struct as individual
    functions; callers can call them to find out the lexical-scoped hints
    that its block (or statement) is compiled under.

    No functions are exported by default. Each function may take an optional
    positive integer as argument, indicating how many blocks it should walk
    upward to obtain the "cop" members.

    Functions can also take another optional argument, which (if specified)
    *becomes the new value* for the hint, affecting the current statement or
    block's behaviour.

FUNCTIONS
    cop_label
        Label for the current construct.

    cop_file
        File name for the current source file.

    cop_filegv
        Glob reference to the current source filehandle.

    cop_stashpv
        The current package name.

    cop_stash
        Hash reference to the current symbol table.

    cop_seq
        Parse sequencial number.

    cop_arybase
        Array base the calling line was compiled with.

    cop_line
        The line number.

    cop_warnings
        Lexical warnings bitmask, a.k.a. "${^WARNING_BITS}". If no lexical
        warnings are in effect, returns the global warning flags as an
        integer.

    cop_io
        Lexical IO defaults, a.k.a. "${^OPEN}". If no lexical IO layers are
        in effect, an empty string is returned. Always returns "undef" under
        pre-5.7 versions of Perl.

ACKNOWLEDGMENTS
    Thanks to Rafael Garcia-Suarez for demonstrating how to do this with the
    elegant Inline::C code on p5p, which I adapted to this less elegant XS
    implementation.

AUTHORS
    唐鳳 <cpan@audreyt.org>

CC0 1.0 Universal
    To the extent possible under law, 唐鳳 has waived all copyright and
    related or neighboring rights to Convert-EastAsianWidth.

    This work is published from Taiwan.

    <http://creativecommons.org/publicdomain/zero/1.0>

