{"id":20260704,"url":"https://github.com/gesslar/helper","last_synced_at":"2026-05-14T07:36:36.525Z","repository":{"id":259330262,"uuid":"862681972","full_name":"gesslar/Helper","owner":"gesslar","description":"A Mudlet package to provide help text parsing via tags.","archived":false,"fork":false,"pushed_at":"2024-11-22T06:30:59.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-14T04:21:28.767Z","etag":null,"topics":["mudlet","mudlet-lua","mudlet-package"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gesslar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-09-25T02:34:20.000Z","updated_at":"2024-11-22T06:30:59.000Z","dependencies_parsed_at":"2024-10-24T13:22:06.898Z","dependency_job_id":"b4beef55-4c88-49ed-a990-5c8d699bd9a2","html_url":"https://github.com/gesslar/Helper","commit_stats":null,"previous_names":["gesslar/helper"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesslar%2FHelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesslar%2FHelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesslar%2FHelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesslar%2FHelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gesslar","download_url":"https://codeload.github.com/gesslar/Helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241721536,"owners_count":20009192,"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":["mudlet","mudlet-lua","mudlet-package"],"created_at":"2024-11-14T11:21:43.747Z","updated_at":"2026-05-14T07:36:36.513Z","avatar_url":"https://github.com/gesslar.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helper\n\nHelper is a Mudlet metapackage to be used in other packages or projects to\nprovide help text parsing via tags. It is inspired by the help system in the\n[generic_mapper](https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/generic-mapper/generic_mapper.xml)\npackage that comes with Mudlet.\n\nThis package is meant to accompany your own packages to provide help text for\ncommands, triggers, and whatever else you can think of.\n\n## Usage\n\nTo use Helper, all you need is to have it installed as a package, or,\nalternatively, you can just copy the `Helper.lua` file into your own package,\neither directly, in Mudlet, or in your muddler or muddy project's resources\ndirectory.\n\nThe function to call to use Helper is:\n\n```lua\nhelper.print({text = \"Your text\"[, styles = {h1 = \"chartreuse\", h2 = \"blue\"}]})\n```\n\nIt accepts two arguments:\n\n- `text` - The text to parse for help tags.\n- `styles` - A table of styles to use for the help text.\n\n### Styles\n\nThe `styles` parameter is optional. If not provided, the default styles will be\nused. Passing styles will merge your custom styles with the defaults,\noverriding existing styles and adding new ones.\n\nBy default, Helper has the following styles defined:\n\n```lua\nlocal defaultStyles = {\n  h1 = \"red\",\n  h2 = \"blue\",\n  h3 = \"yellow\",\n  h4 = \"green\",\n  h5 = \"magenta\",\n  h6 = \"cyan\",\n}\n```\n\nThe values for the colours are those which are supported as part of Mudlet's\n[colour table](https://wiki.mudlet.org/images/c/c3/ShowColors.png)\nwhich works with the [`cecho()`](https://wiki.mudlet.org/w/Manual:Lua_Functions#cecho)\nfunction that is used to display the text.\n\n### Text\n\nThe text can contain tags which are similar in appearance to those in HTML,\nincluding those which are recognised by the [`cecho()`](https://wiki.mudlet.org/w/Manual:Lua_Functions#cecho)\nfunction, as well as the `\u003creset\u003e` tag.\n\nA basic example of the text parameter might look like:\n\n```lua\nlocal my_styles = {\n  h1 = \"chartreuse\",\n  danger = \"orange_red\",\n}\nhelper.print({\n  text =\n\"\u003cdanger\u003eWarning!\u003c/danger\u003e\\n\" ..\n\"This is a \u003ch1\u003etest\u003c/h1\u003e of the emergency text system. Contact your local\\n\" ..\n\"kitten for some comfort.\",\n  styles = my_styles,\n})\n```\n\n#### Tags do not nest\n\nHelper currently does not support nested tags. Any closing tag (`\u003c/...\u003e`) is\nrewritten to `\u003creset\u003e`, which clears *all* active styling rather than popping\nonly the innermost one. This also applies to cecho's native decoration tags\n(`\u003cb\u003e`, `\u003cu\u003e`, `\u003ci\u003e`, `\u003cs\u003e`) when they appear inside a Helper-styled scope —\ntheir closers will reset the surrounding color as well.\n\nFor now, keep each styled span flat:\n\n```lua\n-- OK\n\"\u003cdanger\u003eWarning!\u003c/danger\u003e \u003ch1\u003eHeading\u003c/h1\u003e\"\n\n-- Not OK — the \u003c/u\u003e and \u003c/danger\u003e will wipe the active style\n\"\u003cdanger\u003e\u003cu\u003eWarning\u003c/u\u003e\u003c/danger\u003e\"\n```\n\n### Function tags\n\nHelper supports the use of tags which can derive text as return values from\nfunctions.\n\nA tag is defined by using the `@` symbol followed by the name of the function\nwhich will be called to provide the text for that tag. For example:\n\nUsing a function to provide the text for a tag:\n\n```lua\nhelper.print({text = \"The current version of this package is \u003cb\u003e\u003c@version\u003e\u003c/b\u003e.\"})\n\nfunction version()\n  return helper._VERSION\nend\n```\n\nUsing a method to provide the URL for a link:\n\n```lua\nhelper.print({text = \"You can download the latest version of this package \"\n                     \"from \u003c@MyPackage:url\u003e.\"})\n\nfunction MyPackage:url()\n  return self._URL\nend\n```\n\nThe function must be defined and accessible by the Helper module.\n\n## License\n\n`helper` is released under the [0BSD](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesslar%2Fhelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgesslar%2Fhelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesslar%2Fhelper/lists"}