lua-wcwidth
===========

[![Build Status](https://travis-ci.org/aperezdc/lua-wcwidth.svg?branch=master)](https://travis-ci.org/aperezdc/lua-wcwidth)
[![Coverage Status](https://coveralls.io/repos/github/aperezdc/lua-wcwidth/badge.svg?branch=master)](https://coveralls.io/github/aperezdc/lua-wcwidth?branch=master)
[![LuaRocks](https://img.shields.io/badge/luarocks-v0.5-blue.png)](https://luarocks.org/modules/aperezdc/wcwidth)

When writing output to a fixed-width output system (such as a terminal), the
displayed length of a string does not always match the number of characters
(also known as [runes](https://swtch.com/plan9port/unix/man/rune3.html), or
code points) contained by the string. Some characters occupy two spaces
(full-wide characters), and others occupy none.

POSIX.1-2001 and POSIX.1-2008 specify the
[wcwidth(3)](http://man7.org/linux/man-pages/man3/wcwidth.3.html) function
which can be used to know how many spaces (or *cells*) must be used to display
a Unicode code point. This [Lua](http://lua.org) contains a portable and
standalone implementation based on the Unicode Standard release files.

This module is useful mainly for implementing programs which must produce
output to terminals, while handling proper alignment for double-width and
zero-width Unicode code points.

Usage
-----

The following snippet defines a function which can determine the display width
for a string:

```lua
local wcwidth, utf8 = require "wcwidth", require "utf8"

local function display_width(s)
  local len = 0
  for _, rune in utf8.codes(s) do
    local l = wcwidth(rune)
    if l >= 0 then
      len = len + l
    end
  end
  return len
end
```

The function above can be used to print any UTF-8 string properly
right-aligned to a terminal:

```lua
local function alignright(s, cols)
  local numspaces = cols - display_width(s)
  local spaces = ""
  while numspaces > 0 do
    numspaces = numspaces - 1
    spaces = spaces .. " "
  end
  return spaces .. s
end

print(alignright("コンニチハ", 80))
```

The `wcwidth()` function takes a Unicode code point as argument, and returns
one of the following values:

* `-1`: Width cannot be determined (the code point is not printable).
* `0`: The code point does not advance the cursor (e.g. `NULL`, or a combining
  character).
* `2`: The character is East Asian wide (`W`) or East Asian full-width (`F`),
  and is displayed using two spaces.
* `1`: All the rest of characters, which take a single space.

Note that the
[wcswidth(3)](http://man7.org/linux/man-pages/man3/wcswidth.3.html) companion
function is *deliberately not provided by this module*: while Lua 5.3 provides
[utf8.codes()](http://www.lua.org/manual/5.3/manual.html#pdf-utf8.codes) and
[utf8.codepoint()](http://www.lua.org/manual/5.3/manual.html#pdf-utf8.codepoint)
to convert UTF8 byte sequences to code points, for other Lua versions it would
be needed to depend on a third party module, and that would be against the
goal of `wcwidth` being standalone. If needed be, `wcswidth()` can be
implemented as follows using the Lua 5.3 `utf8` module (or any other
implementation which provides a compatible implementation):

```lua
-- Calculates the printable length of first "n" characters of string "s"
-- on a terminal. Returns the number of cells or -1 if the string contains
-- non-printable characters. Raises an error on invalid UTF8 input.
function wcswidth(s, n)
  local cells = 0
  if n then
    local count = 0
    for _, rune in utf8.codes(s) do
      local w = wcwidth(rune)
      if w < 0 then return -1 end
      count = count + 1
      if count >= n then break end
    end
  else
    for _, rune in utf8.codes(s) do
      local w = wcwidth(rune)
      if w < 0 then return -1 end
      cells = cells + w
    end
  end
  return cells
end
```


Installation
------------

[LuaRocks](https://luarocks.org) is recommended for installation.

The stable version (recommended) can be installed with:

```sh
luarocks install wcwidth
```

The development version can be installed with:

```sh
luarocks install --server=https://luarocks.org/dev wcwidth
```

Unicode Tables
--------------

The `update-tables` script downloads the following resources from the [Unicode
Consortium website](http://unicode.org):

* http://www.unicode.org/Public/UNIDATA/EastAsianWidth.txt
* http://www.unicode.org/Public/UNIDATA/extracted/DerivedGeneralCategory.txt

With them, it generates the following files:

* [wcwidth/widetab.lua](./wcwidth/widetab.lua)
* [wcwidth/zerotab.lua](./wcwidth/zerotab.lua)

The most current version of `wcwidth` uses the following versions of the above
Unicode Standard release files:

* `EastAsianWidth-13.0.0.txt, Date: 2029-01-21, 18:14:00 GMT [KW, LI], © 2020 Unicode®, Inc.`
* `DerivedGeneralCategory-13.0.0.txt, Date: 2019-10-21, 14:30:32 GMT, © 2019 Unicode®, Inc.`