--- a/TODO	Sat Feb 21 12:43:51 2009 +0200
+++ b/TODO	Sat Feb 21 16:10:28 2009 +0200
@@ -1,5 +1,4 @@
 
 Verify refcounts of lm objects. Need a decent test script for that.
 Some additional lua functions?
-Path node/message method to traverse path and return nil or node
 

--- a/lm.c	Sat Feb 21 12:43:51 2009 +0200
+++ b/lm.c	Sat Feb 21 16:10:28 2009 +0200
@@ -9,6 +9,15 @@
 #include "lm_ssl.h"
 #include "lm_connection.h"
 
+/// Some common principles:
+/// Most methods can be used in two way:
+/// * to get value they are invoked without their last argument. Returned value is either a value or pair of nil and error message.
+/// * to set value they are invoked with last arg (value) specified. Returned value in most cases is an object, on which operation is performed (to allow chain-initialization).
+/// Every object have pointer method to return pointer (lightuserdata) to underlying C loudmouth structure.
+/// Every module have a bless method to convert given pointer (lightuserdata) to corresponding lua object.
+/// Every unique C loudmouth object have only one corresponding lua object. Thus, result of "lm.message.bless ( message1:pointer () )" will be exactly message1 object (not its copy).
+/// Where message handler object is expected, message handler function can be specified. However, you can unregister handler only if you have message handler object.
+
 int luaopen_loudmouth (lua_State *L)
 {
 	lua_pushstring (L, LLM_OBJREGISTRY); // 1 registry key

--- a/lm_message.c	Sat Feb 21 12:43:51 2009 +0200
+++ b/lm_message.c	Sat Feb 21 16:10:28 2009 +0200
@@ -11,6 +11,11 @@
 /// lm.message
 /// Module, representing individual message.
 /// Message have a type and optionally a sub type.
+/// Message have a set common methods with message node,
+/// these are next, prev, children, parent, value, child,
+/// find_child, attribute, raw, xml and path. They just save
+/// you typing :node() each time and save memory for
+/// one node object.
 
 /// message type
 /// Message type (root tag type).
@@ -154,6 +159,7 @@
 	{ "attribute",  llm_message_node_attribute  },
 	{ "raw",        llm_message_node_raw        },
 	{ "xml",        llm_message_node_xml        },
+	{ "path",       llm_message_node_path       },
 	// End common methods
 	{ "pointer",    llm_message_pointer         },
 	{ "__gc",       llm_message_gc              },

--- a/lm_message_node.c	Sat Feb 21 12:43:51 2009 +0200
+++ b/lm_message_node.c	Sat Feb 21 16:10:28 2009 +0200
@@ -191,6 +191,27 @@
 	return 1;
 }
 
+/// message_node:path
+/// Returns node with specified path to it.
+/// If any element in a path cannot be found, it returns nil.
+/// A: string (node name), ...
+/// R: lm message node object or nil
+int llm_message_node_path (lua_State *L)
+{
+	LmMessageNode *node = luaL_checkLmMessageNode (L, 1);
+	int i = 1;
+	while (i++ < lua_gettop (L)) {
+		node = lm_message_node_get_child (node, luaL_checkstring (L, i));
+		if (node == NULL) {
+			lua_pushnil (L);
+			return 1;
+		}
+	}
+	llm_message_node_bless (L, node);
+	// XXX lm_message_node_unref (child);
+	return 1;
+}
+
 /// message_node:pointer
 /// Returns pointer to underlying C structure.
 /// R: lightuserdata
@@ -226,6 +247,7 @@
 	{ "attribute",  llm_message_node_attribute  },
 	{ "raw",        llm_message_node_raw        },
 	{ "xml",        llm_message_node_xml        },
+	{ "path",       llm_message_node_path       },
 	{ "pointer",    llm_message_node_pointer    },
 	{ "__gc",       llm_message_node_gc         },
 	{ NULL,         NULL                        },

--- a/lm_message_node.h	Sat Feb 21 12:43:51 2009 +0200
+++ b/lm_message_node.h	Sat Feb 21 16:10:28 2009 +0200
@@ -15,6 +15,7 @@
 int llm_message_node_raw (lua_State *L);
 int llm_message_node_attribute (lua_State *L);
 int llm_message_node_xml (lua_State *L);
+int llm_message_node_path (lua_State *L);
 
 int luaopen_lm_message_node (lua_State *L);