= LuaSrcDiet
:toc: macro
:toc-title:
:proj-name: luasrcdiet
:gh-name: jirutka/{proj-name}
:gh-branch: master
:ldoc-url: https://jirutka.github.io/{proj-name}/ldoc/

ifdef::env-github[]
image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}["Build Status", link="https://travis-ci.org/{gh-name}"]
image:https://img.shields.io/badge/ldoc-docs-blue.svg["LDoc", link="{ldoc-url}"]
endif::env-github[]


Compresses Lua source code by removing unnecessary characters.

This is revival of LuaSrcDiet originally written by mailto:keinhong@gmail.com[Kein-Hong Man].


[discrete]
== Table of Contents

toc::[]


== Introduction

LuaSrcDiet is a utility written in Lua for the purpose of turning Lua 5.1+ source code like this:

[source, lua]
----
local function calc_indent(s)
  local col = 0
  for i = 1, #s do
    local c = sub(s, i, i)
    col = col + 1
    if c == "\t" then  -- tab
      while col % 8 > 0 do col = col + 1 end
    end
  end--for
  return math.floor(col / 8)
end
----

into a more compact or “squeezed” form (minus a lot of unnecessary characters) like this:

[source, lua]
----
local function _(l)local e=0
for o=1,#l do
local n=n(l,o,o)e=e+1
if n=="\t"then
while e%8>0 do e=e+1 end
end
end
return r.floor(e/8)end
----

and still be able to run normally under standard Lua 5.1+ or LuaJIT 2.0+.

LuaSrcDiet reduces the size of https://www.lua.org/[Lua] 5.1+ source files by aggressively removing all unnecessary whitespace and comments, optimizing constant tokens, and renaming local variables to shorter names.
For example, LuaSrcDiet squeezes its own sources from 156 kiB down to 42 kiB.
Further bzip2 or lzma compression can bring the file size further down to under 13 kiB.
That’s _12×_ reduction in size, if you don’t mind the decompression and compilation time.

LuaSrcDiet is broadly similar to Luiz’s http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/5.1/lstrip.tar.gz[lstrip] (tar.gz) for Lua 5.1, which can be found on Luiz’s http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/[Libraries and tools for Lua] page.
LuaSrcDiet with its modified Lua source code lexer and parser allows most optimization options to be enabled or disabled separately, and can do a bit more like renaming local variable names.

There is also Matthew Wild’s http://matthewwild.co.uk/projects/squish/home[squish], which incorporates LuaSrcDiet and offers more code compression options.
Squish goes beyond what LuaSrcDiet does, as the latter (as a matter of policy) only sticks to source code readable by standard Lua binaries.


== LuaSrcDiet and Obfuscation

Owing to the use of LuaSrcDiet among certain things like WoW add-ons, the following is a clarification of this author’s intentions:

* LuaSrcDiet can be used as a _weak_ obfuscator.
  However, note that the structure and arrangement of the source code stays exactly the same, so _do not_ depend on such a weak form of obfuscation if you really needed heavy-duty obfuscation.
* LuaSrcDiet was written for the purpose of comparing minimum-sized sources with binary chunks, their compressibility, and the parsing performance of the Lua interpreter.
  I don’t care one iota about obfuscation, it’s compression I’m interested in.
* This is _experimental software_.
  If you want to use it for important stuff, be sure to apply source and binary equivalence checking.
  I’m not, of course, responsible for anything you do.
* Treat it like a text filter tool or a compiler.
  There is no legal requirement to acknowledge LuaSrcDiet or to place its copyright notice anywhere for the source code you processed.
  Your app is stuff _you_ wrote, LuaSrcDiet is stuff _I_ wrote.
  Simples.
* Obfuscation cannot be defined precisely so we are dealing with subjective judgements.
  I think it’s fair if people want to apply a mild deterrent against casual plagiarism.
  Those desperate for original sources should instead turn their energies towards Open Source or Free Software.


== Changes in This Fork

* Code-base updated to be compatible with Lua 5.1–5.3.
* Added support for processing Lua 5.2–5.3 code (except binary equivalence checking).
* Published on https://luarocks.org/[LuaRocks] (the Lua package manager).
* Documentation comments converted to https://github.com/stevedonovan/LDoc[LDoc’s] format (except lparser.lua).
* Documentation wiki pages converted to AsciiDoc.


== Installation

Note: If you want to bootstrap development environment for running tests, read the next section.


=== Using LuaRocks

You can install {proj-name} using https://luarocks.org[LuaRocks] (the Lua package manager):

[source, subs="+attributes"]
luarocks install {proj-name}

or to get the latest development version:

[source, subs="+attributes"]
luarocks install --server=http://luarocks.org/dev {proj-name}


== Set Up Development Environment

. Clone this repository:
[source, subs="+attributes"]
git clone https://github.com/{gh-name}.git
cd {proj-name}

. Source file `.envrc` into your shell (or manually add `$(pwd)/.venv/bin` to your `PATH`):
[source]
source .envrc

. Install Lua and modules for running tests into directory `.venv`:
[source]
./script/bootstrap

. Start hacking!

. Run linters and tests:
[source]
./script/test


== Documentation

* <<doc/features-and-usage#, Features and Usage>>
* <<doc/performance-stats#, Performance Statistics>>
* <<doc/tech-notes#, Technical Notes>>


== Acknowledgements

* The original author of LuaSrcDiet and its documentation is mailto:keinhong@gmail.com[Kein-Hong Man].
  History of this repository until 2012 has been recreated from https://code.google.com/archive/p/luasrcdiet/downloads[release tarballs] hosted on Google Code.
* Parts of LuaSrcDiet is based on http://yueliang.luaforge.net/[Yueliang], which is in turn based on the https://www.lua.org/[Lua] sources.


== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:COPYRIGHT[COPYRIGHT] file.