add: 添加os库的demo,添加os的API文档

demo/os_date_time/main.lua

@@ -0,0 +1,42 @@
+
+-- LuaTools需要PROJECT和VERSION这两个信息
+PROJECT = "osdemo"
+VERSION = "1.0.0"
+
+log.info("main", PROJECT, VERSION)
+
+-- sys库是标配
+_G.sys = require("sys")
+
+sys.taskInit(function()
+    sys.wait(1000)
+
+    -- 获取本地时间字符串
+    log.info("本地时间字符串", os.date())
+    -- 获取UTC时间字符串
+    log.info("UTC时间字符串", os.date("!%c"))
+
+    -- 格式化本地时间字符串
+    log.info("本地时间字符串", os.date("%Y-%m-%d %H:%M:%S"))
+    -- 格式化UTC时间字符串
+    log.info("UTC时间字符串", os.date("!%Y-%m-%d %H:%M:%S"))
+
+    -- 格式化时间字符串
+    log.info("自定义时间的字符串", os.date("!%Y-%m-%d %H:%M:%S", os.time({year=2000, mon=1, day=1, hour=0, min=0, sec=0})))
+    
+    -- 获取本地时间的table
+    log.info("本地时间字符串", json.encode(os.date("*t")))
+    -- 获取UTC时间的table
+    log.info("UTC时间字符串",  json.encode(os.date("!*t")))
+
+
+    -- 时间戳, 但lua下的精度只能到秒
+    log.info("UTC时间戳", os.time())
+    log.info("自定义时间戳", os.time({year=2000, mon=1, day=1, hour=0, min=0, sec=0}))
+end)
+
+
+-- 用户代码已结束---------------------------------------------
+-- 结尾总是这一句
+sys.run()
+-- sys.run()之后后面不要加任何语句!!!!!

lua/src/loslib.c

@@ -4,6 +4,19 @@
 ** See Copyright Notice in lua.h
 */
 
+/*
+@module  os
+@summary os操作
+@version 1.0
+@date    2020.07.03
+@tag LUAT_CONF_BSP
+@demo    os_date_time
+@usage
+-- os模块是lua原生模块, 这份文档是为了方便阐述实际使用中的常见问题
+
+-- 原生文档请查阅 https://wiki.luatos.com/_static/lua53doc/manual.html#6.9
+*/
+
 #define loslib_c
 #define LUA_LIB
 
@@ -152,12 +165,38 @@ static int os_execute (lua_State *L) {
 }
 #endif
 
+/*
+移除文件
+@api os.remove(path)
+@string 待移除的文件完整路径
+@return bool 成功返回true,其他情况返回nil
+@return string 失败时返回原因字符串
+@usage
+-- 删除根目录下的某个文件
+os.remove("/1.txt")
+-- 注意, 线刷时的文件, 一般在 /luadb 目录, 这个目录下的文件是只读的
+-- 也就是无法执行 os.remove("/luadb/xxx.bin")
+*/
 static int os_remove (lua_State *L) {
   const char *filename = luaL_checkstring(L, 1);
   return luaL_fileresult(L, luat_fs_remove(filename) == 0, filename);
 }
 
-
+/*
+文件重命名
+@api os.rename(old_path, new_path)
+@string 源文件完整路径
+@string 目标文件完整路径
+@return bool 成功返回true,其他情况返回nil
+@return string 失败时返回原因字符串
+@usage
+-- 注意, 只有在相同文件系统下的文件可以重命名
+-- 例如:
+os.rename("/1.txt", "/2.txt")
+-- 不同文件系统, 或者源文件系统是只读的, 则无法执行
+--os.rename("/luadb/1.txt", "/luadb/2.txt")
+--os.rename("/luadb/1.txt", "/2.txt")
+*/
 static int os_rename (lua_State *L) {
   const char *fromname = luaL_checkstring(L, 1);
   const char *toname = luaL_checkstring(L, 2);
@@ -182,7 +221,15 @@ static int os_getenv (lua_State *L) {
 }
 #endif
 
-
+/*
+返回程序使用的按秒计 CPU 时间的近似值
+@api os.clock()
+@return 时间戳
+@usage
+-- 不推荐使用本API
+-- 如需要获取 时间戳, 请使用 os.time()
+-- 如需获取系统运行时长, 请使用 mcu.ticks()
+*/
 static int os_clock (lua_State *L) {
   lua_pushnumber(L, ((lua_Number)clock())/(lua_Number)CLOCKS_PER_SEC);
   return 1;
@@ -286,6 +333,34 @@ static const char *checkoption (lua_State *L, const char *conv,
 #include "luat_rtc.h"
 #endif
 
+/*
+日期函数
+@api os.date(fmt, time)
+@string 格式化字符串,可以是nil
+@table 日期时间的table
+@return table/string 根据fmt的不同,返回值不同
+@usage
+
+-- 值得注意的几点:
+-- 1. 若需要UTC时间, fmt的第一个字符写"!"
+-- 2. fmt的格式化遵循 C 函数 strftime, 可以查阅 https://developer.aliyun.com/article/320480
+
+-- 获取本地时间字符串
+log.info("本地时间字符串", os.date())
+-- 获取UTC时间字符串
+log.info("UTC时间字符串", os.date("!%c"))
+-- 格式化本地时间字符串
+log.info("本地时间字符串", os.date("%Y-%m-%d %H:%M:%S"))
+-- 格式化UTC时间字符串
+log.info("UTC时间字符串", os.date("!%Y-%m-%d %H:%M:%S"))
+-- 格式化时间字符串
+log.info("自定义时间的字符串", os.date("!%Y-%m-%d %H:%M:%S", os.time({year=2000, mon=1, day=1, hour=0, min=0, sec=0})))
+
+-- 获取本地时间的table
+log.info("本地时间字符串", json.encode(os.date("*t")))
+-- 获取UTC时间的table
+log.info("UTC时间字符串",  json.encode(os.date("!*t")))
+*/
 static int os_date (lua_State *L) {
   size_t slen;
   const char *s = luaL_optlstring(L, 1, "%c", &slen);
@@ -333,7 +408,17 @@ static int os_date (lua_State *L) {
   return 1;
 }
 
-
+/*
+时间戳函数
+@api os.time(mytime)
+@table 日期时间的table
+@return 时间戳
+@usage
+-- 注意注意, 这个函数返回的是UTC时间戳
+-- 时间戳, 但lua下的精度只能到秒
+log.info("UTC时间戳", os.time())
+log.info("自定义时间戳", os.time({year=2000, mon=1, day=1, hour=0, min=0, sec=0}))
+*/
 static int os_time (lua_State *L) {
   time_t t;
   if (lua_isnoneornil(L, 1))  /* called without args? */
@@ -370,6 +455,13 @@ static int os_time (lua_State *L) {
   return 1;
 }
 
+/*
+时间差值
+@api os.difftime(timeA, timeB)
+@int 时间A,数值类型
+@int 时间B,数值类型
+@return int 时间差值
+*/
 static int os_difftime (lua_State *L) {
   time_t t1 = l_checktime(L, 1);
   time_t t2 = l_checktime(L, 2);