Ticket #713: Properties.d

/*******************************************************************************

        copyright:      Copyright (c) 2004 Kris Bell. All rights reserved

        license:        BSD style: $(LICENSE)

        version:        Initial release: May 2004
                        Oct 2007: change to use a Map interface to store
                        properties.

        author:         Kris, Steven Schveighoffer

*******************************************************************************/

module tango.text.Properties;

private import  tango.io.Buffer,
                tango.io.FilePath,
                tango.io.FileConst,
                tango.io.FileConduit;

private import  Text = tango.text.Util;

private import  tango.text.stream.LineIterator;

/*******************************************************************************

        Provides an interface for using properties.  This is mainly used by
        the Properties object to load/save properties to a stream.

*******************************************************************************/

interface PropertyMap(T)
{
        /***********************************************************************

                Add a property.  If a property already exists with that name,
                the value is replaced.

        ***********************************************************************/

        void add(T[] name, T[] value);

        /***********************************************************************

                Remove a property.  If the property with the given name
                doesn't exist, this function does nothing.

        ***********************************************************************/

        void remove(T[] name);

        /***********************************************************************

                Index operator.  This is how you get a property value given
                the name.  If the name is not in the map, this returns null.

        ***********************************************************************/

        T[] opIndex(T[] name);

        /***********************************************************************

                Add a value to the property map, using the index operator.  E.g.:
                ---
                properties["file"] = "test.txt";
                ---

                Calling this is equivalent to add(name, value);

                This returns value.

        ***********************************************************************/

        T[] opIndexAssign(T[] value, T[] name);

        /***********************************************************************

                Used to iterate over the keys and values in the map.

        ***********************************************************************/

        int opApply(int delegate(ref T[] name, ref T[] value) dg);

        /***********************************************************************

                Remove all properties from the map.

        ***********************************************************************/

        void clear();

        /***********************************************************************

                Returns true if the named property exists in the map

        ***********************************************************************/

        bool contains(T[] name);
}

/*******************************************************************************

        Provides load facilities for a properties file. That is, a file
        or other medium containing lines of text with a name=value layout.

*******************************************************************************/

class Properties(T)
{
        alias PropertyMap!(T) Map;

        /***********************************************************************

                Load properties from the named file, and pass each of them
                to the provided delegate.

        ***********************************************************************/

        static void load (FilePath path, Map properties)
        {
                auto fc = new FileConduit (path);
                scope (exit)
                       fc.close;

                load (fc, properties);
        }

        /***********************************************************************

                Load properties from the provided buffer, and pass them to
                the specified Map object.

                We use an iterator to sweep text lines, and extract lValue
                and rValue pairs from each one, The expected file format is
                as follows:

                ---
                x = y
                abc = 123
                x.y.z = this is a single property

                # this is a comment line
                ---

        ***********************************************************************/

        static void load (InputStream stream, Map properties)
        {
                foreach (line; new LineIterator!(T) (stream))
                        {
                        auto text = Text.trim (line);

                        // comments require '#' as the first non-whitespace char
                        if (text.length && (text[0] != '#'))
                           {
                           // find the '=' char
                           auto i = Text.locate (text, '=');

                           // ignore if not found ...
                           if (i < text.length)
                                   // Note that we dup here so further lines
                                   // read from the file do not corrupt the
                                   // keys/values.
                                   properties.add(Text.trim(text[0 .. i]).dup, Text.trim(text[i+1 .. $]).dup);
                           }
                        }
        }

        /***********************************************************************

                Write properties to the provided filepath

        ***********************************************************************/

        static void save (FilePath path, Map properties)
        {
                auto fc = new FileConduit (path, FileConduit.WriteCreate);
                scope (exit)
                       fc.close;
                save (fc, properties);
        }

        /***********************************************************************

                Write properties to the provided conduit

        ***********************************************************************/

        static void save (IConduit conduit, Map properties)
        {
                save (new Buffer(conduit), properties).flush;
        }

        /***********************************************************************

                Write properties to the provided buffer

        ***********************************************************************/

        static IBuffer save (IBuffer emit, Map properties)
        {
                const T[] equals = " = ";
                version (Win32)
                         const T[] NL = "\r\n";
                version (Posix)
                         const T[] NL = "\n";

                foreach (key, value; properties)
                         emit (key) (equals) (value) (NL);
                return emit;
        }
}


debug (Properties)
{
        import tango.io.Buffer;
        import tango.io.Console;
        import tango.text.SimplePropertyMap;

        void main() 
        {
                auto aa = new SimplePropertyMap!(char);
                aa ["foo"] = "something";
                aa ["bar"] = "something else";
                aa ["wumpus"] = "";

                // write Hash map to a buffer; could use a file
                auto props = new Properties!(char);
                auto buffer = new Buffer (256);
                props.save (buffer, aa);

                // reset and repopulate hash map from the buffer
                aa.clear();
                props.load (buffer, aa);

                // display result
                foreach (name, value; aa)
                         Cout (name) (" = ") (value).newline;
        }
}