gen-ident-exceptions.pl - a script to gather a names of symbols exported

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• NOTES

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 requires or uses 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:).