Embedded/letter-shell
1
0
Fork 0
mirror of https://github.com/NevermindZZT/letter-shell.git synced 2025-01-21 10:02:54 +08:00
Code Issues Releases Wiki Activity

更改 shell读写接口

Browse Source
This commit is contained in:
NevermindZZT 2021-04-05 19:06:25 +08:00
parent 6f07983e7f
commit 480223721d
7 changed files with 69 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -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 char -1 读取数据失败
* @return unsigned short 实际读取到的字符数量
*/
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

2
demo/esp-idf/shell_cfg.h
View File

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

2
demo/stm32-freertos/shell_cfg.h
View File

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

21
demo/x86-gcc/shell_port.c
View File

@ -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')
{

50
src/shell.c
View File

@ -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
&& *string != '\r'
&& *string != '\n'
&& count < 36)
while (*p && *p != '\r' && *p != '\n')
{
shell->write(*string ++);
count ++;
if (count >= 36 && *(string + 1))
{
shell->write('.');
shell->write('.');
shell->write('.');
}
p++;
count++;
}
return count;
if (count > 36)
{
shell->write(string, 36);
shell->write("...", 3);
}
else
{
shell->write(string, 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++);
}
shell->write(buffer, len);
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);
}

6
src/shell.h
View File

@ -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读函数 */
void (*write)(const char); /**< shell写函数 */
signed short (*read)(char *, unsigned short); /**< shell读函数 */
signed short (*write)(const char *, unsigned short); /**< shell写函数 */
} Shell;

2
src/shell_cfg.h
View File

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