{"id":25056584,"url":"https://github.com/agvxov/bashtutor","last_synced_at":"2025-04-14T11:42:32.096Z","repository":{"id":243425853,"uuid":"812232533","full_name":"agvxov/bashtutor","owner":"agvxov","description":"Easily extendable utility to interactively showcase or teach CLIs, command line tasks, workflows and Bash itself.","archived":false,"fork":false,"pushed_at":"2024-08-17T13:27:37.000Z","size":89,"stargazers_count":25,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T00:51:16.369Z","etag":null,"topics":["bash","cli","learning","learning-by-doing","learning-exercise","teaching","teaching-tool","teaching-tools"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/agvxov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-06-08T10:05:21.000Z","updated_at":"2025-03-07T02:25:58.000Z","dependencies_parsed_at":"2024-08-13T02:55:19.254Z","dependency_job_id":"01cd5fcf-293f-4e09-b82d-44c71af210fd","html_url":"https://github.com/agvxov/bashtutor","commit_stats":null,"previous_names":["agvxov/bashtutor"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agvxov%2Fbashtutor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agvxov%2Fbashtutor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agvxov%2Fbashtutor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agvxov%2Fbashtutor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agvxov","download_url":"https://codeload.github.com/agvxov/bashtutor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248875173,"owners_count":21175996,"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","cli","learning","learning-by-doing","learning-exercise","teaching","teaching-tool","teaching-tools"],"created_at":"2025-02-06T13:33:59.914Z","updated_at":"2025-04-14T11:42:32.069Z","avatar_url":"https://github.com/agvxov.png","language":"Shell","readme":"# Bashtutor\n\u003e Easily extendable utility to interactively showcase or teach CLIs, command line tasks, workflows and Bash itself.\n\n### Usage\nBashtutor works on module bases.\nEach module may teach one specific thing or a broader concept.\nEither a convention abiding module's path or the initialization file\nmust be passed from the cli:\n```sh\n$ bashtutor test_module/\n```\nAfterwards an interactive shell is spawned which will monitor the user's\nprogress _(offline, obviously)_ throughout the module,\nexpressed as individual tasks.\n\nHere is an example:\n```sh\nWelcome! You are running bashtutor v1.2.\nThe currently loaded module is 'test_module/' with 2 tasks.\nYou may run 'task' or 'hint' anytime to display the current task again or a help message respectably.\n\nEnter 'echo hello world'\n(bashtutor) $ echo hello world\nhello world\n\n(1/2)\n\nEnter 'echo goodbye world'\n(bashtutor) $ echo goodbye world\ngoodbye world\nModule completed. Thanks for flying bashtutor!\n```\n\n### Bash module\nThe Bash module (`bash_module/`) is provided both as a proof of concept and\nlegit learning material for Bash.\nFeel free to take it on a test ride.\n\n### Creating a module\nA module consists of a _task file list_ and an arbitrary number of _task files_.\nFor clarity's sake, both of these must be written in bash.\n\nBellow is a detailed explanation,\nbut consulting `test_module/` might get you up to speed faster.\n\n#### Task file list\nThe task file list defines what tasks belong to the module\nand in what order they should be executed.\nThis is done by appending file names to the array variable `${BASHTUTOR_TASK_FILE_LIST}`.\nEach task file name is assumed to be relative to the task file list.\nYou may keep your tasks files in an arbitrary structure inside your module.\nThe default task file name is `task_list.sh` and is automatically recognized.\nThis has the advantage that the user will only have to pass the module directory,\nhowever it changes nothing else as long as the task file is passed explicitly.\n\n#### Task files\nEach task file must define the following functions:\n+ description\n+ hint\n+ validate\n\nTask files are sourced,\nthey operate in the exact same shell as user is using.\n\nYou may define any number of helper functions,\nbut know that if you do not `unset` them at the end of the script\nthey will leak into the user's \"namespace\" and be exposed to him.\n\nCommands outside of functions are in fact executed,\nif you want to do that for some reason,\nyou are free to do so,\nhowever task files are evaluated after each command,\nthis means that adding expensive operations\nwill deteriorate the user experience.\nIn such case you should set some symbols\nwhich **will** persist and check for their existence/state.\n\n##### description\nThis function is run once when the task is initiated\nor whenever the user calls `task`.\n\nThis function *should* print some message to the user which makes it clear\nwhat he should be doing\n\n##### hint\nThis is a function is run only when the user explicitly asks for a hint.\n\nThis function *should* print some message which can help the user accomplish his task.\n\n##### validate\nThis function is called after every command entered.\nThe last command the user has entered is passed in the arguments.\nYou may inspect each bit with `$\u003cint\u003e` or the whole command as one with `$*`.\nSince task files are sourced, all variables of the user's shell are available to you.\nYou may use this fact to perform arbitrary checks,\nfor example inspect files in `$PWD`.\nTo make a task considered complete and to initiate moving on to the next one, `return 1`.\n\n#### Variables\nThe following variables will be available to you inside module scripts:\n```\nBASHTUTOR_R       : the return value of the user's last command\nBASHTUTOR_PS1     : the primary prompt bashtutor uses\nBASHTUTOR_VERSION : version number in 'v\u003cMAJOR\u003e.\u003cMINOR\u003e' notation\n```\n\nAlong side with the following, which all represent ANSI escape sequences:\n+ `NORMAL`\n+ `ITALICS`\n+ `BOLD`\n+ `RED`\n+ `GREEN`\n+ `YELLOW`\n+ `BLUE`\n+ `MAGENTA`\n+ `CYAN`\n\n**NOTE:** WHITE and BLACK are purposefully not provided\nto discourage the usage of colors which could be hard to see depending on the\nunderlying terminal.\n","funding_links":[],"categories":["\u003ca name=\"utility\"\u003e\u003c/a\u003eUtilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagvxov%2Fbashtutor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagvxov%2Fbashtutor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagvxov%2Fbashtutor/lists"}