First version, only decoder

Author: Egor-Skriptunoff

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 
+Copyright (c) 2017 Egor Skriptunoff 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,36 @@
 # pure_lua_GIF
+
 GIF decoder in pure Lua
+
+### Installation
+
+Just copy "gif.lua" to Lua modules' folder.
+
+### Decoding
+
+```lua
+local filename = "SOME_PICTURE.gif"
+
+-- Open GIF file as read-only
+local gif = require'gif'(filename)
+
+-- Extract some information about this GIF
+local w, h = gif.get_width_height()
+print('Picture dimensions: '        ..w..' x '..h)
+print('Number of animation frames: '..gif.get_file_parameters().number_of_images)
+print('Comment inside this GIF: '   ..(gif.get_file_parameters().comment or 'NO_COMMENT'))
+
+-- Get the color of pixel with coordinates (2,0)
+local matrix = gif.read_matrix()   -- first animation frame of this GIF as 2D-matrix of colors
+local row = 1    -- top row of the picture
+local col = 3    -- third pixel from the left
+local color = matrix[row][col]
+if color == -1 then
+   print("This pixel is transparent")
+else
+   print(("The color of this pixel in hexadecimal RRGGBB format is %06X"):format(color))
+end
+
+-- Close GIF file
+gif.close()
+```

example.lua

@@ -0,0 +1,38 @@
+-- Example of non-animated gif:
+local filename = "mini-graphics-ducks-425811.gif"
+-- This .GIF was downloaded from:
+-- http://www.picgifs.com/mini-graphics/mini-graphics/ducks/mini-graphics-ducks-425811.gif
+
+--[[
+-- Example of animated gif:
+local filename = "mini-graphics-cats-864491.gif"
+-- This .GIF was downloaded from:
+-- http://www.picgifs.com/mini-graphics/mini-graphics/cats/mini-graphics-cats-864491.gif
+--]]
+
+local gif = require'gif'(filename)
+local w, h = gif.get_width_height()
+print('Picture dimensions: '..w..' x '..h)
+print('Total Frames: '..gif.get_file_parameters().number_of_images)
+print('Comment: '..(gif.get_file_parameters().comment or 'NO_COMMENT'))
+print('Looped: '..(gif.get_file_parameters().looped and 'YES' or 'NO'))
+repeat
+   local image_no = gif.get_image_parameters().image_no
+   print("Frame #"..image_no)
+   local m = gif.read_matrix()
+   -- Print the matrix for this frame
+   for row = 1, #m do
+      local r = {}
+      for col = 1, #m[1] do
+         local color = m[row][col]
+         if color == -1 then  -- Transparent color
+            color = "------"
+         else                 -- Non-transparent color in 0xRRGGBB format
+            color = ("%06X"):format(color)
+         end
+         table.insert(r, color)
+      end
+      print(table.concat(r, "  "))
+   end
+until not gif.next_image()  -- try to switch to next animation frame
+gif.close()