#13 Add WikiImageLink node type.

Rename: FILE_LINK --> IMAGE_LINK

Author: CXuesong

CFG.txt

@@ -81,14 +81,15 @@ EXPANDABLE_URL  -> EXPANDABLE EXPANDABLE_URL
                 /  URL
                 /  empty
 
-FILE_LINK           -> "[[" FILE_LINK_TARGET FILE_LINK_OPTION* FILE_LINK_CAPTION? "]]"
-                    >| "]]"                                     # FILE_LINK_OPTION and FILE_LINK_CAPTION can have \n inside.
-FILE_LINK_TARGET    -> "[\s_]*(File|Image|<...>)[\s_]*:" EXPANDABLE_TEXT
+# Syntax for inserting an image or thumbnail
+# c.f. https://www.mediawiki.org/wiki/Help:Images#Rendering_a_single_image
+IMAGE_LINK          -> "[[" IMAGE_LINK_TARGET IMAGE_LINK_ARGUMENT* "]]"
+                    >| "]]"                                     # IMAGE_LINK_OPTION and IMAGE_LINK_CAPTION can have \n inside.
+IMAGE_LINK_TARGET   -> "[\s_]*(File|Image|<...>)[\s_]*:" EXPANDABLE_TEXT
                     +| "|"                                      # <...> is customizable File namespace aliases.
-FILE_LINK_OPTION    -> "|" EXPANDABLE_TEXT
-                    +| "|"
-FILE_LINK_CAPTION   -> "|" EXPANDABLE_TEXT                      # FILE_LINK_CAPTION is actually the last FILE_LINK_OPTION
-                    +| "]]"
+IMAGE_LINK_ARGUMENT -> "|" WIKITEXT "=" WIKITEXT
+                    /  "|" WIKITEXT                             # IMAGE_LINK_CAPTION is actually the last IMAGE_LINK_ARGUMENT
+                    +| "|" / "]]"
 
 # Known issue: Current implementation will parse [[http://abc]] as WIKI_LINK,
 # while actually it should be trated as "[" EXTERNAL_LINK "]"

MwParserFromScratch/MwParserUtility.cs

@@ -12,12 +12,9 @@ namespace MwParserFromScratch
     /// </summary>
     public static class MwParserUtility
     {
-        /// <summary>
-        /// Normalizes a template argument name.
-        /// </summary>
-        /// <param name="argumentName">The argument name to be normalized.</param>
-        /// <returns>The normalized argument name, with leading and trailing whitespace removed,
-        /// or <c>null</c> if <see cref="argumentName"/> is <c>null</c>.</returns>
+
+        /// <inheritdoc cref="NormalizeTemplateArgumentName(string)"/>
+        /// <param name="argumentName">The argument name to be normalized. The node will be converted into its string representation.</param>
         public static string NormalizeTemplateArgumentName(Node argumentName)
         {
             if (argumentName == null) return null;
@@ -29,23 +26,41 @@ public static string NormalizeTemplateArgumentName(Node argumentName)
         /// </summary>
         /// <param name="argumentName">The argument name to be normalized.</param>
         /// <returns>The normalized argument name, with leading and trailing whitespace removed,
-        /// or <c>null</c> if <see cref="argumentName"/> is <c>null</c>.</returns>
+        /// or <c>null</c> if <paramref name="argumentName"/> is <c>null</c>.</returns>
         public static string NormalizeTemplateArgumentName(string argumentName)
         {
             if (string.IsNullOrEmpty(argumentName)) return argumentName;
             return argumentName.Trim();
         }
 
+        /// <inheritdoc cref="NormalizeImageLinkArgumentName(string)"/>
+        /// <param name="argumentName">The argument name to be normalized. The node will be converted into its string representation.</param>
+        public static string NormalizeImageLinkArgumentName(Node argumentName)
+        {
+            if (argumentName == null) return null;
+            return NormalizeImageLinkArgumentName(argumentName.ToString());
+        }
+
         /// <summary>
-        /// Normalizes a page title expression. This is a simple version; it simply treats the part before
-        /// the first colon mark as namesapce name. For a more complete version of title normalization,
-        /// including title validation and namespace / interwiki prefix check,
-        /// see WikiLink class in WikiClientLibrary package.
+        /// Normalizes the argument name used in Image link syntax.
         /// </summary>
-        /// <param name="title">The title to be normalized.</param>
-        /// <returns>The normalized argument name, with leading and trailing whitespace removed,
-        /// underscore replaced with space, starting with an upper-case letter.
-        /// Or <c>null</c> if <see cref="title"/> is <c>null</c>.</returns>
+        /// <param name="argumentName">The argument name to be normalized.</param>
+        /// <returns>The normalized argument name, with leading and trailing whitespace removed, and first letter converted into lowercase
+        /// or <c>null</c> if <paramref name="argumentName"/> is <c>null</c>.</returns>
+        public static string NormalizeImageLinkArgumentName(string argumentName)
+        {
+            if (string.IsNullOrEmpty(argumentName)) return argumentName;
+            argumentName = argumentName.Trim();
+            if (argumentName.Length > 0 && char.IsUpper(argumentName, 0))
+            {
+                return char.ToLowerInvariant(argumentName[0]) + argumentName.Substring(1);
+            }
+            return argumentName;
+        }
+
+
+        /// <inheritdoc cref="NormalizeTitle(string)"/>
+        /// <param name="title">The title to be normalized. The node will be converted into its string representation.</param>
         public static string NormalizeTitle(Node title)
         {
             if (title == null) return null;
@@ -54,14 +69,14 @@ public static string NormalizeTitle(Node title)
 
         /// <summary>
         /// Normalizes a page title expression. This is a simple version; it simply treats the part before
-        /// the first colon mark as namesapce name. For a more complete version of title normalization,
+        /// the first colon mark as namespace name. For a more complete version of title normalization,
         /// including title validation and namespace / interwiki prefix check,
         /// see WikiLink class in WikiClientLibrary package.
         /// </summary>
         /// <param name="title">The title to be normalized.</param>
         /// <returns>The normalized argument name, with leading and trailing whitespace removed,
         /// underscore replaced with space, starting with an upper-case letter.
-        /// Or <c>null</c> if <see cref="title"/> is <c>null</c>.</returns>
+        /// Or <c>null</c> if <paramref name="title"/> is <c>null</c>.</returns>
         public static string NormalizeTitle(string title)
         {
             if (string.IsNullOrEmpty(title)) return title;

MwParserFromScratch/Nodes/Inline.cs

@@ -127,6 +127,134 @@ internal override void ToPlainTextCore(StringBuilder builder, NodePlainTextForma
         }
     }
 
+    /// <summary>
+    /// <c>[[File:Image.png|arg1|arg2|alt text]]</c>
+    /// </summary>
+    public class WikiImageLink : InlineNode
+    {
+        private Run _Target;
+
+        public WikiImageLink() : this(null)
+        {
+        }
+
+        public WikiImageLink(Run target)
+        {
+            Target = target;
+            Arguments = new WikiImageLinkArgumentCollection(this);
+        }
+        
+        /// <summary>
+        /// Title of the image.
+        /// </summary>
+        public Run Target
+        {
+            get { return _Target; }
+            set { Attach(ref _Target, value); }
+        }
+
+        /// <summary>
+        /// Image rendering arguments.
+        /// </summary>
+        public WikiImageLinkArgumentCollection Arguments { get; }
+
+        /// <inheritdoc />
+        public override IEnumerable<Node> EnumChildren()
+        {
+            if (_Target != null) yield return _Target;
+            foreach (var argument in Arguments) yield return argument;
+        }
+
+        /// <inheritdoc />
+        protected override Node CloneCore()
+        {
+            return new WikiImageLink(Target) { Arguments = { Arguments } };
+        }
+
+        /// <inheritdoc />
+        internal override void ToPlainTextCore(StringBuilder builder, NodePlainTextFormatter formatter)
+        {
+            var alt = Arguments.Alt;
+            if (alt != null) formatter(alt, builder);
+            var caption = Arguments.Caption;
+            // delimit alt text and caption with a space.
+            if (alt != null && caption != null) 
+                builder.Append(' ');
+            if (caption != null) formatter(caption, builder);
+        }
+    }
+
+    /// <summary>
+    /// An argument field of <see cref="WikiImageLink"/>.
+    /// </summary>
+    public class WikiImageLinkArgument : Node
+    {
+        private Wikitext _Name;
+        private Wikitext _Value;
+
+        public WikiImageLinkArgument() : this(null, null)
+        {
+        }
+
+        public WikiImageLinkArgument(Wikitext name, Wikitext value)
+        {
+            Name = name;
+            Value = value;
+        }
+
+        /// <summary>
+        /// Name of the argument.
+        /// </summary>
+        /// <value>Name of the argument, or <c>null</c> if the argument is anonymous.</value>
+        public Wikitext Name
+        {
+            get { return _Name; }
+            set { Attach(ref _Name, value); }
+        }
+
+        /// <summary>
+        /// Value of the argument.
+        /// </summary>
+        /// <value>Value of the argument. If the value is empty, it should be an empty <see cref="Wikitext"/> instance.</value>
+        public Wikitext Value
+        {
+            get { return _Value; }
+            set { Attach(ref _Value, value); }
+        }
+
+        /// <summary>
+        /// Enumerates the children of this node.
+        /// </summary>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public override IEnumerable<Node> EnumChildren()
+        {
+            if (_Name != null) yield return _Name;
+            if (_Value != null) yield return _Value;
+        }
+
+        protected override Node CloneCore()
+        {
+            var n = new TemplateArgument { Name = Name, Value = Value };
+            return n;
+        }
+
+        public override string ToString()
+        {
+            if (Name == null) return Value.ToString();
+            return Name + "=" + Value;
+        }
+
+        /// <summary>
+        /// Infrastructure. This function will always throw a <seealso cref="NotSupportedException"/>.
+        /// </summary>
+        /// <param name="builder"></param>
+        /// <param name="formatter"></param>
+        internal override void ToPlainTextCore(StringBuilder builder, NodePlainTextFormatter formatter)
+        {
+            throw new NotSupportedException();
+        }
+    }
+
     public class ExternalLink : InlineNode
     {
         private Run _Target;
@@ -400,7 +528,7 @@ internal override void ToPlainTextCore(StringBuilder builder, NodePlainTextForma
     }
 
     /// <summary>
-    /// {{{name|defalut}}}
+    /// {{{name|default}}}
     /// </summary>
     public class ArgumentReference : InlineNode
     {

MwParserFromScratch/Nodes/TemplateArgumentCollection.cs

@@ -55,15 +55,15 @@ private IEnumerable<KeyValuePair<string, TemplateArgument>> EnumNameArgumentPair
         /// The name of argument that will be tested. Can either be a name or 1-based index.
         /// Leading and trailing white spaces will be ignored.
         /// </param>
-        /// <exception cref="ArgumentNullException"><see cref="name"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>A matching <see cref="TemplateArgument"/> with the specified name, or <c>null</c> if no matching template is found.</returns>
         public TemplateArgument this[string name]
         {
             get
             {
                 if (name == null) throw new ArgumentNullException(nameof(name));
                 name = name.Trim();
-                // We want to choose the last matching arguments, if there're multiple choices.
+                // We want to choose the last matching arguments, if there are multiple choices.
                 return EnumNameArgumentPairs(true).FirstOrDefault(p => p.Key == name).Value;
             }
         }
@@ -72,12 +72,11 @@ public TemplateArgument this[string name]
         /// Gets an argument with the specified positional argument index.
         /// </summary>
         /// <param name="name">
-        /// The index of argument that will be tested. Note that this index will not nessarily greater
+        /// The index of argument that will be tested. Note that this index will not necessarily greater
         /// or equal than 1, because there might exist template argument with the name such as "-1", which
         /// can still be matched using this accessor.
         /// </param>
         /// <returns>A matching <see cref="TemplateArgument"/> with the specified name, or <c>null</c> if no matching template is found.</returns>
-        /// <exception cref="ArgumentNullException"><see cref="name"/> is <c>null</c>.</exception>
         public TemplateArgument this[int name] => this[name.ToString()];
 
         /// <summary>
@@ -87,7 +86,7 @@ public TemplateArgument this[string name]
         /// The name of argument that will be tested. Can either be a name or 1-based index.
         /// Leading and trailing white spaces will be ignored.
         /// </param>
-        /// <exception cref="ArgumentNullException"><see cref="name"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         public bool Contains(string name)
         {
             if (name == null) throw new ArgumentNullException(nameof(name));
@@ -99,7 +98,7 @@ public bool Contains(string name)
         /// Determines whether an argument with the specified positional argument index exists.
         /// </summary>
         /// <param name="name">
-        /// The index of argument that will be tested. Note that this index will not nessarily greater
+        /// The index of argument that will be tested. Note that this index will not necessarily greater
         /// or equal than 1, because there might exist template argument with the name such as "-1", which
         /// can still be matched using this accessor.
         /// </param>

MwParserFromScratch/Nodes/WikiImageLinkArgumentCollection.cs

@@ -0,0 +1,94 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace MwParserFromScratch.Nodes
+{
+    /// <summary>
+    /// Represents a collection of <see cref="WikiImageLinkArgument"/>
+    /// that can be accessed via argument names.
+    /// </summary>
+    public class WikiImageLinkArgumentCollection : NodeCollection<WikiImageLinkArgument>
+    {
+        /// <inheritdoc />
+        internal WikiImageLinkArgumentCollection(Node owner) : base(owner)
+        {
+        }
+
+        private IEnumerable<KeyValuePair<string, WikiImageLinkArgument>> EnumNameArgumentPairs(bool reverse)
+        {
+            return (reverse ? Reverse() : this).Select(arg =>
+                new KeyValuePair<string, WikiImageLinkArgument>(MwParserUtility.NormalizeImageLinkArgumentName(arg.Name), arg));
+        }
+
+        /// <summary>
+        /// Enumerates the normalized name-<see cref="WikiImageLinkArgument"/> pairs in the collection.
+        /// </summary>
+        /// <remarks>If there are arguments with duplicate names, they will nonetheless be included in the sequence.</remarks>
+        public IEnumerable<KeyValuePair<string, WikiImageLinkArgument>> EnumNameArgumentPairs()
+        {
+            return EnumNameArgumentPairs(false);
+        }
+
+        /// <summary>
+        /// Gets an named argument (<c>name=value</c>) with the specified name.
+        /// </summary>
+        /// <param name="name">
+        /// The name of argument that will be tested. Leading and trailing white spaces will be ignored. First letter will be normalized.
+        /// </param>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
+        /// <returns>A matching <see cref="WikiImageLinkArgument"/> with the specified name, or <c>null</c> if no matching template is found.</returns>
+        public WikiImageLinkArgument this[string name]
+        {
+            get
+            {
+                if (name == null) throw new ArgumentNullException(nameof(name));
+                name = MwParserUtility.NormalizeImageLinkArgumentName(name);
+                // We want to choose the last matching arguments, if there are multiple choices.
+                return EnumNameArgumentPairs(true).FirstOrDefault(p => p.Key == name).Value;
+            }
+        }
+
+        /// <summary>
+        /// Gets the value of <c>link=</c> option, if available.
+        /// </summary>
+        public Wikitext Link => this["link"]?.Value;
+
+        /// <summary>
+        /// Gets the value of <c>alt=</c> option, if available.
+        /// </summary>
+        public Wikitext Alt => this["alt"]?.Value;
+
+        /// <summary>
+        /// Gets the value of <c>page=</c> option, if available.
+        /// </summary>
+        public Wikitext Page => this["page"]?.Value;
+
+        /// <summary>
+        /// Gets the value of <c>class=</c> option, if available.
+        /// </summary>
+        public Wikitext ClassName => this["class"]?.Value;
+
+        /// <summary>
+        /// Gets the value of <c>lang=</c> option, if available.
+        /// </summary>
+        public Wikitext Lang => this["lang"]?.Value;
+
+        /// <summary>
+        /// Gets the image caption, if available.
+        /// </summary>
+        /// <remarks>The caption of the image is the last unnamed argument that is also after the last named argument.</remarks>
+        public Wikitext Caption
+        {
+            get
+            {
+                return EnumNameArgumentPairs(true)
+                    .TakeWhile(p => p.Key == null)
+                    .FirstOrDefault()
+                    .Value?.Value;
+            }
+        }
+
+    }
+}