using System.Collections.Generic;
using System.Linq;
using System.Xml.Linq;

namespace Developpez.Dotnet.Xml
{
    /// <summary>
    /// Fournit des méthodes d'extension pour la manipulation de documents XML
    /// </summary>
    public static class XmlExtensions
    {
        /// <summary>
        /// Renvoie la valeur d'un élément XML s'il n'est pas null, ou null si l'élément est null.
        /// </summary>
        /// <param name="element">L'élément dont on veut obtenir la valeur</param>
        /// <returns>La valeur de l'élément s'il n'est pas null, ou null si l'élément est null.</returns>
        public static string SafeValue(this XElement element)
        {
            return element.SafeValue(null);
        }

        /// <summary>
        /// Renvoie la valeur d'un élément XML s'il n'est pas null, ou la valeur par défaut spécifiée si l'élément est null.
        /// </summary>
        /// <param name="element">L'élément dont on veut obtenir la valeur</param>
        /// <param name="defaultValue">La valeur à renvoyer si l'élément est null</param>
        /// <returns>La valeur de l'élément s'il n'est pas null, ou la valeur par défaut spécifiée si l'élément est null.</returns>
        public static string SafeValue(this XElement element, string defaultValue)
        {
            return element != null ? element.Value : defaultValue;
        }

        /// <summary>
        /// Renvoie la valeur d'un attribut XML s'il n'est pas null, ou null si l'attribut est null.
        /// </summary>
        /// <param name="attribute">L'attribut dont on veut obtenir la valeur</param>
        /// <returns>La valeur de l'attribut s'il n'est pas null, ou null si l'attribut est null.</returns>
        public static string SafeValue(this XAttribute attribute)
        {
            return attribute.SafeValue(null);
        }

        /// <summary>
        /// Renvoie la valeur d'un attribut XML s'il n'est pas null, ou la valeur par défaut spécifiée si l'attribut est null.
        /// </summary>
        /// <param name="attribute">L'attribut dont on veut obtenir la valeur</param>
        /// <param name="defaultValue">La valeur à renvoyer si l'attribut est null</param>
        /// <returns>La valeur de l'attribut s'il n'est pas null, ou la valeur par défaut spécifiée si l'attribut est null.</returns>
        public static string SafeValue(this XAttribute attribute, string defaultValue)
        {
            return attribute != null ? attribute.Value : defaultValue;
        }

        /// <summary>
        /// Renvoie le premier élément enfant du conteneur avec le XName spécifié, ou null si le conteneur est null.
        /// </summary>
        /// <param name="container">Le conteneur dans lequel chercher l'élément</param>
        /// <param name="name">Le nom de l'élément recherché</param>
        /// <returns>XElement qui correspond au XName spécifié, ou null si l'élément n'existe pas ou si le conteneur est null.</returns>
        public static XElement SafeElement(this XContainer container, XName name)
        {
            return container != null ? container.Element(name) : null;
        }

        /// <summary>
        /// Renvoie une collection des éléments enfants de ce conteneur, ou une séquence vide si le conteneur est null.
        /// </summary>
        /// <param name="container">Le conteneur dont on veut obtenir les éléments enfants</param>
        /// <returns>Une séquence de XElement contenant les éléments enfants de ce conteneur, ou une séquence vide si le conteneur est null.</returns>
        public static IEnumerable<XElement> SafeElements(this XContainer container)
        {
            return container != null ? container.Elements() : Enumerable.Empty<XElement>();
        }

        /// <summary>
        /// Renvoie une collection des éléments enfants de ce conteneur avec le XName spécifié, ou une séquence vide si le conteneur est null.
        /// </summary>
        /// <param name="container">Le conteneur dont on veut obtenir les éléments enfants</param>
        /// <param name="name">Le nom des éléments recherchés</param>
        /// <returns>Une séquence de XElement contenant les éléments enfants de ce conteneur, avec le XName spécifié, ou une séquence vide si le conteneur est null.</returns>
        public static IEnumerable<XElement> SafeElements(this XContainer container, XName name)
        {
            return container != null ? container.Elements(name) : Enumerable.Empty<XElement>();
        }

        /// <summary>
        /// Renvoie l'attribut avec le XName spécifié, ou null si l'élement est null.
        /// </summary>
        /// <param name="element">L'élément pour lequel on veut obtenir l'attribut</param>
        /// <param name="name">Le nom de l'attribut recherché</param>
        /// <returns>XAttribute qui a le XName spécifié, ou null si l'attribut n'existe pas ou si l'élément est null.</returns>
        public static XAttribute SafeAttribute(this XElement element, XName name)
        {
            return element != null ? element.Attribute(name) : null;
        }

        /// <summary>
        /// Renvoie une collection des attributs de cet élément, ou une séquence vide si l'élément est null.
        /// </summary>
        /// <param name="element">L'élément dont on veut obtenir les attributs</param>
        /// <returns>Une séquence de XAttribute contenant les attributs de cet élément, ou une séquence vide si l'élément est null.</returns>
        public static IEnumerable<XAttribute> SafeAttributes(this XElement element)
        {
            return element != null ? element.Attributes() : Enumerable.Empty<XAttribute>();
        }

        /// <summary>
        /// Renvoie une des attributs avec le XName spécifié, ou une séquence vide si l'élément est null.
        /// </summary>
        /// <param name="element">L'élément dont on veut obtenir les attributs</param>
        /// <param name="name">L'élément dont on veut obtenir les attributs</param>
        /// <returns>Une séquence de XAttribute contenant les attributs avec le XName spécifié, ou une séquence vide si l'élément est null.</returns>
        public static IEnumerable<XAttribute> SafeAttributes(this XElement element, XName name)
        {
            return element != null ? element.Attributes(name) : Enumerable.Empty<XAttribute>();
        }
    }
}