Refs #5212 - Reinstate multifile stuff, with fixed unit tests.

This reverts commit 4fe9cd9, and fixes
tests.

Code/Mantid/Framework/API/inc/MantidAPI/MultipleFileProperty.h

@@ -1,6 +1,7 @@
 #ifndef MANTID_API_MULTIPLEFILEPROPERTY_H_
 #define MANTID_API_MULTIPLEFILEPROPERTY_H_
 
+#include "MantidKernel/Logger.h"
 #include "MantidKernel/PropertyWithValue.h"
 #include "MantidKernel/System.h"
 #include "MantidKernel/MultiFileNameParser.h"
@@ -12,8 +13,70 @@ namespace Mantid
 namespace API
 {
 
-  /** A property to allow a user to select multiple files to load.
+  /**
+    A property to allow a user to specify multiple files to load.
+
+    The current functionality is such that there are two basic forms of syntax.  For the puposes
+    of documentation we'll call these the "Long Form" and "Short Form".
+
+    ------------------------------------------------------------------------------------------------------
+    [A] Short Form
+
+        These strings are of the format "[dir][inst][under][runs][ext]" where:
+    
+        [dir]   (Optional) = The OS-specific file directory, e.g. "c:/data/"
+        [inst]  (Optional) = The instrument name, e.g. "IRS" or "PG3".
+        [under] (Optional) = Some instrument filenames require an underscore.
+        [runs]  (Required) = The run numbers, e.g. "0102, 0110-0115, 0120, 0130:0140:2"
+        [ext]   (Optional) = The file extension, e.g. ".raw"
+
+        For optional values, defaults or user settings are used where necessary.
     
+        For [runs], users specify lists and ranges of runs using comma, plus, minus and colon.  Some examples:
+
+        "TSC0001,0002"       = Runs 1 and 2 of the TOSCA instrument are to be loaded.
+        "0003+0004"          = Runs 3 and 4 of the default instrument are to be loaded and added together.
+        "0005:0009.raw"      = The raw files containing runs 5 to 9 of the default instrument are to be loaded.
+        "c:/data/0010-0014"  = The files in "c:/data/" containing runs 10 to 14 of the default instrument are 
+                               to be loaded and added together.
+        "IRS0020:0028:2.nxs" = The nexus files containing runs 20, 22, 24, 26 and 28 for IRIS are to be loaded.
+        "INST_0030-0038:3"   = Runs 30, 33, and 36 of INST are to be loaded and added together.
+
+    ------------------------------------------------------------------------------------------------------
+    [B] Long Form
+    
+        These strings are of the format "[[short_form][operator]]...[short_form]" where:
+
+        [short_form] = [dir][inst][under][runs][ext], which is the "Short Form" outlined above.
+        [operator]   = Either a comma or a plus.
+
+        Some examples:
+
+        "TSC0001,TSC0002+0003"        = Runs 1, 2 and 3 of the TOSCA instrument should be loaded, but 2 and 3 
+                                        are added together.
+        "TSC0005+TSC0006,TSC0007.raw" = Runs 5 and 6 as well as the raw file containing run 7 of the TOSCA 
+                                        instrument should be loaded, but 5 and 6 are added together.
+
+    ------------------------------------------------------------------------------------------------------
+    NOTES: 
+    
+    [1] Presently, we disallow more complex algebra such as "TSC0005,0006+TSC0007". In such a case it is 
+        ambiguous whether or not the user wishes to just add run 7 to 6, or add run 7 to both 5 and 6.
+    
+    [2] The "Short Form" is parsed by the Kernel::MultiFileNameParsing::Parser class, whereas this class is 
+        responsible for splitting up the Long Form.
+
+    [3] The functionality of this class is such that all strings are stored only after being converted to
+        the Long Form, and all filenames are fully resolved.  For example "0005,0006+0007" is stored as
+        "[dir][inst][under]0005[ext],[dir][inst][under]0006[ext]+[dir][inst][under]0007[ext]".
+
+    [4] The default functionality of this Property can be changed to emulate a simple FileProperty - to do
+        this, the user must change the properties file.  Disabling multi file loading in this way will allow
+        users to use "," and "+" in their filenames, and in this case we use the dummy "" delimiters to call
+        toValue and toString.
+
+    ------------------------------------------------------------------------------------------------------
+
     Copyright © 2011 ISIS Rutherford Appleton Laboratory & NScD Oak Ridge National Laboratory
 
     This file is part of Mantid.
@@ -45,15 +108,14 @@ namespace API
     /// 'Virtual copy constructor
     virtual MultipleFileProperty* clone() const { return new MultipleFileProperty(*this); }
 
-    /// Overridden setValue method
+    /// Overridden functions to accomodate std::vector<std::vector<std::string>>> structure of this property.
     virtual std::string setValue(const std::string & propValue);
+    virtual std::string value() const;
+    virtual std::string getDefault() const;
 
     /// @return the vector of suggested extensions. For use in GUIs showing files.
     std::set<std::string> getExts() const
     { return std::set<std::string>(m_exts.begin(), m_exts.end()); }
-    /// @return the vector of ws names.  For use by loading algorithm to name multiple workspaces, especially summed workspaces.
-    std::vector<std::vector<unsigned int> > getRuns() const
-    { return m_parser.runs(); }
 
     /// Returns the main file extension that's used 
     std::string getDefaultExt() const {return m_defaultExt;}
@@ -65,12 +127,17 @@ namespace API
     static std::vector<std::string> flattenFileNames(const std::vector<std::vector<std::string> > & fileNames);
 
   private:
+    /// Whether or not the user has turned on multifile loading.
+    bool m_multiFileLoadingEnabled;
+
     /// Suggested extensions
     std::vector<std::string> m_exts;
     /// Parser used to parse multi-file strings.
     Kernel::MultiFileNameParsing::Parser m_parser;
     ///The default file extension associated with the type of file this property will handle
     std::string m_defaultExt;
+    /// Reference to the logger class
+    Kernel::Logger& g_log;
   };