[Phil]

Subject:    compressFlate() on/off parameter
Date:    Tue, 02 Sep 2014 12:05:56 -0400
To:    bug-PDF-API2 [...] rt.cpan.org
 
PDF::API2 v2.022   Perl 5.16.3  Windows 7   severity: Wishlist

Content.pm's compressFlate() method could have an optional parameter to select whether compression is done (default for missing parameter: 1). This would make it easier to output uncompressed PDF for debugging purposes, rather than having to go into internal variables and set them directly.

<formatting cleanup - Mod.>

[Phil]

updated in PDF::API2 release 3.002

Rather than add a parameter to compressFlate(), I added a new %option to new() and open/open_scalar() in API2.pm. The forcecompress setting is still defaulted to 1 (use compressFlate), but option -nocompress can now be used to initialize it to 0 instead (do not use compressFlate, so that the PDF instructions are readable). Places where the following code was used:

Code: [Select]

$pdf = PDF::API2->new();
$pdf->{'forcecompress'} = 0;can now be done in this manner:

Code: [Select]

$pdf = PDF::API2->new('-nocompress' => 1);
The actual value of the nocompress flag should be non-zero.

The "t" tests used forcecompress set to 0 extensively; these have been updated to -nocompress.

Note: this code change has been heavily revised. Please see several posts later for differences.

[sciurius]

$pdf = PDF::API2->new('-nocompress' => 1);

I'd prefer the much more logical

$pdf = PDF::API2->new('-compress' => 0);

[Phil]

I understand your position, and indeed I worried over what to call the new option and what value(s) to recognize. I also tried to keep the actual Perl coding consistent with how other options hashes worked. Because it's a hash, it needs the => value part (not just -nocompress). A value of 1 for flags seems to be the norm. And the normal way of coding the handling of such flags is if ($options{'-flagname'}), which means that a value of 0 is not normally used because it wouldn't be recognized with such code. It came down to having slightly more complex Perl code that wouldn't match all the other flags' coding style.

If you feel very strongly about this, we can discuss it. I just want to have the issue settled before version 3.002 goes out the door (at least a month from now, as a rough guess, depending on what I end up doing with the name constant ~time() issue, and some other minor leftovers from my 3.001 to-do list). Finally, we could consider -flate as the name, although there is still the issue of 0 versus 1 (default).

[sciurius]

It is hardly worth discussing, as long as the intention is clear.
-nocompress => 1 feels like a double negation to me, which may be confusing.
OTOH if the convention is that all options default to zero, then nocompress is the right name.
Of course, it does not require rocket science to add a line

   $options{-nocompress} = !$options->{-compress} if exists $options->{-compress}

A future expansion could then be

  -compress => 'flate' or 'none' or 'lzh' ... etc

[Phil]

A future expansion could then be

  -compress => 'flate' or 'none' or 'lzh' ... etc

Good point. A brief read through the "Filters" spec says that other compressions (other than compressFlate/FlateDecode) are permitted in a PDF. Apparently, each stream could potentially have its own compression setting, but PDF::API2 is currently content to use the same compression for each stream. In the future we could offer a per-stream setting, if that might be useful for some purpose. In the meantime, I will change -compress as you suggest, to allow future specification such as you give. The default would be 'flate', and 'none' will be permitted. In the future, other compressions could be implemented.

[Phil]

I have revised this code change. The new usage is:

Code: [Select]

$pdf = PDF::API2->new('-compress' => 'none');to turn off Flate compression. The default (new()) is

Code: [Select]

$pdf = PDF::API2->new('-compress' => 'flate');
Some time in the future, we may add other compression methods. Currently, only 'none' and 'flate' are supported.

For backwards compatibility, an integer value of 0 is permitted as a synonym for 'none', and an integer greater than 0 is permitted as a synonym for 'flate'. This applies to either the -compress flag, or to direct setting of $options{'forcecompress'}, although the use of 'none' and 'flate' are preferred. It is certainly possible that at some point in the future, the use of integer values will be deprecated.

The "t" tests have been updated to use -compress and 'none'.

[sciurius]

Thanks.

[Phil]

Just to be clear, this feature will be appearing in v3.002, due out shortly.