{"id":15042266,"url":"https://github.com/konapun/orbital-frame","last_synced_at":"2025-04-14T20:32:48.486Z","repository":{"id":44842981,"uuid":"139926457","full_name":"konapun/orbital-frame","owner":"konapun","description":"The command line as a chatbot","archived":false,"fork":false,"pushed_at":"2023-01-05T16:15:14.000Z","size":1275,"stargazers_count":13,"open_issues_count":17,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T08:51:12.454Z","etag":null,"topics":["bash","bot","chatbot","discord","discord-bot","nodejs","shell","slack","slackbot","unix-command"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/konapun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-06T03:04:04.000Z","updated_at":"2024-01-13T23:58:31.000Z","dependencies_parsed_at":"2023-02-04T06:46:25.263Z","dependency_job_id":null,"html_url":"https://github.com/konapun/orbital-frame","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konapun%2Forbital-frame","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konapun%2Forbital-frame/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konapun%2Forbital-frame/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konapun%2Forbital-frame/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konapun","download_url":"https://codeload.github.com/konapun/orbital-frame/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248955993,"owners_count":21189271,"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":["bash","bot","chatbot","discord","discord-bot","nodejs","shell","slack","slackbot","unix-command"],"created_at":"2024-09-24T20:47:04.075Z","updated_at":"2025-04-14T20:32:48.465Z","avatar_url":"https://github.com/konapun.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# O R B I T A L  -  F R A M E\n**UNIX Command Line as a Chatbot**\n[![Build Status](https://travis-ci.org/konapun/orbital-frame.svg?branch=master)](https://travis-ci.org/konapun/orbital-frame)\n[![DeepScan grade](https://deepscan.io/api/teams/8479/projects/10684/branches/150761/badge/grade.svg)](https://deepscan.io/dashboard#view=project\u0026tid=8479\u0026pid=10684\u0026bid=150761)\n\nUnleash the power and flexibility of the UNIX command line with a chat bot!\nOrbital Frame supports commands, options, variables, pipes, asynchronous\nchaining, inline logical operators (via commands), functions, jobs, signals,\nplugins, and a custom language based on the venerable bash. For full details,\nvisit the [core README](./packages/orbital-frame-core/README.md).\n\n[Try it online!](https://konapun.github.io/projects/orbital-frame)\n\nThis project is organized as a monorepo consisting of the following:\n  - [@orbital-frame/core](./packages/orbital-frame-core/README.md) The core framework.\n  - [@orbital-frame/jehuty](./packages/orbital-frame-jehuty/README.md) A reference implementation using core.\n  - [@orbital-frame/parser](./packages/orbital-frame-parser/README.md) PEG grammar and parser which outputs an AST.\n  - [@orbital-frame/core-commands](./packages/orbital-frame-core-commands/README.md) A collection of optional starter commands to load into your bot. `@orbital-frame/jehuty` uses these.\n  - **@orbital-frame/plugin-*** Optional plugins that can be installed and loaded into your bot.\n  - **@orbital-frame/command-*** Optional commands that can be installed and loaded into your bot.\n  - **@orbital-frame/adapter-*** Adapters orbital frame can run on. `@orbital-frame/core` does not include an adapter by default so you must include one of these to use orbital-frame in your chat service.\n\n## Examples\nThe examples below are using `@orbital-frame/jehuty`, a reference implementation\nwhich is ready right out of the box.\n\n```sh\n@jehuty echo \"hello, world!\"\n@jehuty NUM=10; calc $NUM + 2\n@jehuty NUM=$(calc 9 + $(calc 1 + 1)); echo $NUM | calc + 2\n@jehuty echo hi $(echo hello $(echo there))\n@jehuty echo Counting $(calc 1 + 0) $(calc 1 + 1) $(calc 1 + 2) yay\n@jehuty if $(equal 1 1) \"they're equal\" \"they're not equal\"\n@jehuty alias test-alias 'if $(not $(equal 1 1)) \"they're not equal\" \"they are equal\"'\n@jehuty test-alias\n```\n\n## Syntax\nThe bot command line is mostly a subset of Bash with a few exceptions. The main\nfeatures will be covered here. Although not included for the sake of brevity and\nbecause it will vary based on your bot's configuration, every example below must\nstart by hailing your bot so it understands the message is intended for it. For\nparser details and the full grammar, see\n[@orbital-frame/parser](./packages/orbital-frame-parser/README.md).\n\n### Commands\nCommands can be called with arguments and options. The options and option types\na command accepts are provided by the command's author in the command\ndefinition. A detailed explanation for command authors is provided\n[here](./packages/orbital-frame-core/README.md#Commands).\n\n```sh\nsome_command --some_option option_value arg1 arg2\n```\n\n#### Options\nCommand options can either be valued or boolean, which is defined in the command\nitself.Command options can be either short form or long form:\n\n```sh\nsome_command --long_option option_value\n# or\nsome_command -s option_value\n```\n\nUnlike long options, short options can be chained:\n```sh\nsome_command -abcd arg # here, a, b, c, and d are all options. a, b, and c are boolean options while d is being passed the argument \"arg\"\n```\n\n#### Interpolated Commands\nCommands can be immediately evaluated for use as arguments, option values, etc.\nby surrounding the command or pipeline with `$()`:\n\n```sh\necho \"three plus two is \" $(calc 3 + 2)\n```\n\n#### Interactive Commands\nSome commands start an interactive session where the command can receive\nnonblocking input throughout its lifespan. The interaction character is\nconfigurable based on your bot but defaults to `\u003e`. For full details, see\ndocumentation in the @orbital-frame/core [README](./packages/orbital-frame-core/README.md#Interactive%20Commands):\n```sh\ninteractive_command # some command that starts an interaction\nsome_other_command # the interaction will not intercept this command\n\u003e interactive_input # because this command is prefixed with the interaction character, it will be sent to the interactive command\n```\n\n### Pipes\nPipes are pipelines of commands (or functions) who pass their output as input\ninto the next pipe.\n\n```sh\nwhoami | uppercase\n```\n\n### Variables\nVariables are key/value pairs:\n\n```sh\nMY_KEY=\"some value\" # set a variable\necho $MY_KEY # retrieve a value\n```\n\nThe following variables are built-in:\n  * **`0`** The name of the currently executing command\n  * **`1 .. n`** Positional arguments (used for getting arguments within a function)\n  * **`#`** The number of command line arguments\n  * **`@`** All command line arguments as an array\n  * **`!`** The PID of the current command\n  * **`?`** The exit status of the most recently executed command\n\n### Signals\nSee documentation in the @orbital-frame/core [README](./packages/orbital-frame-core/README.md#signalService)\n\n### Functions\nLike Bash, the Orbital Frame command line supports two forms of functions which\nare equivalent in the AST so it's a matter of your personal style:\n\n##### Form 1\n```sh\nfunction my_function {\n  echo \"This is form 1\"\n}\n\n```\n##### Form 2\n```sh\nmy_function () {\n  echo \"this is form 2\"\n}\n```\n\nLike Bash, function arguments are given through positional environment variables\n$1 through $n, so even in the second form where parentheses are used, no\nparameters can be listed.\n\n```sh\nfunction say_hello {\n  echo Hello, $1\n}\n\nsay_hello konapun # displays \"Hello, konapun\"\n```\n\n#### Control Structures\nTo keep the syntax simple, the Orbital Frame grammar does not include any\ncontrol structures such as if statements or loops but these can be easily\nreplicated using commands. Here is an additional example using commands loaded\ninto jehuty which demonstrates how to do branching using the `if` and `and`\ncommands rather than dedicated control structures:\n\n```sh\n@jehuty function analyze_length {\n    local WORD=$1\n    local LOWER=$2\n    local UPPER=$3\n    local WORD_LENGTH=$(split -d '' $WORD | length)\n\n    if $(and $(greater-than $WORD_LENGTH $LOWER) $(less-than $WORD_LENGTH $UPPER)) \"String is valid\" \"String is invalid\"\n}\n\n@jehuty analyze_length \"fits\" 1 5 # displays \"String is valid\"\n```\n\n#### Scoping\nBy default, all variables are declared in the global scope. If you want to\ninstead use lexical scoping, use the `local` keyword inside your function block:\n\n```sh\nMY_VAR=outer\n\nfunction set_var {\n  local MY_VAR=inner\n  echo $MY_VAR\n}\n\nset_var # echoes \"inner\"\necho $MY_VAR # echoes \"outer\"\n```\n\n## Developing\nThis project uses [yarn](https://github.com/yarnpkg/yarn). See yarn's [installation guide](https://yarnpkg.com/en/docs/install) for installation instructions.\nYou can bootstrap the monorepo by running\n```\nyarn dev\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonapun%2Forbital-frame","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonapun%2Forbital-frame","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonapun%2Forbital-frame/lists"}