mediawiki-extensions-Scribunto/engines/LuaCommon/lualib/luabit/readme.txt

LuaBit
------
LuaBit is a bitwise operation lib completely written in Lua. It's
written in the belief that Lua is self-contained.

The supported operations are: not, and, or, xor, right shift, logic
right shift and left shift.

Several utilities are designed to leverage the power of bit operation:
 1. hex: a dec <-> hex number converter
 2. utf8: convert utf8 string to ucs2
 3. noki: convert nokia pc suite backuped SMS file to .txt

Under the MIT license.

Visit http://luaforge.net/projects/bit/ to get latest version.

Status
------
Now LuaBit is in v0.4. 
Release date: Mar 18, 2007

Content
-------
3 files are there for LuaBit:
 1) bit.lua
    is the bitwise operation lib, all operations are implemented here.

 2) hex.lua
    is a helper lib for ease of using hex numbers with bitwise 
    operation.

 3) noki.lua
    a utility(based on bit and hex) to convert Nokia PC Suite backuped 
    SMS to a unicode .txt file, which is more accessible than the 
    original .nfb or .nfc file.
    
 4) utf8.lua
    convert utf8 string to ucs2 string

How to use
----------
Bit
---
Just require 'bit' in your project and the bit lib will be 
available:
 bit.bnot(n) -- bitwise not (~n)
 bit.band(m, n) -- bitwise and (m & n)
 bit.bor(m, n) -- bitwise or (m | n)
 bit.bxor(m, n) -- bitwise xor (m ^ n)
 bit.brshift(n, bits) -- right shift (n >> bits)
 bit.blshift(n, bits) -- left shift (n << bits)
 bit.blogic_rshift(n, bits) -- logic right shift(zero fill >>>)

Please note that bit.brshift and bit.blshift only support number within
32 bits.

2 utility functions are provided too:
 bit.tobits(n) -- convert n into a bit table(which is a 1/0 sequence)
               -- high bits first
 bit.tonumb(bit_tbl) -- convert a bit table into a number 

Hex
---
For ease of using hex numbers, a utility hex lib is also included in 
LuaBit. You can require 'hex' to use them:
 hex.to_hex(n) -- convert a number to a hex string
 hex.to_dec(hex) -- convert a hex string(prefix with '0x' or '0X') to number

With hex, you can write code like:
 bit.band(258, hex.to_dec('0xFF'))
to get the lower 8 bits of 258, that's 2.

Noki
----
require 'noki', to save your sms to .txt file:
 noki.save_sms('nokia.nfb', 'sms.txt')
and you can view the output sms.txt in notepad or other editor which
support unicode.

Utf8
----
require 'utf8', to convert a utf8 string:
 ucs2_string = utf8.utf_to_uni(utf8_string)

History
-------
v0.4
* utf8 to ucs2 converter(utf8.lua).
* clean up for compatible with Lua5.1 and 5.0.
* add 'How to use' section for bit.lua and hex.lua.

v0.3
* noki added as an application of bit.
* typo correction.

v0.2
* add logic right shift(>>>) support: bit.blogic_rshift.
* add 2 utility functions: bit.tobits and bit.tonumb.
* update hex.to_hex(in hex.lua) to support negative number.

v0.1
LuaBit is written when I do my own game project(Fio at http://fio.edithis.info). 
When loading resources, I have to do some bit operation. And I do not
like the embedded way of bit operation. So I decide to implement those
ops in lua. And that's LuaBit. It's not as fast as the embedded one, but
it works. And Lua is self-contained :-)

To-Do List
---------
v0.1
It'll be useful if LuaBit support those bitwise op like:
 bit.band(258, '0xFF')
ease to type and use. This will be supported in next release.

v0.2
I decide to delay this feature to later version for it'll mess up the 
interface of LuaBit.

v0.3
May more utility functions add to Noki - phonebook might be a nice candidate.

v0.4
There's no UCS2 -> UTF8 convertion now, this feature may add in next release
or when the project need.

Noki'll be be exluded from LuaBit in next release; I decide to let Noki grow
into a powerful tool to support more Nokia PC Suite backup format(.nfb, 
.nfc and .nbu). 

Trial Noki demo at http://nokisms.googlepages.com/(in Chinese)

Known issues
------------
LuaBit doesn't play very well with negative number. The return value of the
bitwise operations might change to positive when applied on negative numbers 
though the bit sequence is correct. So if you want do some arithmetic with
the result of bit operation, be careful.

Feedback
--------
Please send your comments, bugs, patches or change request to 
hanzhao(abrash_han@hotmail.com).
Added more Lua environment features Package library: * Added a simulation of the Lua 5.1 package library. * Removed mw.import(), replaced it with a package loader. Packages can be retrieved from the wiki, using require('Module:Foo'), or from files distributed with Scribunto, using require('foo'). The "Module:" prefix allows for source compatibility with existing Lua code. * Added a couple of libraries from LuaForge: luabit and stringtools. * Made fetchModuleFromParser() return null on error instead of throwing an exception, to more easily support the desired behaviour of the package loader, which needs to return null on error. * Renamed mw.setupEnvironment() to mw.setup() since it is setting up things other than the environment now. * In MWServer:handleRegisterLibrary(), remove the feature which interprets dots in library names, since LuaSandbox doesn't support this. Improved module isolation and related refactoring: * Expose restricted versions of getfenv() and setfenv() to user Lua code. Requires luasandbox r114952. * Don't cache the export list returned by module execution for later function calls. This breaks isolation of #invoke calls, since the local variables are persistent. * Removed ScribuntoFunctionBase and its children, since it doesn't really have a purpose if it can't cache anything. Instead, invoke functions using a module method called invoke(). * Removed Module::initialize(), replaced it with a validate() function. This is a more elegant interface and works better with the new module caching scheme. * Use a Status object for the return value of Engine::validate() instead of an array. Use the formatting facilities of the Status class. Other: * Removed "too many returns" error, doesn't fit in with Lua conventions. * Use the standalone engine by default, so that the extension will work without configuration for more people. * Added an accessor for $engine->interpreter * Fix mw.clone() to correctly clone metatables * If the standalone interpreter exits due to an error, there are some contexts where the initial error will be caught and ignored, and the user will see the error from checkValid() instead. In this case, rethrow the original error for a more informative message. * Load mw.lua into the initial standalone environment, to reduce code duplication between mw.lua and MWServer.lua. * Fixed a bug in Scribunto_LuaStandaloneInterpreter::handleCall() for functions that return no results. * Fixed a bug in encodeLuaVar() for strings with "\r". Added test case. * In MWServer.lua, don't call error() for internal errors, instead just print the error and exit. This avoids a protocol violation when an error is encountered from within handleCall(). * Added lots of documentation. Lua doc comments are in LuaDoc format. Change-Id: Ie2fd572c362bedf02f45d3fa5352a5280e034740 2012-04-18 03:46:18 +00:00			`LuaBit`
			`------`
			`LuaBit is a bitwise operation lib completely written in Lua. It's`
			`written in the belief that Lua is self-contained.`

			`The supported operations are: not, and, or, xor, right shift, logic`
			`right shift and left shift.`

			`Several utilities are designed to leverage the power of bit operation:`
			`1. hex: a dec <-> hex number converter`
			`2. utf8: convert utf8 string to ucs2`
			`3. noki: convert nokia pc suite backuped SMS file to .txt`

			`Under the MIT license.`

			`Visit http://luaforge.net/projects/bit/ to get latest version.`

			`Status`
			`------`
			`Now LuaBit is in v0.4.`
			`Release date: Mar 18, 2007`

			`Content`
			`-------`
			`3 files are there for LuaBit:`
			`1) bit.lua`
			`is the bitwise operation lib, all operations are implemented here.`

			`2) hex.lua`
			`is a helper lib for ease of using hex numbers with bitwise`
			`operation.`

			`3) noki.lua`
			`a utility(based on bit and hex) to convert Nokia PC Suite backuped`
			`SMS to a unicode .txt file, which is more accessible than the`
			`original .nfb or .nfc file.`

			`4) utf8.lua`
			`convert utf8 string to ucs2 string`

			`How to use`
			`----------`
			`Bit`
			`---`
			`Just require 'bit' in your project and the bit lib will be`
			`available:`
			`bit.bnot(n) -- bitwise not (~n)`
			`bit.band(m, n) -- bitwise and (m & n)`
			`bit.bor(m, n) -- bitwise or (m \| n)`
			`bit.bxor(m, n) -- bitwise xor (m ^ n)`
			`bit.brshift(n, bits) -- right shift (n >> bits)`
			`bit.blshift(n, bits) -- left shift (n << bits)`
			`bit.blogic_rshift(n, bits) -- logic right shift(zero fill >>>)`

			`Please note that bit.brshift and bit.blshift only support number within`
			`32 bits.`

			`2 utility functions are provided too:`
			`bit.tobits(n) -- convert n into a bit table(which is a 1/0 sequence)`
			`-- high bits first`
			`bit.tonumb(bit_tbl) -- convert a bit table into a number`

			`Hex`
			`---`
			`For ease of using hex numbers, a utility hex lib is also included in`
			`LuaBit. You can require 'hex' to use them:`
			`hex.to_hex(n) -- convert a number to a hex string`
			`hex.to_dec(hex) -- convert a hex string(prefix with '0x' or '0X') to number`

			`With hex, you can write code like:`
			`bit.band(258, hex.to_dec('0xFF'))`
			`to get the lower 8 bits of 258, that's 2.`

			`Noki`
			`----`
			`require 'noki', to save your sms to .txt file:`
			`noki.save_sms('nokia.nfb', 'sms.txt')`
			`and you can view the output sms.txt in notepad or other editor which`
			`support unicode.`

			`Utf8`
			`----`
			`require 'utf8', to convert a utf8 string:`
			`ucs2_string = utf8.utf_to_uni(utf8_string)`

			`History`
			`-------`
			`v0.4`
			`* utf8 to ucs2 converter(utf8.lua).`
			`* clean up for compatible with Lua5.1 and 5.0.`
			`* add 'How to use' section for bit.lua and hex.lua.`

			`v0.3`
			`* noki added as an application of bit.`
			`* typo correction.`

			`v0.2`
			`* add logic right shift(>>>) support: bit.blogic_rshift.`
			`* add 2 utility functions: bit.tobits and bit.tonumb.`
			`* update hex.to_hex(in hex.lua) to support negative number.`

			`v0.1`
			`LuaBit is written when I do my own game project(Fio at http://fio.edithis.info).`
			`When loading resources, I have to do some bit operation. And I do not`
			`like the embedded way of bit operation. So I decide to implement those`
			`ops in lua. And that's LuaBit. It's not as fast as the embedded one, but`
			`it works. And Lua is self-contained :-)`

			`To-Do List`
			`---------`
			`v0.1`
			`It'll be useful if LuaBit support those bitwise op like:`
			`bit.band(258, '0xFF')`
			`ease to type and use. This will be supported in next release.`

			`v0.2`
			`I decide to delay this feature to later version for it'll mess up the`
			`interface of LuaBit.`

			`v0.3`
			`May more utility functions add to Noki - phonebook might be a nice candidate.`

			`v0.4`
			`There's no UCS2 -> UTF8 convertion now, this feature may add in next release`
			`or when the project need.`

			`Noki'll be be exluded from LuaBit in next release; I decide to let Noki grow`
			`into a powerful tool to support more Nokia PC Suite backup format(.nfb,`
			`.nfc and .nbu).`

			`Trial Noki demo at http://nokisms.googlepages.com/(in Chinese)`

			`Known issues`
			`------------`
			`LuaBit doesn't play very well with negative number. The return value of the`
			`bitwise operations might change to positive when applied on negative numbers`
			`though the bit sequence is correct. So if you want do some arithmetic with`
			`the result of bit operation, be careful.`

			`Feedback`
			`--------`
			`Please send your comments, bugs, patches or change request to`
			`hanzhao(abrash_han@hotmail.com).`