Split the wrap module into state and stack_cleaner modules

The wrap module used to contain two very different classes: state, which
is the lightweight wrapper over the Lua C API, and stack_cleaner, which
is our own creation to deal with inconsistencies in the Lua stack.  These
classes belong in different modules, so this is exactly what this change
does.

This change was r6 in Subversion.

Atffile

@@ -4,4 +4,5 @@ prop: test-suite = lutok
 
 tp: exceptions_test
 tp: operations_test
-tp: wrap_test
+tp: stack_cleaner_test
+tp: state_test

Kyuafile

@@ -4,4 +4,5 @@ test_suite("lutok")
 
 atf_test_program{name="exceptions_test"}
 atf_test_program{name="operations_test"}
-atf_test_program{name="wrap_test"}
+atf_test_program{name="stack_cleaner_test"}
+atf_test_program{name="state_test"}

Makefile.am

@@ -41,20 +41,23 @@ LUTOK_LIBS = liblutok.la $(LUA_LIBS)
 pkginclude_HEADERS  = exceptions.hpp
 pkginclude_HEADERS += noncopyable.hpp
 pkginclude_HEADERS += operations.hpp
+pkginclude_HEADERS += stack_cleaner.hpp
+pkginclude_HEADERS += state.hpp
+pkginclude_HEADERS += state.ipp
 pkginclude_HEADERS += test_utils.hpp
-pkginclude_HEADERS += wrap.hpp
-pkginclude_HEADERS += wrap.ipp
 
 lib_LTLIBRARIES = liblutok.la
 liblutok_la_SOURCES  = exceptions.cpp
 liblutok_la_SOURCES += exceptions.hpp
 liblutok_la_SOURCES += noncopyable.hpp
 liblutok_la_SOURCES += operations.cpp
 liblutok_la_SOURCES += operations.hpp
+liblutok_la_SOURCES += stack_cleaner.cpp
+liblutok_la_SOURCES += stack_cleaner.hpp
+liblutok_la_SOURCES += state.cpp
+liblutok_la_SOURCES += state.hpp
+liblutok_la_SOURCES += state.ipp
 liblutok_la_SOURCES += test_utils.hpp
-liblutok_la_SOURCES += wrap.cpp
-liblutok_la_SOURCES += wrap.hpp
-liblutok_la_SOURCES += wrap.ipp
 liblutok_la_CPPFLAGS = -I$(srcdir)/include $(LUA_CFLAGS)
 liblutok_la_LDFLAGS = -version-info 0:0:0
 liblutok_la_LIBADD = $(LUA_LIBS)
@@ -88,10 +91,15 @@ operations_test_SOURCES = operations_test.cpp test_utils.hpp
 operations_test_CXXFLAGS = $(ATF_CXX_CFLAGS) $(LUTOK_CFLAGS)
 operations_test_LDADD = $(ATF_CXX_LIBS) $(LUTOK_LIBS)
 
-tests_PROGRAMS += wrap_test
-wrap_test_SOURCES = test_utils.hpp wrap_test.cpp
-wrap_test_CXXFLAGS = $(ATF_CXX_CFLAGS) $(LUTOK_CFLAGS)
-wrap_test_LDADD = $(ATF_CXX_LIBS) $(LUTOK_LIBS)
+tests_PROGRAMS += stack_cleaner_test
+stack_cleaner_test_SOURCES = stack_cleaner_test.cpp test_utils.hpp
+stack_cleaner_test_CXXFLAGS = $(ATF_CXX_CFLAGS) $(LUTOK_CFLAGS)
+stack_cleaner_test_LDADD = $(ATF_CXX_LIBS) $(LUTOK_LIBS)
+
+tests_PROGRAMS += state_test
+state_test_SOURCES = state_test.cpp test_utils.hpp
+state_test_CXXFLAGS = $(ATF_CXX_CFLAGS) $(LUTOK_CFLAGS)
+state_test_LDADD = $(ATF_CXX_LIBS) $(LUTOK_LIBS)
 
 check-local: check-kyua
 PHONY_TARGETS += check-kyua

configure.ac

@@ -37,7 +37,7 @@ AC_CONFIG_AUX_DIR([admin])
 AC_CONFIG_FILES([Doxyfile Makefile])
 AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_MACRO_DIR([m4])
-AC_CONFIG_SRCDIR([wrap.hpp])
+AC_CONFIG_SRCDIR([state.hpp])
 
 
 AM_INIT_AUTOMAKE([1.9 check-news foreign subdir-objects -Wall])

exceptions.cpp

@@ -31,7 +31,7 @@
 #include <lua.hpp>
 
 #include "exceptions.hpp"
-#include "wrap.hpp"
+#include "state.hpp"
 
 
 /// Constructs a new error with a plain-text message.

include/lutok/Makefile.am.inc

@@ -29,4 +29,5 @@
 EXTRA_DIST+=    include/lutok/exceptions.hpp
 EXTRA_DIST+=    include/lutok/noncopyable.hpp
 EXTRA_DIST+=    include/lutok/operations.hpp
-EXTRA_DIST+=    include/lutok/wrap.hpp
+EXTRA_DIST+=    include/lutok/stack_cleaner.hpp
+EXTRA_DIST+=    include/lutok/state.hpp

include/lutok/stack_cleaner.hpp

@@ -0,0 +1 @@
+#include "../../stack_cleaner.hpp"

include/lutok/state.hpp

@@ -0,0 +1 @@
+#include "../../state.hpp"

operations.cpp

@@ -30,7 +30,8 @@
 
 #include "exceptions.hpp"
 #include "operations.hpp"
-#include "wrap.hpp"
+#include "stack_cleaner.hpp"
+#include "state.hpp"
 
 
 /// Creates a module: i.e. a table with a set of methods in it.

operations.hpp

@@ -36,7 +36,7 @@
 #include <string>
 #include <vector>
 
-#include <lutok/wrap.hpp>
+#include <lutok/state.hpp>
 
 namespace lutok {
 

operations_test.cpp

@@ -32,8 +32,8 @@
 
 #include "exceptions.hpp"
 #include "operations.hpp"
+#include "state.ipp"
 #include "test_utils.hpp"
-#include "wrap.ipp"
 
 
 namespace {

stack_cleaner.cpp

@@ -0,0 +1,91 @@
+// Copyright 2011 Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+// * Redistributions of source code must retain the above copyright
+//   notice, this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above copyright
+//   notice, this list of conditions and the following disclaimer in the
+//   documentation and/or other materials provided with the distribution.
+// * Neither the name of Google Inc. nor the names of its contributors
+//   may be used to endorse or promote products derived from this software
+//   without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#include <cassert>
+#include <cstring>
+
+#include "stack_cleaner.hpp"
+#include "state.ipp"
+
+
+/// Internal implementation for lutok::stack_cleaner.
+struct lutok::stack_cleaner::impl {
+    /// Reference to the Lua state this stack_cleaner refers to.
+    state& state_ref;
+
+    /// The depth of the Lua stack to be restored.
+    unsigned int original_depth;
+
+    /// Constructor.
+    ///
+    /// \param state_ref_ Reference to the Lua state.
+    /// \param original_depth_ The depth of the Lua stack.
+    impl(state& state_ref_, const unsigned int original_depth_) :
+        state_ref(state_ref_),
+        original_depth(original_depth_)
+    {
+    }
+};
+
+
+/// Creates a new stack cleaner.
+///
+/// This gathers the current height of the stack so that extra elements can be
+/// popped during destruction.
+///
+/// \param state_ The Lua state.
+lutok::stack_cleaner::stack_cleaner(state& state_) :
+    _pimpl(new impl(state_, state_.get_top()))
+{
+}
+
+
+/// Pops any values from the stack not known at construction time.
+///
+/// \pre The current height of the stack must be equal or greater to the height
+/// of the stack when this object was instantiated.
+lutok::stack_cleaner::~stack_cleaner(void)
+{
+    const unsigned int current_depth = _pimpl->state_ref.get_top();
+    assert(current_depth >= _pimpl->original_depth);
+    const unsigned int diff = current_depth - _pimpl->original_depth;
+    if (diff > 0)
+        _pimpl->state_ref.pop(diff);
+}
+
+
+/// Forgets about any elements currently in the stack.
+///
+/// This allows a function to return values on the stack because all the
+/// elements that are currently in the stack will not be touched during
+/// destruction when the function is called.
+void
+lutok::stack_cleaner::forget(void)
+{
+    _pimpl->original_depth = _pimpl->state_ref.get_top();
+}

stack_cleaner.hpp

@@ -0,0 +1,86 @@
+// Copyright 2011 Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+// * Redistributions of source code must retain the above copyright
+//   notice, this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above copyright
+//   notice, this list of conditions and the following disclaimer in the
+//   documentation and/or other materials provided with the distribution.
+// * Neither the name of Google Inc. nor the names of its contributors
+//   may be used to endorse or promote products derived from this software
+//   without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+/// \file stack_cleaner.hpp
+/// Provides the stack_cleaner class.
+
+#if !defined(LUTOK_STACK_CLEANER_HPP)
+#define LUTOK_STACK_CLEANER_HPP
+
+#include <memory>
+
+#include <lutok/noncopyable.hpp>
+#include <lutok/state.hpp>
+
+namespace lutok {
+
+
+/// A RAII model for values on the Lua stack.
+///
+/// At creation time, the object records the current depth of the Lua stack and,
+/// during destruction, restores the recorded depth by popping as many stack
+/// entries as required.  As a corollary, the stack can only grow during the
+/// lifetime of a stack_cleaner object (or shrink, but cannot become shorter
+/// than the depth recorded at creation time).
+///
+/// Use this class as follows:
+///
+/// state s;
+/// {
+///     stack_cleaner cleaner1(s);
+///     s.push_integer(3);
+///     s.push_integer(5);
+///     ... do stuff here ...
+///     for (...) {
+///         stack_cleaner cleaner2(s);
+///         s.load_string("...");
+///         s.pcall(0, 1, 0);
+///         ... do stuff here ...
+///     }
+///     // cleaner2 destroyed; the result of pcall is gone.
+/// }
+/// // cleaner1 destroyed; the integers 3 and 5 are gone.
+///
+/// You must give a name to the instantiated objects even if they cannot be
+/// accessed later.  Otherwise, the instance will be destroyed right away and
+/// will not have the desired effect.
+class stack_cleaner : noncopyable {
+    struct impl;
+    std::auto_ptr< impl > _pimpl;
+
+public:
+    stack_cleaner(state&);
+    ~stack_cleaner(void);
+
+    void forget(void);
+};
+
+
+}  // namespace lutok
+
+#endif  // !defined(LUTOK_STACK_CLEANER_HPP)