################################################################################################################
# STLFilt.pl: BD Software STL Error Message Decryptor (a Perl script)
#			  This version supports MSVC 6/7/7.1 in conjunction with any of the 
#			  following libraries:
#					Native MSVC 6 Library
#					Native MSVC 7.x (.NET) Library
#					STLPort 4.x Library
#					Dinkum 3.08 Library
#					Dinkum Unabridged Library
#
#			  (Under VC7/.NET, the compiler's /WL option *MUST* be supplied)
#

$STLFilt_ID = "BD Software STL Message Decryptor (Release 2.70 for MSVC 6/7)";

#
# (C) Copyright Leor Zolman 2001-2003. Permission to copy, use, modify, sell and
# distribute this software is granted provided this copyright notice appears
# in all copies. This software is provided "as is" without express or implied
# warranty, and with no claim as to its suitability for any purpose.
#
#################################################################################################################
#    Visit www.bdsoft.com for information about BD Software's on-site training seminars                         #
#    in C, C++, STL, Java, Perl, Unix Fundamentals and Korn Shell Programming                                   #
#################################################################################################################
#
# For quick installation instructions for the STL Error Decryptor, see QUICKSTART.txt.
# For manifest and other general information, see README.txt
#
# (Note: hard tab setting for this source file is: 4)
#
# Purpose:	Transform STL template-based typenames from MSVC error messages
#			into a minimal, *readable* format. We might lose some details...
#			but retain our sanity! 
#
# This file is part of a package including:
#
#			CL.cpp/.exe					The "Proxy" CL.EXE replacement,
#			STLTask.cpp/.exe			A taskbar icon-based error decryption control utility,
#			STLFilt.BAT					A "low-bandwidth" batch file for error decryption control
#			MFilt.BAT					A simple command-line driver for compiling w/Decryption
#			MFiltTool.BAT				Command-line driver for use with MSVC Custom Tool
#
# This script may be used in several different ways:
#	1) With the "Proxy CL" program, CL.CPP 
#	2) With a batch file such as MFilt.BAT (for explicit command-line use only)
#	3) As a VC++ "Tool" in conjunction with a script such as MFiltTool.BAT 
#	   (see README-VCTool.txt for instructions on configuring this approach)
#
# Acknowledgements:
#   David Smallberg came up with the "Proxy compiler" idea (but blame me for the name).
#   Scott Meyers taught his "Effective STL" seminar, where the project began.
#   Thomas Becker wrote and helps me maintain the Win32 piping code used throughout both CL.CPP and 
#       STLFilt.pl, keeping everyone talking despite all the curves thrown him (so far) by ActiveState
#       and Microsoft. THANK YOU, Thomas!
#   David Abrahams designed the long-typename-wrapping algorithm and continues to contribute actively
#		to its evolution.
#
# For the complete list of folks whose feedback and de-bugging help contributed to this
# package, and also for the list of programming courses BD Software offers, see README.txt.
#
#
#################################################################################################################
#
#   Script Options
#   --------------
#
#	Command line options are case insensitive, and may be preceded by either '-' or '/'.
#   The Proxy CL, if being used, supplies many of these options as per settings in the
#   Proxy-CL.INI configuration file.
#
#	Note that some of the Decryptor's behavior is controlled via command-line options,
#	while other behavior may only be configured via hard-wired variable settings. Please
#   examine the entire "User-Configurable Settings" section below to become familiar with
#   all the customizable features.
#
#	General options:
#
#			/plg				Specify we're processing a .PLG file, as when running
#								from an MSVC Tool in conjunction with a batch file
#								such as the provided MFiltTool.BAT
#
#			/iter:x				Set iterator policy to x, where x is s[short], m[edium] or l[ong]
#								(See the assignments of $def_iter_policy and $newiter below for details)
#
#								The following two options apply ONLY to VC7:
#			/alloc:x			Set allocator policy s[short] or l[ong]
#								(Don't use /alloc:L with VC7, it's broken)
#
#			/func:x				Set functor policy s[hort], or l[ong]
#								(See the assignment of $def_func_policy below for details)
#
#								(The three options above are typically 
#								conveyed to Perl by the Proxy CL)
#
#			/with:x				Set "with clause" substitution policy to x, where x is L[ong] or  S[hort]
#								(See the assignment of $def_with_policy below for details)
#
#			/width:nn			Set output text area width (will break
#								message lines at this column. Most useful
#								under VC7 when /func:L or /iter:L are being
#								used; required with /meta or /break)
#
#			/lognative			log native messages to NativeLog.txt 
#								(for de-bugging; may be automatically enabled via 
#								the LOG_NATIVE_MSGS option in Proxy-CL.INI file, but
#								there is no corresponding Proxy CL option)
#
#			/banner:x			Show banner or not (Y or N, defaults to Y, forced
#								to N by the Proxy CL)
#
#
#	Options supporting long typename wrapping:
#
#								(Note: If output width is set to 0, there is no line wrapping at all
#								and the following options are no-ops)
#
#			/break:x			Break algorithm: D[ave Abrahams] or P[lain] (default).
#								The "Dave" option wraps long complex typenames in a way that
#								makes it easier to see parameter lists at various nesting depths. 
#                               This is most beneficial for apps involving template metaprogramming.
#
#								******The following options apply only in /break:D (Dave) mode: ******
#
#			/cbreak:x			Comma break: B = break before commas (default), A = break after
#								(Applies during /break;D mode only)
#
#			/closewrap:x		Wrap before unmatched closing delimiters: Y (default) or N
#								(Applies during /break;D mode only)
#
#			/meta:x				Configure for metaprogramming [Y] or vanilla wrapping [N] as follows:
#
#								/meta:y (or just /meta) forces /break:D, and forces /cbreak and
#								/closewrap options according to values specified in the $meta_y_cbreak
#								and $meta_y_closewrap variable initializations, respectively.
#
#								/meta:n forces /break:P (/cbreak and /closewrap don't apply)
#
#								In either case, if the output width hasn't yet been set to a non-zero
#								value, it is set to 80 (choosing a wrapping flavor makes no sense
#								with wrapping disabled); this may be overridden by a subsequent /width
#								option.
#
#								Note: If no /meta option is present, the default values for /break,
#								/cbreak and /closewrap are determined by the user-configurable
#								settings of $break_algorithm, $comma_wrap and $close_wrap below.
#
#								Note also that /meta is not configurable from the INI files, because
#								it is intended as a command-line "override" mechanism. The individual
#								settings of /break, /cbreak and /closewrap, however, *are* (and apply
#								only when the /meta option is not used.)
#
#################################################################################################################
# User-configurable settings  (use UPPER CASE ONLY for all alphabetics here):
#
							############################################################################
							# The following ten settings may be overridden by options on
							# the command line (either explicitly, or when conveyed by the
							# Proxy CL from settings in Proxy-CL.INI):

							# default iterator policy:
$def_iter_policy = 'M';		# 'L' (Long): NEVER remove iterator type name qualification
							# 'M' (Medium): USUALLY remove iterator type name qualification
							#               leave intact when iter type may be significant
							#				to the diagnostic
							# 'S' (Short): ALWAYS remove iterator type name qualification

$def_alloc_policy = 'S';	# default allocator policy (applies to VC7/.NET only):
							# 'L' (Long): leave allocator info intact (BROKEN)
							# 'S' (Short): strip all allocator information

$def_func_policy = 'S';		# default functor policy (applies to VC7/.NET only):
							# 'L' (Long): leave default functor info intact
							# 'S' (Short): strip all default functor information

$def_with_policy = 'S';		# default "with clause" substitution policy (/with:x option):
							# 'L' (long): Do NOT substitute in template parameters in "with" clauses
							# 'S' (short): Do substitute template parameters in "with" clauses

$banner = 'Y';				# by default, show a banner (Proxy CL overrides this to 'N')

$break_algorithm = 'P';		# P[lain] or D[ave Abrahams] line-breaking algorithm (/break:x option)
							# (Note: line-breaking of any kind happens only if $output_width is non-zero)

$comma_wrap = 'B';			# wrap lines B[efore] or A[fter] commas. (/cbreak:x option)
							# (Applies in Dave mode only.)

$close_wrap = 'Y';			# Force a break before close delimiters
							# whose open is not on the same line  (/closewrap:x option)
							# (Applies in Dave mode only.)

$output_width = 0;			# default line wrapping column (0 = no line wrap)
							# (note: with wrapping enabled, only the first wrapped line of
							# an error message will appear down in the status bar when you
							# double-click the message from within the IDE output window)

$lognative = 0;				# by default, not logging native messages


							#####################################################################################
							# The remaining settings in this section can only be configured here in the
							# Perl source (there are no corresponding command-line options):

$newiter = 'iter';			# ('iter' or 'IT' or...) shorten the word "iterator" to this
							# Note: /iter:L forces $newiter to be 'iterator' (no filtering)

$tabsize = 4;				# number of chars to incrementally indent lines

$alloc = 'alloc';			# shorten the word "allocator" to this

$hide_generated_warns = 1;	# "has generated" warnings suppressed if 1
$hide_deprecated_warns = 1;	# "was declared deprecated" warnings suppressed if 1

$smush_amps_and_stars = 0;	# 1 leaves asterisks/ampersands adjacent to preceding identifiers;
							# 0 inserts a space between

$keep_space_pre_colon = 0;	# True to retain space after line number / before colon (for
							# compatibility with 3rd party tools such as Rational RoseRT)

$space_after_commas = 0;	# 1: force spaces after commas, 0: don't

$meta_y_cbreak = 'B';		# /meta:y forces this value for cbreak
$meta_y_closewrap = 'Y';	# /meta:y forces this value for closewrap

$keep_stdns = 0;			# 0 to remove "std::" and related prefixes, 1 to retain them.
							# NOTE: if set to 1, STL-related filtering will *not* take place. This option
							# is designed for use in conjunction with /break:D to retain maximum detail in
							# metaprogramming-style messages, rather than for use with STL library messages.

$show_internal_err = 1;		# Set to 0 for use with web-based online compilers ;-)

#
# END of user-configurable settings
#################################################################################################################


$| = 1;											# set output autoflush

$iter_policy = $def_iter_policy;				# default iterator policy
$alloc_policy = $def_alloc_policy;				# default allocator policy (used w/VC7 ONLY)
$func_policy = $def_func_policy;				# default functor policy (used w/VC7 ONLY)
$with_policy = $def_with_policy;				# default "with clause" substitution policy
$tab = " " x $tabsize;
$indent_string = ("\n" . $tab);
$plg = 0;										# Not processing .PLG file
$plg_sawcompiling = 0;							# Haven't seen "Compiling..." yet
$doing_brackets = 0;							# Aren't processing a [...] sequence in PLG file

$pdbg = 0;										# true to show print trace
$wrapdbg = 0;									# de-bug wrap loop
$delimdbg = 0;									# de-bug /wrap:D mode delimiter parsing
$choked = 0;									# haven't choked yet with an internal error

sub break_and_print;
sub break_and_println;
sub break_and_print_plain;
sub break_and_print_fragment;
sub print2;
sub scanback;
sub lognative_header;
sub showkey;

#sub custom;									# declare custom post-processing steps here

# Little hack to avoid "Exiting subroutine via next" warnings on internal error:
sub NoWarn
{
	$msg = shift (@_);
	print "$msg" if $msg !~ /Exiting subroutine via next/;
}

$SIG{__WARN__} = "NoWarn";

@save_args = @ARGV;								# lognative_header uses this

while (@ARGV)									# process command-line options
{
	if ($ARGV[0] =~ /^[\/-]iter:([SML])[a-zA-Z]*$/i) # allow command-line iterator policy
	{												 # specification of form: /iter:x
		$iter_policy = "\u$1";
		$newiter = 'iterator' if $iter_policy eq 'L';
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]alloc:([SL])[a-zA-Z]*$/i) # allow command-line allocator policy
	{												 # specification of form: /alloc:x
		$alloc_policy = "\u$1";
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]func:([SL])[a-zA-Z]*$/i) # allow command-line functor policy
	{												# specification of form: /func:x
		$func_policy = "\u$1";						# (applies to hash_compare<...> and	
		shift;										# equal<...> functors under VC7 ONLY)
		next;
	}

	if ($ARGV[0] =~ /^[\/-]with:([YNSL])[A-Z]*$/i) # allow with clause policy
	{											   # specification of form: /with:x
		$with_policy = "\u$1";
		$with_policy =~ tr/NY/LS/;
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]width:(\d+)/i)			# allow line output width spec
	{												# of form: /width:n
		$output_width = $1;
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]break:([DP])[A-Z]*$/i)	# break: D or P
	{
		$break_algorithm = "\u$1";
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]cbreak:([AB])[A-Z]*$/i)  # comma break: B or A
	{
		$comma_wrap = "\u$1";
		shift;
		next;
	}

	if ($ARGV[0] =~ /^[\/-]closewrap:?([YN]?)[A-Z]*$/i)  # closewrap:Y or N