Back to...

   1  --  LZMA.Decoding - a standalone, generic LZMA decoder.
   2  -----------------
   3  --
   4  --  Based on a translation of LzmaSpec.cpp, the LZMA Reference Decoder, by Igor Pavlov.
   5  --  Further rework documented in body.
   6  
   7  --  Examples of use:
   8  --    LZMA_Dec, a standalone decoder for .lzma files
   9  --    UnZip.Decompress, extracts Zip files entries with, among others, LZMA encoding
  10  
  11  --  Legal licensing note:
  12  
  13  --  Copyright (c) 2014 .. 2019 Gautier de Montmollin (maintainer of the Ada version)
  14  --  SWITZERLAND
  15  
  16  --  Permission is hereby granted, free of charge, to any person obtaining a copy
  17  --  of this software and associated documentation files (the "Software"), to deal
  18  --  in the Software without restriction, including without limitation the rights
  19  --  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  20  --  copies of the Software, and to permit persons to whom the Software is
  21  --  furnished to do so, subject to the following conditions:
  22  
  23  --  The above copyright notice and this permission notice shall be included in
  24  --  all copies or substantial portions of the Software.
  25  
  26  --  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  27  --  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  28  --  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  29  --  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  30  --  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  31  --  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  32  --  THE SOFTWARE.
  33  
  34  --  NB: this is the MIT License, as found on the site
  35  --  http://www.opensource.org/licenses/mit-license.php
  36  
  37  generic
  38    --  Input:
  39    with function Read_Byte return Byte;
  40    --  Output:
  41    with procedure Write_Byte (b : Byte);
  42  
  43  package LZMA.Decoding is
  44  
  45    type LZMA_Result is (
  46      LZMA_finished_with_marker,
  47      LZMA_finished_without_marker
  48    );
  49  
  50    --  The passing of the uncompressed data size follows very
  51    --  confusing rules in the LZMA format. If you have a noiseless
  52    --  data transmission it is better to bypass any size check,
  53    --  by using a End-Of-Stream marker (marker_expected = True on the decoder
  54    --  side below: type LZMA_Hints) and *not* giving any hardcoded
  55    --  size (has_size = False), and keeping given_size = dummy_size (default).
  56  
  57    dummy_size : constant Data_Bytes_Count := Data_Bytes_Count'Last;
  58  
  59    --  The hints represent knowledge prior to decompressing a LZMA
  60    --  stream. Notably, the LZMA header with has_size = True is *not*
  61    --  compatible with the LZMA header with has_size = False.
  62    --
  63    type LZMA_Hints is record
  64      has_size               : Boolean;         --  Is size is part of header data ?
  65                                                --  In LZMA.Encoding.Encode: uncompressed_size_info.
  66      given_size             : Data_Bytes_Count --  If has_size = False, we use given_size.
  67                                := dummy_size;
  68      marker_expected        : Boolean;         --  Is an End-Of-Stream marker expected ?
  69      fail_on_bad_range_code : Boolean;         --  Raise exception if range decoder corrupted ?
  70      --  The LZMA specification is a bit ambiguous on this point: a decoder has to ignore
  71      --  corruption cases, but an encoder is required to avoid them...
  72    end record;
  73  
  74    ----------------------------------------------------------------------------------
  75    --  Usage #1 : Object-less procedure, if you care only about the decompression  --
  76    ----------------------------------------------------------------------------------
  77  
  78    procedure Decompress (hints : LZMA_Hints);
  79    --  The parameter hints.has_size must have the same value as
  80    --  uncompressed_size_info in LZMA.Encoding.Encode: there are unfortunately
  81    --  two incompatible LZMA header variants: one including uncompressed
  82    --  data size, and one without that size.
  83    --  Note that hints.has_size = uncompressed_size_info = True for .lzma files.
  84  
  85    ---------------------------------------------------------------------------
  86    --  Usage #2 : Object-oriented, with stored technical details as output  --
  87    ---------------------------------------------------------------------------
  88  
  89    type LZMA_Decoder_Info is limited private;
  90    procedure Decode (info : out LZMA_Decoder_Info; hints : LZMA_Hints; res : out LZMA_Result);
  91  
  92    --  The technical details:
  93    function Literal_context_bits (info : LZMA_Decoder_Info) return Natural;
  94    function Literal_pos_bits (info : LZMA_Decoder_Info) return Natural;
  95    function Pos_bits (info : LZMA_Decoder_Info) return Natural;
  96  
  97    function Unpack_size_defined (info : LZMA_Decoder_Info) return Boolean;
  98    function Unpack_size_as_defined (info : LZMA_Decoder_Info) return Data_Bytes_Count;
  99    --  Sizes in bytes:
 100    function Probability_model_size (info : LZMA_Decoder_Info) return Interfaces.Unsigned_32;
 101    function Dictionary_size (info : LZMA_Decoder_Info) return Interfaces.Unsigned_32;
 102    function Dictionary_size_in_properties (info : LZMA_Decoder_Info) return Interfaces.Unsigned_32;
 103    --
 104    function Range_decoder_corrupted (info : LZMA_Decoder_Info) return Boolean;
 105  
 106    LZMA_Error : exception;
 107  
 108  private
 109  
 110    type LZMA_Decoder_Info is record
 111      unpackSize            : Data_Bytes_Count;
 112      unpackSize_as_defined : Data_Bytes_Count;
 113      unpackSizeDefined     : Boolean;
 114      markerIsMandatory     : Boolean;
 115      dictionary_size       : UInt32;
 116      dictSizeInProperties  : UInt32;
 117      lc                    : Literal_Context_Bits_Range;   -- number of "literal context" bits
 118      lp                    : Literal_Position_Bits_Range;  -- number of "literal pos" bits
 119      pb                    : Position_Bits_Range;          -- number of "pos" bits
 120      range_dec_corrupted   : Boolean;
 121    end record;
 122  
 123  end LZMA.Decoding;