{"id":13896651,"url":"https://github.com/martin-eden/lua_code_formatter","last_synced_at":"2025-07-17T13:30:48.658Z","repository":{"id":108072506,"uuid":"77866547","full_name":"martin-eden/lua_code_formatter","owner":"martin-eden","description":"Reformats any valid Lua 5.3 source code.","archived":false,"fork":false,"pushed_at":"2022-09-08T18:49:41.000Z","size":263,"stargazers_count":40,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-07T18:40:33.478Z","etag":null,"topics":["code","formatter","lua","parser","pretty-print","sourcecode","strip-comments"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martin-eden.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"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}},"created_at":"2017-01-02T22:43:32.000Z","updated_at":"2023-07-25T14:06:21.000Z","dependencies_parsed_at":"2024-02-23T11:14:41.022Z","dependency_job_id":"35c5d704-6cf8-43e1-9d2a-0039300dd7f0","html_url":"https://github.com/martin-eden/lua_code_formatter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-eden%2Flua_code_formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-eden%2Flua_code_formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-eden%2Flua_code_formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-eden%2Flua_code_formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martin-eden","download_url":"https://codeload.github.com/martin-eden/lua_code_formatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226265522,"owners_count":17597223,"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":["code","formatter","lua","parser","pretty-print","sourcecode","strip-comments"],"created_at":"2024-08-06T18:03:03.709Z","updated_at":"2024-11-25T02:31:11.007Z","avatar_url":"https://github.com/martin-eden.png","language":"Lua","readme":"### Description\n\nFormats any valid Lua 5.3 code.\n\nLines with code are wrapped to fit inside given margins.\n\nFiles with invalid Lua syntax may lose the content after the syntax\nerror! If this is a problem - verify the correctness of the file\nbefore running reformatter. For example via `$ luac -p \u003clua_file\u003e`.\n\nInstallation deploys three command-line scripts:\n\n  * `lua.reformat`\n  * `lua.get_ast`\n  * `lua.get_formatter_ast`\n\nLast two for people who love tinkering.\n\n---\n\n### Requirements\n\n* [LuaRocks](https://luarocks.org/). For easy installation.\n* [Lua interpreter](https://lua.org). Version 5.3 is preferred.\n  Another options described in a following table.\n\n  | Lua version required | Syntax supported | Branch           | Notes                              |\n  | :---:                | :---:            | ---              | ---                                |\n  | 5.3                  | 5.3              | [master]         | May contain experimental features. |\n  | 5.3                  | 5.3              | [5.3]            |                                    |\n  | 5.1                  | 5.3              | [5.1]            |                                    |\n  | 5.1                  | 5.1              | [5.1-syntax_5.1] |                                    |\n\n  [master]: https://github.com/martin-eden/lua_code_formatter/tree/master\n  [5.3]: https://github.com/martin-eden/lua_code_formatter/tree/5.3\n  [5.1]: https://github.com/martin-eden/lua_code_formatter/tree/5.1\n  [5.1-syntax_5.1]: https://github.com/martin-eden/lua_code_formatter/tree/5.1-syntax_5.1\n* OS: Linux. Possibly it can work on other OSs but I've not tested it\n  there.\n\n### Installation\n\n| Luarocks repo               | Git repo, luarocks                                            |\n| ---                         | ---                                                           |\n| `sudo luarocks install lcf` | `git clone https://github.com/martin-eden/lua_code_formatter` |\n|                             | `cd ./lua_code_formatter`                                     |\n|                             | `sudo luarocks make lcf-scm-1.rockspec`                       |\n\n### Deinstallation\n\n| Luarocks repo              | Git repo, luarocks         |\n| ---                        | ---                        |\n| `sudo luarocks remove lcf` | `sudo luarocks remove lcf` |\n|                            | `rm lua_code_formatter`    |\n\n---\n\n### Usage\n\n#### From command-line\n\n`lua.reformat [\u003clua_file\u003e]`\n\n#### From Lua interpreter\n\nSuppose you have a string with Lua code and wish to get another string\nwith formatted code.\n\n```Lua\ndo\n  local lua_code_str = 'do return end' -- \u003c fill it\n\n  require('lcf.workshop.base')\n  local get_ast = request('!.lua.code.get_ast')\n  local get_formatted_code = request('!.lua.code.ast_as_code')\n\n  return get_formatted_code(get_ast(lua_code_str))\nend\n```\n\n##### Passing formatting parameters\n\nYou may override default parameters by passing a table with new values\nof changed parameters:\n\n```lua\nget_formatted_code(\n  get_ast(lua_code_str),\n  {\n    indent_chunk = '  ',\n    right_margin = 96,\n    max_text_width = math.huge,\n    keep_unparsed_tail = true,\n    keep_comments = true,\n  }\n)\n```\n\n| Parameter            | Default | Description                                            | Notes |\n| ---                  | :---:   | ---                                                    | --- |\n| `indent_chunk`       | ` ` ` ` | String used for building one indent.                   | You may try value `\\|..` to see it's effect. |\n| `right_margin`       | 96      | Maximum line length with indent.                       | Setting it makes sense for printing. |\n| `max_text_width`     | +inf    | Maximum line length without indent.                    | Setting it makes sense for viewing in editor. |\n| `keep_unparsed_tail` | true    | Keep text after point where we failed to parse source. | Syntactically incorrect code may still lose parts even with this flag. For example `f() = a` is formatted as `f()`. (It's parsed as assignment but formatted as function call.) |\n| `keep_comments`      | true    | Keep comments.                                         | Comment text is not changed so comments may last beyond right margin. |\n\n##### Comments handling\n\nComments are raised to statements level.\n\nSo text\n  ```lua\n  function(a, --parameter \"a\"\n    b) --parameter \"b\"\n  end\n  ```\nis formatted as\n  ```lua\n  --parameter \"a\"\n  function(a, b)\n    --parameter \"b\"\n  end\n  ```\nThis is done to keep formatting routines simple.\n\n---\n\n### Changing formatting logic\n\nFirst, general workflow of this formatter:\n\n1. Load `.lua` file as string.\n2. Parse that string to tree in table.\n3. Change nodes of that tree to make it easier to handle in formatting\n  routines.\n4. Run formatting routines for all nodes in tree. Formatting routines\n  output to virtual printer.\n5. Write contents of virtual printer to file.\n\nWe are at point `4`. Start tinkering from something simple but usable\nas \"repeat\" block handling:\n`workshop/formats/lua/formatter/handlers/statements/blocks/repeat_block.lua`\n\n---\n\n### Contributors\n\n* Several people were asking to keep comments. This was done and\n  `--keep-comments` option was added.\n* `Peter Melnichenko ♰` shown me how to write cross-platform\n  `.rockspec` file.\n* `Oliver Jan Krylow` added cautions in `readme.md` that file with\n  invalid syntax loses tail. I've mentioned `$ luac -p` workaround\n  and added `--keep-unparsed-tail` option to detect and prevent\n  this.\n* `keneanung` adoped formatter to Lua 5.1 syntax and pushed branch\n  `5.1-syntax_5.1`. Main audience of this is LuaJIT users.\n\n### Further development\n\nI feel this project is done. Original goal to reformat ugly code from\nWorld of Warcraft addons accomplished.\n\n* I'm planning to keep it compatible with current PuC-Lua version.\n* Maybe I'll add more documentation about inner mechanics.\n* Maybe I'll add more advanced formatting like empty lines before\n  long `for` blocks.\n\n---\n\n### See also \n  * [Command-line builder](https://github.com/martin-eden/lcf_params_gui) for this.\n  * [My other repositories](https://github.com/martin-eden/contents).\n\n---\n```\n2016-08-16\n2017-01-28\n2017-09-26\n2018-02-23\n```\n","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-eden%2Flua_code_formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartin-eden%2Flua_code_formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-eden%2Flua_code_formatter/lists"}