%GregorioTeX common file (stuff needed by both gregoriotex and gregoriosyms)
%
% Copyright (C) 2007-2019 The Gregorio Project (see CONTRIBUTORS.md)
%
% This file is part of Gregorio.
%
% Gregorio is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% Gregorio is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with Gregorio.  If not, see <http://www.gnu.org/licenses/>.

\gre@declarefileversion{gregoriotex-commonx.tex}{5.2.1}% GREGORIO_VERSION


%%%%%%%%%
%% Debugging
%%%%%%%%%

\def\gre@debugmsg#1#2{%
	\IfStrEq{\gre@debug}{}{}%
		%false
		{\IfStrEq{#1}{all}%
			%true
			{\gre@error{Debug error: ‘all’ is not a permitted keyword}}%
			%false
			{\IfStrEq{\gre@debug}{,all,}%
				%true
				{\gre@typeout{GregorioTeX debug: (#1) #2}}%
				%false
				{\IfSubStr{\gre@debug}{,#1,}%
					%true
					{\gre@typeout{GregorioTeX debug: (#1) #2}}%
					%false
					{\relax}%
				}%
			}%
		}%
}%

\def\gre@fixdebug{%
	{% we're starting a group in order to localize \exploregroups
		\exploregroups%
		\StrRemoveBraces{\gre@debug}[\gre@debug]%
		\xdef\gre@debug{,\gre@debug,}%
	}%
}%

\IfStrEq{\gre@debug}{}{% then
}{% else
	\typeout{GregorioTeX is in debug mode}%
	\typeout{\gre@debug\space messages will be printed to the log.}%
	\gre@fixdebug\relax %
}%

%%%%%%%%%%%%%
% Macros to handle deprecation path.
%%%%%%%%%%%%%

% #1 - the deprecated macro
% #2 - the correct macro to use
\def\gre@deprecated#1#2{%
	\ifgre@allowdeprecated%
		\gre@warning{#1\space is deprecated.\MessageBreak Use #2\space instead}%
	\else%
		\gre@error{#1\space is deprecated.\MessageBreak Use #2\space instead}%
	\fi%
	\relax%
}%

\def\gre@obsolete#1#2{%
	\gre@error{#1\space is obsolete.\MessageBreak Use #2\space instead}%
	\relax%
}%

%%%%%%%%%%%%%
% Internal function tracing
%%%%%%%%%%%%%

% Each function in the internal name space (\gre@...) should have an invocation of
% \gre@trace as its first line with the argument being the name of the function (without
% the backslash) and the list of arguments.
% The last line of these functions should be \gre@trace@end.
% Macros which merely store a value are not considered to be functions and thus not
% included in the trace stack.
% We also exempt the internal aliases for functions defined elsewhere.
% The tracing messages are turned on via the debug interface, keyword: trace.

\def\gre@trace@prefix{GreTrace: }
\def\gre@trace#1{%
	\IfSubStr{\gre@debug}{,trace,}%
		{%print tracing messages and increase indent
			\gre@typeout{\gre@trace@prefix \unexpanded{#1}}%
			\edef\gre@trace@prefix{\gre@trace@prefix| }%
		}{}%do nothing if not tracing
}%
\def\gre@trace@end{%
	\IfSubStr{\gre@debug}{,trace,}%
		{%dedent trace messages and mark end
			\StrGobbleRight{\gre@trace@prefix}{2}[\gre@trace@prefix]%
			\gre@typeout{\gre@trace@prefix -----}%
		}{}%do nothing if not tracing
}