libfalcon-engine1 0.9.6.9-git20120606-2.1+b1 / usr / lib / falcon / img / qrcode.fal

/*
   FALCON - The Falcon Programming Language.
   FILE: qrcode.fal

   QR-Code library front end.
   -----------------------------------------------------------------------------
   Author: Giancarlo Niccolai & Giuseppe Greco
   Begin:Wed, 27 Oct 2010 21:51:41 +0200

   -----------------------------------------------------------------------------
   (C) Copyright 2010: the FALCON developers (see list in AUTHORS file)

   See LICENSE file for licensing details.
*/

import from self.lib in qr

/*# @main QR-Code generator module.

   This module exposes two classes (@a Maker and @a Image) that are meant to
   create QR-Code images.

   QR-Code is a sort of barcode that can store binary and text information on
   paper or screen devices, and can be read back with optical devices.

   QR-Code is a patent held by
   @link http://www.denso-wave.com/qrcode/index-e.html "Denso wave",
   but is released free of charge for everyone to use.

   A minimal sample program may be:

   @code
   import from img.qrcode in qr

   // Generates a QR Code image with a utf-8 encded text
   img = qr.Maker().text("Hello world", qr.ECL.L, "utf-8")

   // Save it as a PNG with 3 pixels per bit and 2 pixels of white border.
   img.savePng("hello.png", 3, 2)
   @endcodce

   The library has support for dumping the image directly to an arbitrary stream
   (and so, for example, generating a live document on a web server).

   The code of this library is heavily based on
   @link "http://fukuchi.org/works/qrencode/index.en.html" "Lib QR Encode".
*/

// workaround to circumvent error in module loader
QrMask = qr.QrMask

/*# Error correction level enumeration.
   Sets the trade off between generation complexity and scan readability.

   Can be one of:
   - **L**: Low correction
   - **M**: Medium correction
   - **Q**: Medium-high correction
   - **H**: High correction.
*/
ECL = qr.QrEcl

/*# QR-Code generator.

   This class provides functionality for creating QR-Code images.

   The class instance is used to generate one or more @a Image instances,
   which are the actual content that can be streamed to a target file or to
   an arbitrary stream.
*/
class Maker
   /*# Cache directory -- set to nil to disable caching.
   */
   cache_dir = nil

   /*#
   * Encoding of final output.
   */
   encoding = "utf-8"

   /*# Specifies whether or not to estimate best mask.
   *
   * Set this attribute to false if performance is an issue.
   */
   find_best_mask = true

   /*# The number of masks to be checked -- mask ids are generated randomly.
   */
   find_from_random = 0

   /*# Default mask.
   *
   * Only used when best mask estimation is disabled.
   */
   default_mask = 2

   /*# Max width (in pixels) allowed for png images.
   */
   png_max_size = 1024

   /*# Encodes raw binary data.
      @param data The text to be encoded.
      @optparam ecl The error correction level (defaults to ECL.L).

      @see Maker.ECL
   */
   function encodeBin(data, ecl)
      input = self._getInput(ecl)
      input.append(qr.QrMode.Bin, len(data), data)
      return self._encodeInput(input)
   end

   /*# Encodes a text string.
      @param text The text to be encoded.
      @optparam ecl The error correction level (defaults to ECL.L).
      @optparam encoding Optional text encoding for the final output.
      @optparam caseSensitive Set to false to create alphanumeric sequences.

      @see Maker.ECL
   */
   function encodeText(text, ecl, encoding, caseSensitive)
      if encoding == nil: encoding = self.encoding
      if caseSensitive == nil: caseSensitive = true

      if encoding
         text = transcodeTo(text, encoding)
      end

      input = self._getInput(ecl)
      qr.QrSplit.splitStringToInput(text, input, qr.QrMode.Bin, caseSensitive)
      return self._encodeInput(input)
   end

   function encodeNum(data, ecl)
      raise qr.QrError(qr.QrError.functionality_not_supported, "encodeNum")
   end

   function encodeAn(data, ecl)
      raise qr.QrError(qr.QrError.functionality_not_supported, "encodeAn")
   end

   function encodeKanji(data, ecl)
      raise qr.QrError(qr.QrError.functionality_not_supported, "encodeKanji")
   end

   function encodeStruct(data, ecl)
      raise qr.QrError(qr.QrError.functionality_not_supported, "encodeStruct")
   end

   /*# @private */
   function _getInput(ecl)
      if ecl == nil: ecl = qr.QrEcl.L
      if ecl < qr.QrEcl.L or ecl > qr.QrEcl.H
         raise qr.QrError(qr.QrError.invalid_ecl, @i"$(ecl) is not supported")
      end

      return qr.QrInput(0, ecl)
   end

   /*# @private */
   function _encodeInput(input, maskNo)
      if maskNo == nil: maskNo = -1

      spec = qr.QrSpec()
      raw = qr.QrRawCode(input)
      version = raw.version
      width = spec.getWidth(version)
      frame = spec.createFrame(version, self.cache_dir)

      if (filler = qr.QrFrameFiller(width, frame)) == nil
         raise qr.QrError(qr.QrError.encoding_error, i"error creating frame filler")
      end

      // cache function references to improve performance 
      funcGetCode = raw.getCode
      funcNext = filler.next
      funcSetFrameAt = filler.setFrameAt

      for i in [0:raw.dataLength + raw.eccLength]
         code = funcGetCode()
         bit = 0x80
         for j in [0:8]
            addr = funcNext()
            funcSetFrameAt(addr, 0x02 || ((bit && code) != 0 ? 1 : 0))
            bit >>= 1
         end
      end; raw = nil

      for i in [0:spec.getRemainder(version)]
         addr = funcNext()
         funcSetFrameAt(addr, 0x02)
      end

      frame = filler.frame
      maskObj = qr.QrMask(self)

      if maskNo < 0
         if self.find_best_mask
            masked = maskObj.mask(width, frame, input.ecl)
         else
            masked = maskObj.createMask(width, frame, self.default_mask % 8, input.ecl)
         end
      else
         masked = maskObj.createMask(width, frame, maskNo, input.ecl)
      end

      if masked == nil
         raise qr.QrError(qr.QrError.encoding_error, i"error masking frame")
      end

      return Image(version, width, masked, self)
   end
end

/*# Class representing a QR-Code image.
   @param version The version of this QR-Code image.
   @param width The width of this QR-Code image.
   @param data Raw binary data.
   @param maker The maker that built this Image (used for configuration).

   @note This class should not be instanced directly; it should be created
         trhough the @a Maker methods.

   This class contains the data that can be rendered to an output image.

   @prop version (read only) The version of this QR-Code image (indicating its
         complexity and data size).
   @prop width Size in read points of this image.
*/
class Image(version, width, data, maker)
   _version = version
   _width = width
   _code = data
   _maker = maker
   _binarized = nil

   /*# Saves the image on the given file as a JPG image.
      @param filename The file where the image will be saved.
      @optparam size Size of dots, in pixels.
      @optparam margin Size of the white margin around the image, in pixels.
      @raise IoError i/o on error.
   */
   function saveJpg(filename, size, margin)
      self._saveImage(qr.QrImage.jpg, filename, size, margin)
   end

   /*# Saves the image on the given file as a PNG image.
      @param filename The file where the image will be saved.
      @optparam size Size of dots, in pixels.
      @optparam margin Size of the white margin around the image, in pixels.
      @raise IoError i/o on error.
   */
   function savePng(filename, size, margin)
      self._saveImage(qr.QrImage.png, filename, size, margin)
   end

   /*# Writes the image to the given stream as a JPG image.
      @param outStream The stream where the image will be written.
      @optparam size Size of dots, in pixels.
      @optparam margin Size of the white margin around the image, in pixels.
      @raise IoError on i/o error.
   */
   function writeJpg(outStream, size, margin)
      self._writeImage(qr.QrImage.jpg, outStream, size, margin)
   end

   /*# Writes the image to the given stream as a PNG image.
      @param outStream The stream where the image will be written.
      @optparam size Size of dots, in pixels.
      @optparam margin Size of the white margin around the image, in pixels.
      @raise IoError on i/o error.
   */
   function writePng(outStream, size, margin)
      self._writeImage(qr.QrImage.png, outStream, size, margin)
   end

   function __get_version()
      return self._version
   end

   function __get_width()
      return self._width
   end

   /*# @private */
   function _writeImage(func, outStream, size, margin)
      if not self._binarized: self._binarized = qr.QrTools.binarize(self._code)
      maxSize = int(self._maker.png_max_size / (len(self._code) + 2 * margin))
      func(self._binarized, outStream, min(max(1, size), maxSize), margin)
   end

   /*# @private */
   function _saveImage(func, filename, size, margin)
      stream = OutputStream(filename)

      try
         self._writeImage(func, stream, size, margin)
         stream.close()
      catch in error
         stream.close()
         raise error
      end
   end
end