zaaReloaded2/zaaReloaded2/Controller/Comments/ItemComment.cs

/* ParameterComment.cs
 * part of zaaReloaded2
 * 
 * Copyright 2015-2017 Daniel Kraus
 * 
 * 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.
 */
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;

namespace zaaReloaded2.Controller.Comments
{
    /// <summary>
    /// Represents an optional comment for a laboratory item.
    /// The zaaReloaded2.Controller.Elements.Items class can
    /// parse these optional comment strings which may be used
    /// to prompt users to enter target ranges etc.
    /// </summary>
    /// <example>
    /// TAC "(Zielspiegel: &lt;8-10&gt; µg/l)"
    /// </example>
    /// <remarks>
    /// In the example, the tacrolimus trough level TAC carries a comment about the
    /// recommended range. The comment must be enclosed in quotes in order for it
    /// to be recognized. The quotes will be stripped. The angle brackets denote
    /// a place holder that will be replaced by the comment that is set in the
    /// RequestParameterComment's event args. The text between the angle brackets
    /// ("8-10") is an optional default value. One could also just use 'empty'
    /// brackets ("&lt;&gt;").
    /// </remarks>
    public class ItemComment
    {
        #region Factory

        /// <summary>
        /// Creates a new ItemComment object from a definition string.
        /// </summary>
        /// <param name="definitionString">String that complies
        /// with the definition pattern (item "optional prefix &lt;optional
        /// default value&gt; optioal suffix").</param>
        public static ItemComment FromDefinitionString(string definitionString)
        {
            Match match = _definition.Match(definitionString);
            if (match.Success)
            {
                return new ItemComment(
                    definitionString,
                    match.Groups["item"].Value.Trim(),
                    match.Groups["prefix"].Value,
                    match.Groups["value"].Value,
                    match.Groups["suffix"].Value);
            }
            else
            {
                return null;
            }
        }


        #endregion

        #region Properties

        /// <summary>
        /// Gets or sets the item name that this comment is for.
        /// </summary>
        public string Item { get; set; }

        /// <summary>
        /// Prefix of this comment, e.g. "(target trough level: "
        /// </summary>
        public string Prefix { get; set; }

        /// <summary>
        /// Value of this comment; String.Empty represents a
        /// cancelled comment.
        /// </summary>
        public string Value { get; set; }

        /// <summary>
        /// Suffix of this comment, e.g. " µg/l)"
        /// </summary>
        public string Suffix { get; set; }

        /// <summary>
        /// Gets the original definition string that this ItemComment
        /// was created from.
        /// </summary>
        public string Definition { get; private set; }

        /// <summary>
        /// Gets or sets whether this comment has been cancelled.mo
        /// </summary>
        public bool IsCancelled { get; set; }

        #endregion

        #region Event

        /// <summary>
        /// Event that is raised when the comment value needs to be
        /// filled in by someone or something.
        /// </summary>
        public event EventHandler<ItemCommentEventArgs> FillInComment;

        #endregion

        #region Constructors

        public ItemComment()
        {
            Item = String.Empty;
            Prefix = String.Empty;
            Value = String.Empty;
            Suffix = String.Empty;
        }

        public ItemComment(string item, string prefix, string value, string suffix)
            : this()
        {
            Item = item;
            Prefix = prefix;
            Value = value;
            Suffix = suffix;
        }

        public ItemComment(string definition, string item, string prefix, string value, string suffix)
            : this(item, prefix, value, suffix)
        {
            Definition = definition;
        }

        #endregion

        #region Methods

        /// <summary>
        /// Builds the comment string from the prefix, the value, and
        /// the suffix. Raises the FillInComment event to get the value
        /// first. If the value is an empty string, the entire comment
        /// string will be an empty string.
        /// </summary>
        /// <returns>Comment string with filled-in value, or String.Empty
        /// if the value is an empty string.</returns>
        public string BuildComment()
        {
            OnFillInComment();

            string value = Value;
            if (String.IsNullOrEmpty(value))
            {
                // If the comment was not cancelled and an empty
                // value was deliberately entered, return an
                // empty string.
                if (!IsCancelled)
                {
                    return String.Empty;
                }
                // If the comment was cancelled and the default
                // value is an empty string, insert a prompt
                // to manually enter the comment.
                else
                {
                    value = Properties.Settings.Default.ManualCommentPrompt;
                }
            }

            if (!IsCancelled)
            {
                return Prefix + value + Suffix;
            }
            else
            {
                return Prefix + "<highlight>" + value + "</highlight>" + Suffix;
            }
        }

        #endregion

        #region Private methods

        /// <summary>
        /// Raises the FillInComment event.
        /// </summary>
        protected virtual void OnFillInComment()
        {
            if (_isFilledIn) return;

            EventHandler<ItemCommentEventArgs> h = FillInComment;
            if (h != null)
            {
                _isFilledIn = true;
                h(this, new ItemCommentEventArgs(this));
            }
        }

        #endregion

        #region Fields

        bool _isFilledIn;
        static readonly Regex _definition =
            new Regex(@"(?<item>[^""]+)""(?<prefix>[^<]+)?<(?<value>[^>]*)>(?<suffix>[^""]+)?""");

        #endregion
    }
}