{"id":23424297,"url":"https://github.com/ringtailsoftware/zig-embshell","last_synced_at":"2025-04-12T16:35:26.251Z","repository":{"id":136877117,"uuid":"595374526","full_name":"ringtailsoftware/zig-embshell","owner":"ringtailsoftware","description":"Small embeddable command line shell in zig","archived":false,"fork":false,"pushed_at":"2025-01-13T20:16:26.000Z","size":40,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T22:40:50.402Z","etag":null,"topics":["cli","embedded","shell","zig","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ringtailsoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-31T00:09:50.000Z","updated_at":"2025-04-05T15:02:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"6b27b14c-51eb-4b5d-aa5e-b2e70842a705","html_url":"https://github.com/ringtailsoftware/zig-embshell","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Fzig-embshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Fzig-embshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Fzig-embshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Fzig-embshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringtailsoftware","download_url":"https://codeload.github.com/ringtailsoftware/zig-embshell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248597102,"owners_count":21130811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","embedded","shell","zig","zig-package","ziglang"],"created_at":"2024-12-23T04:16:33.387Z","updated_at":"2025-04-12T16:35:26.245Z","avatar_url":"https://github.com/ringtailsoftware.png","language":"Zig","readme":"# EmbShell\n\nA very small interactive command shell for (embedded) Zig programs.\n\nEmbShell makes an ideal system monitor for debugging and interacting with a small embedded system. It interactively takes lines of text, parses commands and makes callbacks into handler functions.\n\nCompared with Readline, Linenoise and Editline - EmbShell is tiny. It lacks most of their features, but it does have:\n\n - Tab completion for command names\n - Backspace for line editing\n - No reliance on libc and very little use of Zig's `std` (ie. no fancy print formatting)\n - Very little RAM use (just a configurable buffer for the incoming command line)\n\nIn EmbShell:\n\n - All commands and configuration are set at `comptime` to optimise footprint\n - All arguments are separated by whitespace, there is no support for quoted strings, multiline commands or escaped data\n - All handler arguments are strings, leaving it to the app to decide how to parse them\n - No runtime memory allocations\n\n## Using\n\nDeveloped with `zig 0.14.0`\n\n### Run the sample\n\n    cd example-posix\n    zig build run\n\n```\nmyshell\u003e help\necho\nled\nmyshell\u003e echo hello world\nYou said: { echo, hello, world }\nOK\nmyshell\u003e led 1\nIf we had an LED it would be set to true\nOK\n```\n\n## Using in your own project\n\nFirst add the library as a dependency in your `build.zig.zon` file.\n\n`zig fetch --save git+https://github.com/ringtailsoftware/zig-embshell.git`\n\nAnd add it to `build.zig` file.\n```zig\nconst embshell_dep = b.dependency(\"embshell\", .{\n    .target = target,\n    .optimize = optimize,\n});\nexe.root_module.addImport(\"embshell\", embshell_dep.module(\"embshell\"));\n```\n\n`@import` the module and provide a configuration.\n\n - `.prompt` is the string shown to the user before each command is entered\n - `.maxargs` is the maximum number of arguments EmbShell will process (e.g. \"mycmd foo bar\" is 3 arguments)\n - `.maxlinelen` is the maximum length of a line to be handled, a buffer of this size will be created\n - `.cmdtable` an array of names and handler function for commands\n\n```zig\nconst UserdataT = u32;\nconst EmbShellT = @import(\"embshell\").EmbShellFixedParams(UserdataT);\nconst EmbShell = @import(\"embshell\").EmbShellFixed(.{\n    .prompt = \"myshell\u003e \",\n    .maxargs = 16,\n    .maxlinelen = 128,\n    .cmdtable = \u0026.{\n        .{ .name = \"echo\", .handler = echoHandler },\n        .{ .name = \"led\", .handler = ledHandler },\n    },\n    .userdataT = UserdataT,\n});\n```\n\n\nEach handler function is in the following form. EmbShell prints \"OK\" after successfully executing each function and \"Failed\" if an error is returned.\n\n```zig\nfn myHandler(userdata: UserdataT, args:[][]const u8) anyerror!void {\n    // process args\n    // optionally return error\n}\n```\n\nNext, call `.init()` and provide a write callback to allow EmbShell to emit data\n\n```zig\nfn write(data:[]const u8) void {\n    // emit data to terminal\n}\n\nvar shell = try EmbShell.init(write, userdata);\n```\n\nFinally, feed EmbShell with incoming data from the terminal to be processed\n\n```zig\nconst buf = readFromMyTerminal();\nshell.feed(buf)\n```\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringtailsoftware%2Fzig-embshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringtailsoftware%2Fzig-embshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringtailsoftware%2Fzig-embshell/lists"}