Add CLI configuration documentation

This patch allows a module to define its configuration in XML in source, such
that it can be parsed by the XML documentation engine. Documentation is
generated in a two-pass approach:

1. The documentation is first generated from the XML pulled from the source
2. The documentation is then enhanced by the registration of configuration
   options that use the configuration framework

This patch include configuration documentation for the following modules:
 * chan_motif
 * res_xmpp
 * app_confbridge
 * app_skel
 * udptl

Two new CLI commands have been added:
 * config show help - show configuration help by module, category, and item
 * xmldoc dump - dump the in-memory representation of the XML documentation to
   a new XML file.

Review: https://reviewboard.asterisk.org/r/2278
Review: https://reviewboard.asterisk.org/r/2058

patches:
  on review 2058 uploaded by twilson



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@381527 65c4cc65-6c06-0410-ace0-fbb531ad65f3

4 files changed, 77 insertions, 0 deletions

diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h
index cded90ef7..7e1ef13ec 100644
--- a/include/asterisk/_private.h
+++ b/include/asterisk/_private.h
@@ -49,6 +49,7 @@ int ast_ssl_init(void);                 /*!< Provided by ssl.c */
 int ast_test_init(void);            /*!< Provided by test.c */
 int ast_msg_init(void);             /*!< Provided by message.c */
 void ast_msg_shutdown(void);        /*!< Provided by message.c */
+int aco_init(void);             /*!< Provided by config_options.c */
 
 /*!
  * \brief Reload asterisk modules.
diff --git a/include/asterisk/config_options.h b/include/asterisk/config_options.h
index 1b0beb206..64d8d5089 100644
--- a/include/asterisk/config_options.h
+++ b/include/asterisk/config_options.h
@@ -109,6 +109,7 @@ typedef int (*aco_matchvalue_func)(const char *text);
 struct aco_type {
 	/* common stuff */
 	enum aco_type_t type;   /*!< Whether this is a global or item type */
+	const char *name;       /*!< The name of this type (must match XML documentation) */
 	const char *category;   /*!< A regular expression for matching categories to be allowed or denied */
 	const char *matchfield; /*!< An option name to match for this type (i.e. a 'type'-like column) */
 	const char *matchvalue; /*!< The value of the option to require for matching (i.e. 'peer' for type= in sip.conf) */
@@ -202,6 +203,14 @@ static struct aco_info name = { \
 	__VA_ARGS__ \
 };
 
+#define CONFIG_INFO_CORE(mod, name, arr, alloc, ...) \
+static struct aco_info name = { \
+	.module = mod, \
+	.global_obj = &arr, \
+	.snapshot_alloc = alloc, \
+	__VA_ARGS__ \
+};
+
 /*! \brief Initialize an aco_info structure
  * \note aco_info_destroy must be called if this succeeds
  * \param info The address of an aco_info struct to initialize
diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h
index ddfcc25d9..063e8c0b3 100644
--- a/include/asterisk/xml.h
+++ b/include/asterisk/xml.h
@@ -23,6 +23,7 @@
 
 struct ast_xml_node;
 struct ast_xml_doc;
+struct ast_xml_xpath_results;
 
 /*!
  * \brief Initialize the XML library implementation.
@@ -207,6 +208,44 @@ struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node);
  * \brief Dump the specified document to a file. */
 int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc);
 
+/*!
+ * \brief Free the XPath results
+ * \param results The XPath results object to dispose of
+ *
+ * \since 12
+ */
+void ast_xml_xpath_results_free(struct ast_xml_xpath_results *results);
+
+/*!
+ * \brief Return the number of results from an XPath query
+ * \param results The XPath results object to count
+ * \retval The number of results in the XPath object
+ *
+ * \since 12
+ */
+int ast_xml_xpath_num_results(struct ast_xml_xpath_results *results);
+
+/*!
+ * \brief Return the first result node of an XPath query
+ * \param results The XPath results object to get the first result from
+ * \retval The first result in the XPath object on success
+ * \retval NULL on error
+ *
+ * \since 12
+ */
+struct ast_xml_node *ast_xml_xpath_get_first_result(struct ast_xml_xpath_results *results);
+
+/*!
+ * \brief Execute an XPath query on an XML document
+ * \param doc The XML document to query
+ * \param xpath_str The XPath query string to execute on the document
+ * \retval An object containing the results of the XPath query on success
+ * \retval NULL on failure
+ *
+ * \since 12
+ */
+struct ast_xml_xpath_results *ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str);
+
 /* Features using ast_xml_ */
 #ifdef HAVE_LIBXML2
 #define AST_XML_DOCS
diff --git a/include/asterisk/xmldoc.h b/include/asterisk/xmldoc.h
index 9bf647612..c09f693c8 100644
--- a/include/asterisk/xmldoc.h
+++ b/include/asterisk/xmldoc.h
@@ -35,6 +35,7 @@ enum ast_doc_src {
 #ifdef AST_XML_DOCS
 
 struct ao2_container;
+struct ast_xml_node;
 
 /*! \brief Struct that contains the XML documentation for a particular item.  Note
  * that this is an ao2 ref counted object.
@@ -61,11 +62,27 @@ struct ast_xml_doc_item {
 		AST_STRING_FIELD(name);
 		/*! The type of the item */
 		AST_STRING_FIELD(type);
+		/*! Reference to another field */
+		AST_STRING_FIELD(ref);
 	);
+	/*! The node that this item was created from. Note that the life time of
+	 * the node is not tied to the lifetime of this object.
+	 */
+	struct ast_xml_node *node;
 	/*! The next XML documentation item that matches the same name/item type */
 	struct ast_xml_doc_item *next;
 };
 
+/*! \brief Execute an XPath query on the loaded XML documentation
+ * \param query The XPath query string to execute
+ * \param ... Variable printf style format arguments
+ * \retval An XPath results object on success
+ * \retval NULL if no match found
+ *
+ * \since 12
+ */
+struct ast_xml_xpath_results *__attribute__((format(printf, 1, 2))) ast_xmldoc_query(const char *fmt, ...);
+
 /*!
  *  \brief Get the syntax for a specified application or function.
  *  \param type Application, Function or AGI ?
@@ -138,6 +155,17 @@ char *ast_xmldoc_build_description(const char *type, const char *name, const cha
  */
 struct ao2_container *ast_xmldoc_build_documentation(const char *type);
 
+/*!
+ *  \brief Regenerate the documentation for a particular item
+ *  \param item The documentation item to regenerate
+ *
+ *  \retval -1 on error
+ *  \retval 0 on success
+ *
+ *  \since 12
+ */
+int ast_xmldoc_regenerate_doc_item(struct ast_xml_doc_item *item);
+
 #endif /* AST_XML_DOCS */
 
 #endif /* _ASTERISK_XMLDOC_H */