docs » hs.utf8

A collection of UTF-8 characters already converted from codepoint and available as convenient key-value pairs. UTF-8 printable versions of common Apple and OS X special keys are predefined and others can be added with hs.utf8.registerCodepoint(label, codepoint) for your own use.

• This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing hs.utf8.registeredKeys.
• For parity with hs.utf8.registeredLabels, this can also invoked as a function, i.e. hs.utf8.registeredKeys["cmd"] is equivalent to hs.utf8.registeredKeys("cmd")

Returns the provided string with all non-printable ascii characters escaped, except Return, Linefeed, and Tab.

• string - The input string which is to have all non-printable ascii characters escaped as \x## (a single byte hexadecimal number).
• all - an optional boolean parameter (default false) indicating whether or not Return, Linefeed, and Tab should also be considered "non-printable"

• The cleaned up string, with non-printable characters escaped.

• Because Unicode characters outside of the basic ascii alphabet are multi-byte characters, any UTF8 or other Unicode encoded character will be broken up into their individual bytes and likely escaped by this function.
• This function is useful for displaying binary data in a human readable way that might otherwise be inexpressible in the Hammerspoon console or other destination. For example:
  • utf8.charpattern, which contains the regular expression for matching valid UTF8 encoded sequences, results in (null) in the Hammerspoon console, but hs.utf8.asciiOnly(utf8.charpattern) will display [\x00-\x7F\xC2-\xF4][\x80-\xBF]*.

Wrapper to utf8.char(...) which ensures that all codepoints return valid UTF8 characters.

• codepoints - A series of numeric Unicode code points to be converted to a UTF-8 byte sequences. If a codepoint is a string (and does not start with U+, it is used as a key for lookup in hs.utf8.registeredKeys[]

• A string containing the UTF-8 byte sequences corresponding to provided codepoints as a combined string.

• Valid codepoint values are from 0x0000 - 0x10FFFF (0 - 1114111)
• If the codepoint provided is a string that starts with U+, then the 'U+' is converted to a '0x' so that lua can properly treat the value as numeric.
• Invalid codepoints are returned as the Unicode Replacement Character (U+FFFD)
  • This includes out of range codepoints as well as the Unicode Surrogate codepoints (U+D800 - U+DFFF)

Replace invalid UTF8 character sequences in inString with replacementChar so it can be safely displayed in the console or other destination which requires valid UTF8 encoding.

• inString - String of characters which may contain invalid UTF8 byte sequences
• replacementChar - optional parameter to replace invalid byte sequences in inString. If this parameter is not provided, the default UTF8 replacement character, U+FFFD, is used.

• outString - The contents of inString with all invalid UTF8 byte sequences replaced by the replacementChar.
• posTable - a table of indexes in outString corresponding indicating where replacementChar has been used.

• This function is a slight modification to code found at http://notebook.kulchenko.com/programming/fixing-malformed-utf8-in-lua.

• If replacementChar is a multi-byte character (like U+FFFD) or multi character string, then the string length of outString will be longer than the string length of inString. The character positions in posTable will reflect these new positions in outString.

• To calculate the character position of the invalid characters in inString, use something like the following:

  outString, outErrors = hs.utf8.fixUTF8(inString, replacement) inErrors = {} for i,p in ipairs(outErrors) do table.insert(inErrors, p - ((i - 1) * string.length(replacement) - 1)) end

  Where replacement is utf8.char(0xFFFD), if you leave it out of the hs.utf8.fixUTF8 function in the first line.

Returns a hex dump of the provided string. This is primarily useful for examining the exact makeup of binary data contained in a Lua String as individual bytes for debugging purposes.

• inputString - the data to be rendered as individual hexadecimal bytes for examination.
• count - an optional parameter specifying the number of bytes to display per line (default 16)

• a string containing the hex dump of the input string.

• Like hs.utf8.asciiOnly, this function will break up Unicode characters into their individual bytes.
• As an example: hs.utf8.hexDump(utf8.charpattern) will return 00 : 5B 00 2D 7F C2 2D F4 5D 5B 80 2D BF 5D 2A : [.-..-.][.-.]*

Registers a Unicode codepoint under the given label as a UTF-8 string of bytes which can be referenced by the label later in your code as hs.utf8.registeredKeys[label] for convenience and readability.

• label - a string label to use as a human-readable reference when getting the UTF-8 byte sequence for use in other strings and output functions.
• codepoint - a Unicode codepoint in numeric or U+xxxx format to register with the given label.

• Returns the UTF-8 byte sequence for the Unicode codepoint registered.

• If a codepoint label was previously registered, this will overwrite the previous value with a new one. Because many of the special keys you may want to register have different variants, this allows you to easily modify the existing predefined defaults to suite your preferences.
• The return value is merely syntactic sugar and you do not need to save it locally; it can be safely ignored -- future access to the pre-converted codepoint should be retrieved as hs.utf8.registeredKeys[label] in your code. It looks good when invoked from the console, though ☺.

Returns the label name for a UTF8 character, as it is registered in hs.utf8.registeredKeys[].

• utf8char -- the character to lookup in hs.utf8.registeredKeys[]

• The string label for the UTF8 character or a string in the format of "U+XXXX", if it is not defined in hs.utf8.registeredKeys[], or nil, if utf8char is not a valid UTF8 character.

• For parity with hs.utf8.registeredKeys, this can also be invoked as if it were an array: i.e. hs.utf8.registeredLabels(char) is equivalent to hs.utf8.registeredLabels[char]