{"id":16164765,"url":"https://github.com/aperezdc/lua-wcwidth","last_synced_at":"2025-03-18T23:30:31.757Z","repository":{"id":142776929,"uuid":"63096417","full_name":"aperezdc/lua-wcwidth","owner":"aperezdc","description":"Pure Lua implementation of the wcwidth() function","archived":false,"fork":false,"pushed_at":"2020-04-23T09:12:11.000Z","size":38,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-02-28T12:46:51.786Z","etag":null,"topics":["character","lua","lua-wcwidth","standalone","unicode","wcwidth"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/aperezdc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2016-07-11T19:34:43.000Z","updated_at":"2023-06-25T00:43:55.000Z","dependencies_parsed_at":"2023-04-27T00:03:47.287Z","dependency_job_id":null,"html_url":"https://github.com/aperezdc/lua-wcwidth","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/aperezdc%2Flua-wcwidth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aperezdc%2Flua-wcwidth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aperezdc%2Flua-wcwidth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aperezdc%2Flua-wcwidth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aperezdc","download_url":"https://codeload.github.com/aperezdc/lua-wcwidth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243955431,"owners_count":20374369,"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":["character","lua","lua-wcwidth","standalone","unicode","wcwidth"],"created_at":"2024-10-10T02:47:40.171Z","updated_at":"2025-03-18T23:30:31.751Z","avatar_url":"https://github.com/aperezdc.png","language":"Lua","readme":"lua-wcwidth\n===========\n\n[![Build Status](https://travis-ci.org/aperezdc/lua-wcwidth.svg?branch=master)](https://travis-ci.org/aperezdc/lua-wcwidth)\n[![Coverage Status](https://coveralls.io/repos/github/aperezdc/lua-wcwidth/badge.svg?branch=master)](https://coveralls.io/github/aperezdc/lua-wcwidth?branch=master)\n[![LuaRocks](https://img.shields.io/badge/luarocks-v0.5-blue.png)](https://luarocks.org/modules/aperezdc/wcwidth)\n\nWhen writing output to a fixed-width output system (such as a terminal), the\ndisplayed length of a string does not always match the number of characters\n(also known as [runes](https://swtch.com/plan9port/unix/man/rune3.html), or\ncode points) contained by the string. Some characters occupy two spaces\n(full-wide characters), and others occupy none.\n\nPOSIX.1-2001 and POSIX.1-2008 specify the\n[wcwidth(3)](http://man7.org/linux/man-pages/man3/wcwidth.3.html) function\nwhich can be used to know how many spaces (or *cells*) must be used to display\na Unicode code point. This [Lua](http://lua.org) contains a portable and\nstandalone implementation based on the Unicode Standard release files.\n\nThis module is useful mainly for implementing programs which must produce\noutput to terminals, while handling proper alignment for double-width and\nzero-width Unicode code points.\n\nUsage\n-----\n\nThe following snippet defines a function which can determine the display width\nfor a string:\n\n```lua\nlocal wcwidth, utf8 = require \"wcwidth\", require \"utf8\"\n\nlocal function display_width(s)\n  local len = 0\n  for _, rune in utf8.codes(s) do\n    local l = wcwidth(rune)\n    if l \u003e= 0 then\n      len = len + l\n    end\n  end\n  return len\nend\n```\n\nThe function above can be used to print any UTF-8 string properly\nright-aligned to a terminal:\n\n```lua\nlocal function alignright(s, cols)\n  local numspaces = cols - display_width(s)\n  local spaces = \"\"\n  while numspaces \u003e 0 do\n    numspaces = numspaces - 1\n    spaces = spaces .. \" \"\n  end\n  return spaces .. s\nend\n\nprint(alignright(\"コンニチハ\", 80))\n```\n\nThe `wcwidth()` function takes a Unicode code point as argument, and returns\none of the following values:\n\n* `-1`: Width cannot be determined (the code point is not printable).\n* `0`: The code point does not advance the cursor (e.g. `NULL`, or a combining\n  character).\n* `2`: The character is East Asian wide (`W`) or East Asian full-width (`F`),\n  and is displayed using two spaces.\n* `1`: All the rest of characters, which take a single space.\n\nNote that the\n[wcswidth(3)](http://man7.org/linux/man-pages/man3/wcswidth.3.html) companion\nfunction is *deliberately not provided by this module*: while Lua 5.3 provides\n[utf8.codes()](http://www.lua.org/manual/5.3/manual.html#pdf-utf8.codes) and\n[utf8.codepoint()](http://www.lua.org/manual/5.3/manual.html#pdf-utf8.codepoint)\nto convert UTF8 byte sequences to code points, for other Lua versions it would\nbe needed to depend on a third party module, and that would be against the\ngoal of `wcwidth` being standalone. If needed be, `wcswidth()` can be\nimplemented as follows using the Lua 5.3 `utf8` module (or any other\nimplementation which provides a compatible implementation):\n\n```lua\n-- Calculates the printable length of first \"n\" characters of string \"s\"\n-- on a terminal. Returns the number of cells or -1 if the string contains\n-- non-printable characters. Raises an error on invalid UTF8 input.\nfunction wcswidth(s, n)\n  local cells = 0\n  if n then\n    local count = 0\n    for _, rune in utf8.codes(s) do\n      local w = wcwidth(rune)\n      if w \u003c 0 then return -1 end\n      count = count + 1\n      if count \u003e= n then break end\n    end\n  else\n    for _, rune in utf8.codes(s) do\n      local w = wcwidth(rune)\n      if w \u003c 0 then return -1 end\n      cells = cells + w\n    end\n  end\n  return cells\nend\n```\n\n\nInstallation\n------------\n\n[LuaRocks](https://luarocks.org) is recommended for installation.\n\nThe stable version (recommended) can be installed with:\n\n```sh\nluarocks install wcwidth\n```\n\nThe development version can be installed with:\n\n```sh\nluarocks install --server=https://luarocks.org/dev wcwidth\n```\n\nUnicode Tables\n--------------\n\nThe `update-tables` script downloads the following resources from the [Unicode\nConsortium website](http://unicode.org):\n\n* http://www.unicode.org/Public/UNIDATA/EastAsianWidth.txt\n* http://www.unicode.org/Public/UNIDATA/extracted/DerivedGeneralCategory.txt\n\nWith them, it generates the following files:\n\n* [wcwidth/widetab.lua](./wcwidth/widetab.lua)\n* [wcwidth/zerotab.lua](./wcwidth/zerotab.lua)\n\nThe most current version of `wcwidth` uses the following versions of the above\nUnicode Standard release files:\n\n* `EastAsianWidth-13.0.0.txt, Date: 2029-01-21, 18:14:00 GMT [KW, LI], © 2020 Unicode®, Inc.`\n* `DerivedGeneralCategory-13.0.0.txt, Date: 2019-10-21, 14:30:32 GMT, © 2019 Unicode®, Inc.`\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faperezdc%2Flua-wcwidth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faperezdc%2Flua-wcwidth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faperezdc%2Flua-wcwidth/lists"}