更改 shell读写接口

README.md

@@ -1,6 +1,6 @@
-# letter shell 3.0
+# letter shell 3.x
 
-![version](https://img.shields.io/badge/version-3.0.6-brightgreen.svg)
+![version](https://img.shields.io/badge/version-3.1.0-brightgreen.svg)
 ![standard](https://img.shields.io/badge/standard-c99-brightgreen.svg)
 ![build](https://img.shields.io/badge/build-2020.11.29-brightgreen.svg)
 ![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)
@@ -9,7 +9,7 @@
 
 ![shell_info.png](doc/img/shell_info.png)
 
-- [letter shell 3.0](#letter-shell-30)
+- [letter shell 3.x](#letter-shell-3x)
   - [简介](#简介)
   - [功能](#功能)
   - [移植说明](#移植说明)
@@ -33,11 +33,11 @@
 
 ## 简介
 
-[letter shell 3.0](https://github.com/NevermindZZT/letter-shell/tree/shell3.0)是一个C语言编写的，可以嵌入在程序中的嵌入式shell，主要面向嵌入式设备，以C语言函数为运行单位，可以通过命令行调用，运行程序中的函数
+[letter shell](https://github.com/NevermindZZT/letter-shell)是一个C语言编写的，可以嵌入在程序中的嵌入式shell，主要面向嵌入式设备，以C语言函数为运行单位，可以通过命令行调用，运行程序中的函数
 
-相对2.x版本，letter shell 3.0增加了用户管理，权限管理，后续会增加对文件系统的支持
+相对2.x版本，letter shell 3.x增加了用户管理，权限管理，以及对文件系统的初步支持
 
-此外3.0版本修改了命令格式和定义，2.x版本的工程需要经过简单的修改才能完成迁移
+此外3.x版本修改了命令格式和定义，2.x版本的工程需要经过简单的修改才能完成迁移
 
 若只需要使用基础功能，可以使用[letter shell 2.x](https://github.com/NevermindZZT/letter-shell/tree/shell2.x)版本
 
@@ -66,19 +66,22 @@
     /**
      * @brief shell读取数据函数原型
      *
-     * @param char shell读取的字符
+     * @param data shell读取的字符
+     * @param len 请求读取的字符数量
      *
-     * @return char 0 读取数据成功
+     * @return unsigned short 实际读取到的字符数量
-     * @return char -1 读取数据失败
      */
-    typedef signed char (*shellRead)(char *);
+    typedef unsigned short (*shellRead)(char *data, unsigned short len);
 
     /**
      * @brief shell写数据函数原型
      *
-     * @param const char 需写的字符
+     * @param data 需写的字符数据
+     * @param len 需要写入的字符数
+     *
+     * @return unsigned short 实际写入的字符数量
      */
-    typedef void (*shellWrite)(const char);
+    typedef unsigned short (*shellWrite)(const char *data, unsigned short len);
     ```
 
 3. 申请一片缓冲区
@@ -149,7 +152,7 @@
 
 ### 函数定义
 
-letter shell 3.0同时支持两种形式的函数定义方式，形如main函数定义的`func(int argc, char *agrv[])`以及形如普通C函数的定义`func(int i, char *str, ...)`，两种函数定义方式适用于不同的场景
+letter shell 3.x同时支持两种形式的函数定义方式，形如main函数定义的`func(int argc, char *agrv[])`以及形如普通C函数的定义`func(int i, char *str, ...)`，两种函数定义方式适用于不同的场景
 
 #### main函数形式
 
@@ -196,7 +199,7 @@ input int: 666, char: A, string: hello world
 
 ### 变量使用
 
-letter shell 3.0支持导出变量，通过命令行查看，设置以及使用变量的值
+letter shell 3.x支持导出变量，通过命令行查看，设置以及使用变量的值
 
 - 导出变量
 
@@ -239,7 +242,7 @@ letter shell 3.0支持导出变量，通过命令行查看，设置以及使用
 
 - 使用变量
 
-    letter shell 3.0的变量可以在命令中作为参数传递，对于需要传递结构体引用到命令中的场景特别适用，使用`$`+变量名的方式传递
+    letter shell 3.x的变量可以在命令中作为参数传递，对于需要传递结构体引用到命令中的场景特别适用，使用`$`+变量名的方式传递
 
     ```sh
     letter:/$ shellPrint $shell "hello world\r\n"
@@ -260,7 +263,7 @@ letter shell支持通过函数地址直接执行函数，可以方便执行那
 
 ## 命令定义
 
-letter shell 3.0将可执行的函数命令定义，用户定义，按键定义以及变量定义统一归为命令定义，使用相同的结构储存，查找和执行
+letter shell 3.x将可执行的函数命令定义，用户定义，按键定义以及变量定义统一归为命令定义，使用相同的结构储存，查找和执行
 
 ### 定义方式
 
@@ -297,7 +300,7 @@ letter shell 支持使用命令导出方式和命令表方式进行命令的添
 
 ### 定义宏说明
 
-letter shell 3.0对可执行命令，按键，用户以及变量分别提供了一个宏，用于进行命令定义
+letter shell 3.x对可执行命令，按键，用户以及变量分别提供了一个宏，用于进行命令定义
 
 1. 可执行命令定义
 
@@ -431,7 +434,7 @@ union
 
 ## 代理函数和代理参数解析
 
-letter shell 3.0原生支持将整数，字符，字符串参数，以及在某些情况下的浮点参数直接传递给执行命令的函数，一般情况下，这几种参数类型完全可以满足调试需要，然而在某些情况下，用户确实需要传递其他类型的参数，此时，可以选择将命令定义成main函数形式，使用字符串传递参数，然后自行对参数进行解析，除此之外，letter shell还提供了代理函数的机制，可以对任意类型的参数进行自定义解析
+letter shell 3.x原生支持将整数，字符，字符串参数，以及在某些情况下的浮点参数直接传递给执行命令的函数，一般情况下，这几种参数类型完全可以满足调试需要，然而在某些情况下，用户确实需要传递其他类型的参数，此时，可以选择将命令定义成main函数形式，使用字符串传递参数，然后自行对参数进行解析，除此之外，letter shell还提供了代理函数的机制，可以对任意类型的参数进行自定义解析
 
 关于代理函数的实现原理和具体使用示例，可以参考[letter-shell代理函数解析](https://nevermindzzt.github.io/2020/04/17/letter-shell%E4%BB%A3%E7%90%86%E5%87%BD%E6%95%B0%E8%A7%A3%E6%9E%90/)
 
@@ -453,7 +456,7 @@ p1, SHELL_PARAM_FLOAT(p2), p3, SHELL_PARAM_FLOAT(p4));
 
 ## 权限系统说明
 
-letter shell 3.0的权限管理同用户定义紧密相关，letter shell 3.0使用8个bit位表示命令权限，当用户和命令的权限按位与为真，或者命令权限为0时，表示该用户拥有此命令的权限，可以调用改命令
+letter shell 3.x的权限管理同用户定义紧密相关，letter shell 3.x使用8个bit位表示命令权限，当用户和命令的权限按位与为真，或者命令权限为0时，表示该用户拥有此命令的权限，可以调用改命令
 
 ## 伴生对象
 
@@ -475,7 +478,7 @@ letter shell 3.0.4版本新增了尾行模式，适用于需要在shell所使用
 
 ## 命令遍历工具
 
-letter shell 3.0提供了一个用于遍历工程中命令导出的工具，位于tools/shellTools.py，需要python3环境运行，可以列出工程中，所有使用`SHELL_EXPORT_XXX`导出的命令名，以及位置，结合VS Code可以直接进行跳转
+letter shell 3.x提供了一个用于遍历工程中命令导出的工具，位于tools/shellTools.py，需要python3环境运行，可以列出工程中，所有使用`SHELL_EXPORT_XXX`导出的命令名，以及位置，结合VS Code可以直接进行跳转
 
 ```sh
 python shellTools.py project

demo/esp-idf/shell_cfg.h

@@ -87,7 +87,7 @@
 
 /**
  * @brief shell命令参数最大数量
- *        包含命令名在内，超过8个参数并且使用了参数自动转换的情况下，需要修改源码
+ *        包含命令名在内，超过16个参数并且使用了参数自动转换的情况下，需要修改源码
  */
 #define     SHELL_PARAMETER_MAX_NUMBER  8
 

demo/stm32-freertos/shell_cfg.h

@@ -87,7 +87,7 @@
 
 /**
  * @brief shell命令参数最大数量
- *        包含命令名在内，超过8个参数并且使用了参数自动转换的情况下，需要修改源码
+ *        包含命令名在内，超过16个参数并且使用了参数自动转换的情况下，需要修改源码
  */
 #define     SHELL_PARAMETER_MAX_NUMBER  8
 

demo/x86-gcc/shell_port.c

@@ -27,9 +27,14 @@ char shellPathBuffer[512] = "/";
  * 
  * @param data 数据
  */
-void userShellWrite(char data)
+unsigned short userShellWrite(char *data, unsigned short len)
 {
-    putchar(data);
+    unsigned short length = len;
+    while (length--)
+    {
+        putchar(*data++);
+    }
+    return len;
 }
 
 /**
@@ -38,14 +43,18 @@ void userShellWrite(char data)
  * @param data 数据
  * @return char 状态
  */
-signed char userShellRead(char *data)
+unsigned short userShellRead(char *data, unsigned short len)
 {
+    unsigned short length = len;
     system("stty -echo");
     system("stty -icanon");
-    *data = getchar();
+    while (length--)
+    {
+        *data++ = getchar();
+    }
     system("stty icanon");
     system("stty echo");
-    return 0;
+    return len;
 }
 
 /**
@@ -138,7 +147,7 @@ void shellKeyTest(void)
     SHELL_ASSERT(shell && shell->read, return);
     while (1)
     {
-        if (shell->read(&data) == 0)
+        if (shell->read(&data, 1) == 1)
         {
             if (data == '\n' || data == '\r')
             {

src/shell.c

@@ -260,7 +260,7 @@ Shell* shellGetCurrent(void)
  */
 static void shellWriteByte(Shell *shell, const char data)
 {
-    shell->write(data);
+    shell->write(&data, 1);
 }
 
 
@@ -275,13 +275,13 @@ static void shellWriteByte(Shell *shell, const char data)
 unsigned short shellWriteString(Shell *shell, const char *string)
 {
     unsigned short count = 0;
+    char *p = string;
     SHELL_ASSERT(shell->write, return 0);
-    while(*string)
+    while(*p++)
     {
-        shell->write(*string ++);
         count ++;
     }
-    return count;
+    return shell->write(string, count);
 }
 
 
@@ -296,22 +296,24 @@ unsigned short shellWriteString(Shell *shell, const char *string)
 static unsigned short shellWriteCommandDesc(Shell *shell, const char *string)
 {
     unsigned short count = 0;
+    char *p = string;
     SHELL_ASSERT(shell->write, return 0);
-    while(*string
+    while (*p && *p != '\r' && *p != '\n')
-        && *string != '\r'
-        && *string != '\n'
-        && count < 36)
     {
-        shell->write(*string ++);
+        p++;
-        count ++;
+        count++;
-        if (count >= 36 && *(string + 1))
+    }
+    
+    if (count > 36)
     {
-            shell->write('.');
+        shell->write(string, 36);
-            shell->write('.');
+        shell->write("...", 3);
-            shell->write('.');
     }
+    else
+    {
+        shell->write(string, count);
     }
-    return count;
+    return count > 36 ? 36 : 39;
 }
 
 
@@ -385,9 +387,9 @@ void shellScan(Shell *shell, char *fmt, ...)
     if (shell->read)
     {
         do {
-            if (shell->read(&buffer[index]) == 0)
+            if (shell->read(&buffer[index], 1) == 1)
             {
-                shell->write(buffer[index]);
+                shell->write(buffer[index], 1);
                 index++;
             }
         } while (buffer[index -1] != '\r' && buffer[index -1] != '\n' && index < SHELL_SCAN_BUFFER);
@@ -1742,10 +1744,8 @@ void shellWriteEndLine(Shell *shell, char *buffer, int len)
     {
         shellWriteString(shell, shellText[SHELL_TEXT_CLEAR_LINE]);
     }
-    while (len --)
+    shell->write(buffer, len);
-    {
+
-        shell->write(*buffer++);
-    }
     if (!shell->status.isActive)
     {
         shellWriteCommandLine(shell, 0);
@@ -1754,7 +1754,7 @@ void shellWriteEndLine(Shell *shell, char *buffer, int len)
             shellWriteString(shell, shell->parser.buffer);
             for (short i = 0; i < shell->parser.length - shell->parser.cursor; i++)
             {
-                shell->write('\b');
+                shell->write('\b', 1);
             }
         }
     }
@@ -1776,7 +1776,7 @@ void shellTask(void *param)
     while(1)
     {
 #endif
-        if (shell->read && shell->read(&data) == 0)
+        if (shell->read && shell->read(&data, 1) == 1)
         {
             shellHandler(shell, data);
         }

src/shell.h

@@ -14,7 +14,7 @@
 
 #include "shell_cfg.h"
 
-#define     SHELL_VERSION               "3.0.6"                 /**< 版本号 */
+#define     SHELL_VERSION               "3.1.0"                 /**< 版本号 */
 
 
 /**
@@ -340,8 +340,8 @@ typedef struct shell_def
         unsigned char isActive : 1;                             /**< 当前活动Shell */
         unsigned char tabFlag : 1;                              /**< tab标志 */
     } status;
-    signed char (*read)(char *);                                /**< shell读函数 */
+    signed short (*read)(char *, unsigned short);               /**< shell读函数 */
-    void (*write)(const char);                                  /**< shell写函数 */
+    signed short (*write)(const char *, unsigned short);        /**< shell写函数 */
 } Shell;
 
 

src/shell_cfg.h

@@ -85,7 +85,7 @@
 
 /**
  * @brief shell命令参数最大数量
- *        包含命令名在内，超过8个参数并且使用了参数自动转换的情况下，需要修改源码
+ *        包含命令名在内，超过16个参数并且使用了参数自动转换的情况下，需要修改源码
  */
 #define     SHELL_PARAMETER_MAX_NUMBER  8