#region Copyright & License
//
// Copyright 2001-2006 The Apache Software Foundation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections;
using System.IO;

using log4net.Core;
using log4net.Layout.Pattern;
using log4net.Util;

namespace log4net.Layout
{
	/// <summary>
	/// A flexible layout configurable with pattern string.
	/// </summary>
	/// <remarks>
	/// <para>
	/// The goal of this class is to <see cref="PatternLayout.Format"/> a 
	/// <see cref="LoggingEvent"/> as a string. The results
	/// depend on the <i>conversion pattern</i>.
	/// </para>
	/// <para>
	/// The conversion pattern is closely related to the conversion
	/// pattern of the printf function in C. A conversion pattern is
	/// composed of literal text and format control expressions called
	/// <i>conversion specifiers</i>.
	/// </para>
	/// <para>
	/// <i>You are free to insert any literal text within the conversion
	/// pattern.</i>
	/// </para>
	/// <para>
	/// Each conversion specifier starts with a percent sign (%) and is
	/// followed by optional <i>format modifiers</i> and a <i>conversion
	/// pattern name</i>. The conversion pattern name specifies the type of
	/// data, e.g. logger, level, date, thread name. The format
	/// modifiers control such things as field width, padding, left and
	/// right justification. The following is a simple example.
	/// </para>
	/// <para>
	/// Let the conversion pattern be <b>"%-5level [%thread]: %message%newline"</b> and assume
	/// that the log4net environment was set to use a PatternLayout. Then the
	/// statements
	/// </para>
	/// <code lang="C#">
	/// ILog log = LogManager.GetLogger(typeof(TestApp));
	/// log.Debug("Message 1");
	/// log.Warn("Message 2");   
	/// </code>
	/// <para>would yield the output</para>
	/// <code>
	/// DEBUG [main]: Message 1
	/// WARN  [main]: Message 2  
	/// </code>
	/// <para>
	/// Note that there is no explicit separator between text and
	/// conversion specifiers. The pattern parser knows when it has reached
	/// the end of a conversion specifier when it reads a conversion
	/// character. In the example above the conversion specifier
	/// <b>%-5level</b> means the level of the logging event should be left
	/// justified to a width of five characters.
	/// </para>
	/// <para>
	/// The recognized conversion pattern names are:
	/// </para>
	/// <list type="table">
	///     <listheader>
	///         <term>Conversion Pattern Name</term>
	///         <description>Effect</description>
	///     </listheader>
	///     <item>
	///         <term>a</term>
	///         <description>Equivalent to <b>appdomain</b></description>
	///     </item>
	///     <item>
	///         <term>appdomain</term>
	///         <description>
	///				Used to output the friendly name of the AppDomain where the 
	///				logging event was generated. 
	///         </description>
	///     </item>
	///     <item>
	///         <term>c</term>
	///         <description>Equivalent to <b>logger</b></description>
	///     </item>
	///     <item>
	///         <term>C</term>
	///         <description>Equivalent to <b>type</b></description>
	///     </item>
	///     <item>
	///         <term>class</term>
	///         <description>Equivalent to <b>type</b></description>
	///     </item>
	///     <item>
	///         <term>d</term>
	///         <description>Equivalent to <b>date</b></description>
	///     </item>
	///     <item>
	///			<term>date</term> 
	///			<description>
	/// 			<para>
	/// 			Used to output the date of the logging event in the local time zone. 
	/// 			To output the date in universal time use the <c>%utcdate</c> pattern.
	/// 			The date conversion 
	/// 			specifier may be followed by a <i>date format specifier</i> enclosed 
	/// 			between braces. For example, <b>%date{HH:mm:ss,fff}</b> or
	/// 			<b>%date{dd MMM yyyy HH:mm:ss,fff}</b>.  If no date format specifier is 
	/// 			given then ISO8601 format is
	/// 			assumed (<see cref="log4net.DateFormatter.Iso8601DateFormatter"/>).
	/// 			</para>
	/// 			<para>
	/// 			The date format specifier admits the same syntax as the
	/// 			time pattern string of the <see cref="DateTime.ToString(string)"/>.
	/// 			</para>
	/// 			<para>
	/// 			For better results it is recommended to use the log4net date
	/// 			formatters. These can be specified using one of the strings
	/// 			"ABSOLUTE", "DATE" and "ISO8601" for specifying 
	/// 			<see cref="log4net.DateFormatter.AbsoluteTimeDateFormatter"/>, 
	/// 			<see cref="log4net.DateFormatter.DateTimeDateFormatter"/> and respectively 
	/// 			<see cref="log4net.DateFormatter.Iso8601DateFormatter"/>. For example, 
	/// 			<b>%date{ISO8601}</b> or <b>%date{ABSOLUTE}</b>.
	/// 			</para>
	/// 			<para>
	/// 			These dedicated date formatters perform significantly
	/// 			better than <see cref="DateTime.ToString(string)"/>.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>exception</term>
	///			<description>
	///				<para>
	///				Used to output the exception passed in with the log message.
	///				</para>
	///				<para>
	/// 			If an exception object is stored in the logging event
	/// 			it will be rendered into the pattern output with a
	/// 			trailing newline.
	/// 			If there is no exception then nothing will be output
	/// 			and no trailing newline will be appended.
	/// 			It is typical to put a newline before the exception
	/// 			and to have the exception as the last data in the pattern.
	///				</para>
	///			</description>
	///		</item>
	///     <item>
	///         <term>F</term>
	///         <description>Equivalent to <b>file</b></description>
	///     </item>
	///		<item>
	///			<term>file</term>
	///			<description>
	///				<para>
	///				Used to output the file name where the logging request was
	///				issued.
	///				</para>
	///				<para>
	///				<b>WARNING</b> Generating caller location information is
	///				extremely slow. Its use should be avoided unless execution speed
	///				is not an issue.
	///				</para>
	/// 			<para>
	/// 			See the note below on the availability of caller location information.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>identity</term>
	///			<description>
	///				<para>
	///				Used to output the user name for the currently active user
	///				(Principal.Identity.Name).
	///				</para>
	///				<para>
	///				<b>WARNING</b> Generating caller information is
	///				extremely slow. Its use should be avoided unless execution speed
	///				is not an issue.
	///				</para>
	///			</description>
	///		</item>
	///     <item>
	///         <term>l</term>
	///         <description>Equivalent to <b>location</b></description>
	///     </item>
	///     <item>
	///         <term>L</term>
	///         <description>Equivalent to <b>line</b></description>
	///     </item>
	///		<item>
	///			<term>location</term>
	///			<description>
	/// 			<para>
	/// 			Used to output location information of the caller which generated
	/// 			the logging event.
	/// 			</para>
	/// 			<para>
	/// 			The location information depends on the CLI implementation but
	/// 			usually consists of the fully qualified name of the calling
	/// 			method followed by the callers source the file name and line
	/// 			number between parentheses.
	/// 			</para>
	/// 			<para>
	/// 			The location information can be very useful. However, its
	/// 			generation is <b>extremely</b> slow. Its use should be avoided
	/// 			unless execution speed is not an issue.
	/// 			</para>
	/// 			<para>
	/// 			See the note below on the availability of caller location information.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>level</term>
	///			<description>
	/// 			<para>
	/// 			Used to output the level of the logging event.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>line</term>
	///			<description>
	///				<para>
	///				Used to output the line number from where the logging request
	///				was issued.
	///				</para>
	///				<para>
	///				<b>WARNING</b> Generating caller location information is
	///				extremely slow. Its use should be avoided unless execution speed
	///				is not an issue.
	///				</para>
	/// 			<para>
	/// 			See the note below on the availability of caller location information.
	/// 			</para>
	///			</description>
	///		</item>
	///     <item>
	///         <term>logger</term>
	///         <description>
	///             <para>
	///				Used to output the logger of the logging event. The
	/// 			logger conversion specifier can be optionally followed by
	/// 			<i>precision specifier</i>, that is a decimal constant in
	/// 			brackets.
	///             </para>
	/// 			<para>
	/// 			If a precision specifier is given, then only the corresponding
	/// 			number of right most components of the logger name will be
	/// 			printed. By default the logger name is printed in full.
	/// 			</para>
	/// 			<para>
	/// 			For example, for the logger name "a.b.c" the pattern
	/// 			<b>%logger{2}</b> will output "b.c".
	/// 			</para>
	///         </description>
	///     </item>
	///     <item>
	///         <term>m</term>
	///         <description>Equivalent to <b>message</b></description>
	///     </item>
	///     <item>
	///         <term>M</term>
	///         <description>Equivalent to <b>method</b></description>
	///     </item>
	///		<item>
	///			<term>message</term>
	///			<description>
	/// 			<para>
	/// 			Used to output the application supplied message associated with 
	/// 			the logging event.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>mdc</term>
	///			<description>
	/// 			<para>
	/// 			The MDC (old name for the ThreadContext.Properties) is now part of the
	/// 			combined event properties. This pattern is supported for compatibility
	/// 			but is equivalent to <b>property</b>.
	/// 			</para>
	///			</description>
	///		</item>
	///		<item>
	///			<term>method</term>
	///			<description>
	///				<para>
	///				Used to output the method name where the logging request was
	///				issued.
	///				</para>
	///				<para>
	///				<b>WARNING</b> Generating caller location information is
	///				extremely slow. Its use should be avoided unless execution speed
	///				is not an issue.
	///				</para>
	/// 			<para>
	/// 			See the note below on the availability of caller location information.
	/// 			</para>
	///			</description>
	///		</item>
	///     <item>
	///         <term>n</term>
	///         <description>Equivalent to <b>newline</b></description>
	///     </item>
	///		<item>
	///			<term>newline</term>
	///			<description>
	/// 			<para>
	/// 			Outputs the platform dependent line separator character or
	/// 			characters.
	/// 			</para>
	/// 			<para>
	/// 			This conversion pattern offers the same performance as using 
	/// 			non-portable line separator strings such as	"\n", or "\r\n". 
	/// 			Thus, it is the preferred way of specifying a line separator.
	/// 			</para> 
	///			</description>
	///		</item>
	///		<item>
	///			<term>ndc</term>
	///			<description>
	/// 			<para>
	/// 			Used to output the NDC (nested diagnostic context) associated
	/// 			with the thread that generated the logging event.
	/// 			</para>
	///			</description>
	///		</item>
	///     <item>
	///         <term>p</term>
	///         <description>Equivalent to <b>level</b></description>
	///     </item>
	///     <item>
	///         <term>P</term>
	///         <description>Equivalent to <b>property</b></description>
	///     </item>
	///     <item>
	///         <term>properties</term>
	///         <description>Equivalent to <b>property</b></description>
	///     </item>
	///		<item>
	///			<term>property</term>
	///			<description>
	/// 			<para>
	/// 			Used to output the an event specific property. The key to 
	/// 			lookup must be specified within braces and directly following the
	/// 			pattern specifier, e.g. <b>%property{user}</b> would include the value
	/// 			from the property that is keyed by the string 'user'. Each property value
	/// 			that is to be included in the log must be specified separately.
	/// 			Properties are added to events by loggers or appenders. By default 
	/// 			the <c>log4net:HostName</c> property is set to the name of machine on 
	/// 			which the event was originally logged.
	/// 			</para>
	/// 			<para>
	/// 			If no key is specified, e.g. <b>%property</b> then all the keys and their