NAME
    gen-ident-exceptions.pl - a script to gather a names of symbols exported
    by external modules that a set of perl files uses.

SYNOPSIS
    gen-ident-exceptions.pl [ --include-symbols-from-exporter ] 
    [ -p *perl-path* ] [ -d *dir-prefix-to-exclude* ]..
    [ -u *user-exceptions-file* ] ..
    [ -U *user-exception-comma-sep-list* ] ..
    [ -m *module-exceptions-file* ] ..
    [ -M *module-exception-comma-sep-list* ] ..
    [ -n *modulenames-to-skip-file* ] ..
    [ -N *modulenames-to-skip-comma-sep-list* ] ..
    [ -x *not-exceptions-file* ] ..
    [ -X *not-exception-comma-sep-list* ] ..  *destfile* *srcfiles*..

DESCRIPTION
    It is obvious that when obfuscating some perl file, the names of symbols
    the from the modules it imports should not be mangled (or obfuscated
    versions of all dependant modules needs to be shipped, which is not
    always convenient). The only way of excluding the symbol names from
    being mangled is to list them in *file with list of exceptions*. This
    utility is dedicated to creation of such *file with list of exceptions*.

OPTIONS
    The options after which there is a ellipsis (*..*) in the synopsis
    section accept a set of strings and thus may be specified several times.
    The values passed to such options will be merged. The values for all
    those options are strings that do not contain spaces and commas in them.
    If the value of such option contains only one space or comma, it is
    treated as there were two occurencies of that option with values formed
    from strings before and after that space or comma character. I.e. the
    following commandline strings will equally alter the behaviour of this
    script for option named -X:

        -X a -X b -X c -X d
        -X 'a b' -X c -X d
        -X 'a b c d'
        -X 'a,b' -X c -X d
        -X 'a,b,c,d'

    -p *perl-path*
        Specify the invokaction string for the backend. It does not need to
        specify the full path of the perl program. This option is intended
        for passing any additional options mostly used for specifying the
        location of modules your program requires. The passed string is
        prepended to the necessary options used for functionality of this
        script. The default value of this option is *perl* and is sufficient
        for most cases.

    -d *dir-prefix-to-exclude*
        Specify the set of directory name prefixes modules from which will
        be the modules whoose symbols will be added to *file with list of
        exceptions*. If you need to generate a list of a exceptions for a
        file in the current directory and you are unix-like OS, then it's
        very convenient to use the prefix */* to get a list of all
        exceptions (you will get a list of symbols from the modules that are
        located not in the current directory - e.g
        /usr/lib/perl5/5.6.1/Pod/Usage.pm).

    -u *user-exceptions-file*
    -U *user-exception-comma-sep-list*
        The -u option specifies filenames from which a list of symbols (each
        line of the file lists exactly one symbol name probably surrounded
        by spaces) that should be added to resultant set of exceptions is
        taken. E.g. the symbols *blah*, *foo*, *bar* will be extracted from
        the file with the following content:

         blah
           foo
          bar

        The -U option specifies the a list of symbols that should be added
        to resultant set of exceptions. E.g. all the following commandline
        fragments request to add symbols *blah*, *foo*, *bar*, *baz*:

            -U blah -U foo -U bar -U  baz
            -U 'blah foo' -U 'bar,baz'
            -U 'blah foo bar baz'

    --include-symbols-from-exporter
        If this option is specified, symbols listed as defined by
        Exporter::Heavy are not ignored. Previous versions of this utility
        included such symbols as exceptions; this commandline switch is
        added as a mean to active old behaviour.

    -m *module-exceptions-file*
    -M *module-exceptions-comma-sep-list*
        The -m option specifies filenames from which a list of module name
        prefixes symbols from which should be added to resultant set of
        exceptions is taken. The -M option specifies the module name
        prefixes but immediately on commandline.

        Module with name *$name* is considered *source for exceptions* if
        "(split('::',$name))[0]" was exactly equal (i.e.
        charcter-by-character, case-sensitive - in other words using "eq"
        perl operator) to the ones specifed directly via -M or mentioned in
        file specified using -m option.

        For example, specifying "-M App" will make all symbols from modules
        named *App::Manager*, *App::Packer* listed as exceptions, but not
        symbols from modules *AppConfig::MyFile* and *AppConfig::Std*.

    -n *modulenames-to-skip-file*
    -N *modulenames-to-skip-comma-sep-list*
        The -n option specifies filenames from which a list of module name
        prefixes symbols from which should be excluded from resultant set of
        exceptions is taken. The -N option specifies the module name
        prefixes treated this way but immediately on commandline.

        Module with name *$name* is not considered *source for exceptions*
        if "(split('::',$name))[0]" was exactly equal (i.e.
        charcter-by-character, case-sensitive - in other words using "eq"
        perl operator) to the ones specifed directly via -N or mentioned in
        file specified using -n option.

    -x *not-exceptions-file*
    -X *not-exception-comma-sep-list*
        The -x option specifies names of files from which a names of symbols
        to omit from output exceptions list is taken. The -X option
        specifies the names of symbols to omit from output exceptions list
        immediately on commandline.

        Use these options if you are sure that the code being obfuscated
        won't ever use symbols with these names from other modules (using
        these names for private variables is perfectly OK, of course) - this
        helps your programs to become even more obfuscated, especially if
        you use modules that export a lot of symbols (like e.g. *Gtk::**).

NOTES
    The files from which it extracts exceptions should be synaxically
    correct, and all modules it *require*s or *use*s should be present. If
    the modules the files from which it extracts exceptions are in
    non-standard locations, you should specify these locations using -p
    switch - e.g. to extract exceptions from file, that uses modules located
    in directory lib, add the following to your commandline:
    "-p 'perl -Ilib'".

    It's impossible to create a list of exceptions by using only -d switch
    for modules referenced using "require" operator. You will have to
    specify module name prefix to be able to extract symbols from such
    modules.

    This script extracts just symbol names, without any type information -
    i.e. if some module exports just two symbols - *$foo* and *%foo*, the
    resultant exceptions file will contain just one line with word "foo".
    The strings passed directly via -u, -x options and indirectly via files
    specified with -u, -x should also be symbol names, without package name
    part and without type-specific prefix (*$*, *%*, etc) - e.g. *bar*, not
    *$bar* or *$blah::bar* (though the script will try to extract bare
    symbol name).

    On unix-like OSes, in case all perl source files use modules from
    standard locations (/usr/lib, /usr/local/lib, etc) it's very convenient
    to invoke the gen-ident-exceptions.pl script with the relative paths to
    the perl source files, adding -d / to the commandline. This way you
    won't have to type common module prefixes your source file uses. On
    Windows same applies, but appending -d C: to the commandline instead
    (provided the perl is installed on drive C:).

