0.1.18

Author: huangxiangyao

CMakeLists.txt

@@ -11,7 +11,7 @@ cmake_minimum_required(VERSION 3.23)
 # (3) Sync the download url in `README.md`.
 ###############################################################################
 project(cmdout_sln
-	VERSION 0.1.17
+	VERSION 0.1.18
 )
 set(CMDOUT_VERSION ${PROJECT_VERSION})
 
@@ -71,7 +71,7 @@ if (CMDOUT_ENABLE_DOXYGEN)
 	set(DOXYGEN_SHOW_INCLUDE_FILES YES)
 	set(DOXYGEN_BINARY_TOC YES)
 	set(DOXYGEN_TOC_EXPAND YES)
-	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "index.md")
+	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "docs/index.md")
 	message(DEBUG "PROJECT_SOURCE_DIR: ${PROJECT_SOURCE_DIR}")
 	message(DEBUG "CMAKE_CURRENT_SOURCE_DIR: ${CMAKE_CURRENT_SOURCE_DIR}")
 	doxygen_add_docs(cmdout_doxygen

README.md

@@ -1,5 +1,5 @@
 # myvas::cmdout
-The `myvas::cmdout` library provides facilities for executing shell commands and get their output before time runs out.
+The cmdout library provides facilities for executing shell commands and get their output before time runs out.
 
 ## Todo list
 - By now, it works on Linux; but it should work on more platforms.
@@ -9,22 +9,22 @@ The `myvas::cmdout` library provides facilities for executing shell commands and
 ```
 include(FetchContent)
 FetchContent_Declare(cmdout
-	URL https://github.com/myvas/cmdout/archive/refs/tags/0.1.13.tar.gz
+	URL https://github.com/myvas/cmdout/archive/refs/tags/0.1.18.tar.gz
 	DOWNLOAD_EXTRACT_TIMESTAMP ON
 )
 FetchContent_MakeAvailable(cmdout)
 
-target_link_libraries(<your_target> PRIVATE myvas::cmdout)
+target_link_libraries(<your_target> PRIVATE cmdout)
 ```
 ### Include the header file
 ```
-#include <cmdout.hpp>
+#include <cmdout/cmdout.hpp>
 ```
 
 ### Examples
 C++17 on GNU/Linux Debian 11 (bullseye)
 ```
-#include <cmdout_ext.hpp>
+#include <cmdout/cmdout_ext.hpp>
 #include <cassert>
 //...
 int main() {

benchmarks/CMakeLists.txt

@@ -16,4 +16,4 @@ include(cmake/benchmark.cmake)
 ###########################
 add_executable(benchmarks "src/benchmarks.cpp")
 cmdout_enable_warnings(benchmarks)
-target_link_libraries(benchmarks PRIVATE myvas::cmdout benchmark::benchmark)
+target_link_libraries(benchmarks PRIVATE cmdout benchmark::benchmark)

benchmarks/src/benchmarks.cpp

@@ -5,7 +5,7 @@
  * @file  benchmarks.cpp
  * @brief benchmarks for myvas::cmdout.
  */
-#include "cmdout.hpp"
+#include <cmdout/cmdout.hpp>
 
 #include <iostream>
 

cmdout/include/cmdout/cmdout.hpp

@@ -15,6 +15,9 @@
 
 namespace myvas {
 
+/**
+ * @brief Default timeout 10 seconds.
+ */
 const int64_t CMDOUT_TIMEOUT_MILLISECONDS = 10 * 1000;
 
 /**
@@ -32,7 +35,7 @@ class cmdout
 	/**
 	 * @brief Gets the exit code after exec returned.
 	 *
-	 * The value is one of the following:
+	 * @return The value is one of the following:
 	 * - If cmd is empty, then a nonzero value if a shell is available, or 0 if
 	 * no shell is available.
 	 * - If a child process in cmd could not be created, or its status could not
@@ -43,23 +46,45 @@ class cmdout
 	 * last command in cmd.
 	 */
 	int status() const;
+
+	/**
+	 * @brief Sets the status value.
+	 */
 	cmdout& status(int);
 
 	/**
 	 * @brief Gets the content of stdout (file descriptor 1).
 	 */
 	std::string out() const;
+	/**
+	 * @brief Sets the out string.
+	 */
 	cmdout& out(const std::string&);
 
 	/**
 	 * @brief Gets the shell command line.
 	 */
 	std::string cmd() const;
+	/**
+	 * @brief Sets the cmd string.
+	 */
 	cmdout& cmd(const std::string&);
 
+	/**
+	 * @brief Gets the timeout duration in milliseconds.
+	 */
 	std::chrono::milliseconds timeout() const;
+	/**
+	 * @brief Gets the timeout in milliseconds.
+	 */
 	int64_t timeout_ms() const;
+	/**
+	 * @brief Sets the timeout.
+	 */
 	cmdout& timeout(std::chrono::milliseconds);
+	/**
+	 * @brief Sets the timeout value.
+	 */
 	cmdout& timeout(int64_t);
 
 	/**
@@ -73,9 +98,6 @@ class cmdout
 	 *
 	 * @param cmd The cmd argument is a pointer to a null-terminated string
 	 * containing a shell command.
-	 *
-	 * @return The return value is a cmdout object, in which wraps the status code
-	 * and output string of the shell command.
 	 */
 	explicit cmdout(const std::string& cmd);
 
@@ -88,9 +110,6 @@ class cmdout
 	 * containing a shell command.
 	 *
 	 * @param timeout_ms timeout in milliseconds. (If zero, defaults to 10 seconds)
-	 *
-	 * @return The return value is a cmdout object, in which wraps the status code
-	 * and output string of the shell command.
 	 */
 	explicit cmdout(const std::string& cmd, int64_t timeout_ms);
 
@@ -102,44 +121,76 @@ class cmdout
 	 * containing a shell command.
 	 *
 	 * @param timeout timeout duration. (If zero, defaults to 10 seconds)
-	 *
-	 * @return The return value is a cmdout object, in which wraps the status code
-	 * and output string of the shell command.
 	 */
 	explicit cmdout(const std::string& cmd, std::chrono::milliseconds timeout);
 
 	/**
 	 * @brief Constructs an output.
 	 *
+	 * @param cmd The cmd argument is a pointer to a null-terminated string containing a shell command.
+	 * @param timeout timeout duration. (If zero, defaults to 10 seconds)
 	 * @param status EXIT_SUCCESS, EXIT_FAILURE or errno
+	 * @param out output string
+	 *
 	 * @see cerrno and cstdlib.
 	 */
 	explicit cmdout(const std::string& cmd, std::chrono::milliseconds timeout, int status, const std::string& out);
+	/**
+	 * @brief Constructs an output.
+	 *
+	 * @param cmd The cmd argument is a pointer to a null-terminated string containing a shell command.
+	 * @param timeout_ms timeout. (If zero, defaults to 10 seconds)
+	 * @param status EXIT_SUCCESS, EXIT_FAILURE or errno
+	 * @param out output string
+	 *
+	 * @see cerrno and cstdlib.
+	 */
 	explicit cmdout(const std::string& cmd, int64_t timeout_ms, int status, const std::string& out);
 
+	/**
+	 * @brief Copy constructor.
+	 */
 	cmdout(const cmdout&);
+	/**
+	 * @brief Copy assignment.
+	 */
 	cmdout& operator=(const cmdout&);
+	/**
+	 * @brief Move constructor.
+	 */
 	cmdout(cmdout&&);
+	/**
+	 * @brief Move assignment.
+	 */
 	cmdout& operator=(cmdout&&);
 
+	/**
+	 * @brief Destructor.
+	 */
 	virtual ~cmdout();
 
 	/**
 	 * @brief Execute a specified shell command with arguments initialized in this class.
+	 *
+	 * @return The return value is a cmdout reference, in which wraps the status code
+	 * and output string of the shell command.
 	 */
 	cmdout& exec();
 };
 
 /**
  * @brief Execute a shell command specified in cmd.
  *
+ * @param cmd The cmd argument is a pointer to a null-terminated string containing a shell command.
+ *
  * @return Returns a cmdout object (without timeout)
  */
 cmdout system(const std::string& cmd);
 
 /**
  * @brief Execute a shell command specified in cmd and get its output before time runs out.
  *
+ * @param cmd The cmd argument is a pointer to a null-terminated string containing a shell command.
  * @param timeout timeout duration, defaults to 10 seconds
  *
  * @return Returns a cmdout object
@@ -149,6 +200,7 @@ cmdout system_timeout(const std::string& cmd, std::chrono::milliseconds timeout)
 /**
  * @brief Execute a shell command specified in cmd and get its output before time runs out.
  *
+ * @param cmd The cmd argument is a pointer to a null-terminated string containing a shell command.
  * @param timeout_ms timeout in milliseconds, defaults to 10 seconds
  *
  * @return Returns a cmdout object

cmdout/src/cmdout.cpp

@@ -5,7 +5,7 @@
  * @file  cmdout.cpp
  * @brief Implementation of class myvas::cmdout.
  */
-#include "cmdout.hpp"
+#include <cmdout/cmdout.hpp>
 
 namespace myvas {
 

cmdout/src/system.cpp

@@ -5,7 +5,7 @@
  * @file  system.cpp
  * @brief Implementation of function myvas::system().
  */
-#include "cmdout.hpp"
+#include <cmdout/cmdout.hpp>
 
 #include <array>
 #include <future>

examples/CMakeLists.txt

@@ -17,8 +17,8 @@ target_sources(example_std_system_out PRIVATE "src/example_std_system_out.cpp")
 
 add_executable(example_myvas_system)
 target_sources(example_myvas_system PRIVATE "src/example_myvas_system.cpp")
-target_link_libraries(example_myvas_system PRIVATE myvas::cmdout)
+target_link_libraries(example_myvas_system PRIVATE cmdout)
 
 add_executable(example_myvas_cmdout)
 target_sources(example_myvas_cmdout PRIVATE "src/example_myvas_cmdout.cpp")
-target_link_libraries(example_myvas_cmdout PRIVATE myvas::cmdout)
+target_link_libraries(example_myvas_cmdout PRIVATE cmdout)

examples/src/example_myvas_cmdout.cpp

@@ -5,7 +5,7 @@
  * @file  example_myvas_cmdout.cpp
  * @brief example for class myvas::cmdout.
  */
-#include <cmdout_ext.hpp>
+#include <cmdout/cmdout_ext.hpp>
 
 #include <iostream>
 #include <cassert>

examples/src/example_myvas_system.cpp

@@ -5,7 +5,7 @@
  * @file  example_myvas_system.cpp
  * @brief example for function myvas::system().
  */
-#include <cmdout_ext.hpp>
+#include <cmdout/cmdout_ext.hpp>
 
 #include <iostream>
 #include <cassert>

tests/CMakeLists.txt

@@ -37,5 +37,5 @@ endfunction()
 # target tests
 ###########################
 if(CMDOUT_BUILD_TESTS OR CMDOUT_BUILD_ALL)
-    cmdout_prepare_test(tests myvas::cmdout)
+    cmdout_prepare_test(tests cmdout)
 endif()

tests/src/test_myvas_cmdout.cpp

@@ -5,9 +5,10 @@
  * @file  test_myvas_cmdout.cpp
  * @brief Unit test for class myvas::cmdout.
  */
-#include <catch2/catch_test_macros.hpp>
 
-#include <cmdout.hpp>
+#include <cmdout/cmdout.hpp>
+
+#include <catch2/catch_test_macros.hpp>
 
 TEST_CASE("myvas::cmdout") {
 	SECTION("with default arguments") {

tests/src/test_myvas_system.cpp

@@ -5,9 +5,10 @@
  * @file  test_myvas_system.cpp
  * @brief Unit test for function myvas::system().
  */
-#include <catch2/catch_test_macros.hpp>
 
-#include <cmdout.hpp>
+#include <cmdout/cmdout.hpp>
+
+#include <catch2/catch_test_macros.hpp>
 
 TEST_CASE("myvas::system") {
 	SECTION("with exit 0") {