diff --git a/README b/README index 251e2be..4625288 100644 --- a/README +++ b/README @@ -1,10 +1,9 @@ - - Lua-iconv: performs character set conversions in Lua - (c) 2005-10 Alexandre Erwin Ittner - Project page: http://lua-iconv.luaforge.net/ +Lua-iconv: performs character set conversions in Lua +(c) 2005-10 Alexandre Erwin Ittner +Project page: http://lua-iconv.luaforge.net/ -=== INTRODUCTION === +=== Introduction === Lua-iconv is POSIX 'iconv' binding for the Lua Programming Language. The iconv library converts a sequence of characters from one codeset into a @@ -12,22 +11,91 @@ sequence of corresponding characters in another codeset. The codesets are those specified in the iconv.new() call that returned the conversion descriptor, cd. -Lua-iconv 6 *requires* Lua 5.1. If you are using Lua 5.0, please use the -first release (lua-iconv-r1). +Lua-iconv 6 and later *requires* Lua 5.1. If you are using Lua 5.0, please +use the first release (lua-iconv-r1). -Details regarding iconv may be obtained from: -http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html +Details on iconv may be obtained in the Open Group's interface definition +(http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html). -=== LICENSE === +=== Download and installation === -Lua-iconv is (c) 2005-10 Alexandre Erwin Ittner +Lua-iconv can be obtained from its LuaForge project page +(http://luaforge.net/projects/lua-iconv/) or from some Linux distributions +which already provide it (eg. Debian). + +Unless you downloaded a compiled package, you must build the library for +your system. If you are using a system with pkg-config (as many Linux +distributions and Unix flavors) just fire up your favourite shell, untar +the distribution package and type, as root, within the program directory: + + make install + +The library will be compiled and installed on the in the correct path (which +is defined in lua5.1.pc). + +Compiling on systems without pkg-config requires manual changes in the +Makefile. + + + +=== Loading and initialization === + +Lua-iconv is a shared library that must be loaded in the Lua interpreter +before use. From Lua 5.1 and later, you can simply do a + + require "iconv" + +call to load up the library (that, of course, must be installed in a +directory from package.cpath). + + + +=== API documentation === + +cd = iconv.new(to, from) +cd = iconv.open(to, from) + + Opens a new conversion descriptor, from the 'from' charset to the + 'to' charset. Concatenating "//TRANSLIT" to the first argument will + enable character transliteration and concatenating "//IGNORE" to + the first argument will cause iconv to ignore any invalid characters + found in the input string. + + This function returns a new converter or nil on error. + + +nstr, err = cd:iconv(str) + + Converts the 'str' string to the desired charset. This method always + returns two arguments: the converted string and an error code, which + may have any of the following values: + + nil + No error. Conversion was successful. + + iconv.ERROR_NO_MEMORY + Failed to allocate enough memory in the conversion process. + + iconv.ERROR_INVALID + An invalid character was found in the input sequence. + + iconv.ERROR_INCOMPLETE + An incomplete character was found in the input sequence. + + iconv.ERROR_UNKNOWN + There was an unknown error. + + +=== License === Lua-iconv is copyrighted free software: it can be used for both academic and commercial purposes at absolutely no cost. There are no royalties or GNU-like "copyleft" restrictions. The legal details are below: + Lua-iconv is (c) 2005-10 Alexandre Erwin Ittner + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including @@ -51,77 +119,3 @@ or GNU-like "copyleft" restrictions. The legal details are below: documentation would be greatly appreciated (but it is not required). - -=== DOWNLOAD, COMPILATION AND INSTALLATION === - -Lua-iconv can be obtained from its LuaForge project page: -http://lua-iconv.luaforge.net/ - -Lua-iconv must be compiled as a shared object and loaded by the Lua -interpreter using the new module system in Lua 5.1. - -If you are using a system with pkg-config (as many Linux distributions and -Unix flavors) just fire up your favourite shell, untar the distribution -package and type, as root, within the program directory: - - make install - -The library will be compiled and installed on the in the correct path (that -is defined in lua5.1.pc. - -Compiling on systems without pkg-config requires manual changes on the -Makefile. - - - -=== LOADING AND INITIALIZATION === - -Lua-iconv is a shared library that exports a single function called -luaopen_iconv that must be called by the Lua interpreter. Lua 5.1 -uses the new package system, so you can simply do a - - require "iconv" - -call to load up the library (that, of course, must be installed in a -directory from package.cpath). - - - -=== USAGE === - -cd = iconv.new(to, from) -cd = iconv.open(to, from) - - Opens a new conversion descriptor, from the 'from' charset to the - 'to' charset. Concatenating "//TRANSLIT" to the first argument will - enable character transliteration and concatenating "//IGNORE" to - the first argument will cause iconv to ignore any invalid characters - found in the input string. - - This function returns a new converter or nil on error. - - -nstr, err = cd:iconv(str) - - Converts the 'str' string to the desired charset. This method always - returns two arguments: the converted string and an error code, which - may have any of the following values: - - nil - No error. Conversion was succeful. - - iconv.ERROR_NO_MEMORY - Failed to allocate enough memory in the conversion process. - - iconv.ERROR_INVALID - An invalid character was found in the input sequence. - - iconv.ERROR_INCOMPLETE - An incomplete character was found in the input sequence. - - iconv.ERROR_UNKNOWN - There was an unknown error. - - -=== EOF === -