NAME

Image::Magick::CommandParser - Parse any command line acceptable to convert or mogrify

Synopsis

This is scripts/synopsis.pl:

#!/usr/bin/env perl

use strict;
use warnings;
use warnings qw(FATAL utf8);

use Image::Magick::CommandParser;

# ----------------------------------------------

my($command)	= 'convert colors/*s*.png -append output.png';
my($processor)	= Image::Magick::CommandParser -> new
(
	command		=> $command,
	maxlevel	=> 'notice',
);

$processor -> run;

print 'Input:  ', $command, "\n";
print 'Result: ', $processor -> result, "\n";

With its output (after running in the distro dir, with access to colors/*.png):

Input:  convert colors/*s*.png -append output.png
Result: convert colors/fuchsia.png colors/silver.png -append output.png

Description

Image::Magick::CommandParser is a stand-alone parser for command lines acceptable to the Imagemagick programs convert and mogrify.

It aims to handle all constructs supported by Imagemagick itself, but it's vital to understand that this module does not use any component of Imagemagick. Hence the stand-alone just above.

In particular the output is a stack, accessible via the $object -> stack method, which returns an array of hashrefs.

The stack is managed by an object of type Set::Array. See the "FAQ" for details.

The result - as a space-separated string of tokens detected in the command - is returned by "result()".

The actual parsing is done with Set::FA::Element.

Consult the "FAQ" and t/test.t for specific examples of command line options supported. A few of them are included here:

o All command options of the form [-+][a-zA-Z]+

o Redirecting input from files

o convert magick:rose -label @t/label.1.txt -format "%l label" rose.png

o File globbing

o convert colors/*s*.png -append output.png

o Explicit image format

o convert rgb:camera.image -size 320x85 output.png

o Built-in images and patterns

o convert pattern:bricks -size 320x85 output.png

o Standard input and output

o convert gif:- -size 320x85 output.png
o convert magick:logo -size 320x85 gif:-

o File handle numbers

o convert fd:3 png:fd:4 gif:fd:5 fd:6 -append output.png

o The apparently endless variations of the geometry parameter

Samples:

o 320x85
o 50%
o 60%x40
o 320x85+0+0
o 60x40%+0+0
o 50%!+0+0

o Built-in special files

Samples:

o logo:
o magick:rose

o Output label format strings

o convert magick:rose -label "%wx%h" -format "%l label" rose.png

o The image stack and cloning

o convert label.gif ( +clone -shade 110x90 -normalize -negate +clone -compose Plus -composite ) button.gif
o convert label.gif +clone 0,4,5 button.gif

Imagemagick has a web page, http://imagemagick.org/script/command-line-processing.php, dedicated to the features available in its command line processing code. Please report any cases where this module does not support one of those features. But see "Trouble-shooting" before reporting an issue, since there I list a few special cases.

Installation

Install Image::Magick::CommandParser as you would for any Perl module:

Run:

cpanm Image::Magick::CommandParser

or run:

sudo cpan Image::Magick::CommandParser

or unpack the distro, and then:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

Constructor and Initialization

Call new() as my($parser) = Image::Magick::CommandParser -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type Image::Magick::CommandParser.

Key-value pairs accepted in the parameter list (see also the corresponding methods [e.g. "command([$string])"]):

o command => $string

The command string to process.

Default: ''.

o logger => $logger_object

Specify a logger object.

The default value triggers creation of an object of type Log::Handler which outputs to the screen.

To disable logging, just set logger to the empty string.

Default: undef.

o maxlevel => $level

This option is only used if an object of type Log::Handler is created. See logger above.

Methods

command([$string])

Here, the [] indicate an optional parameter.

Get or set the command line string to be processed.

log($level, $s)

Calls $self -> logger -> log($level => $s) if ($self -> logger).

logger([$logger_object])

Here, the [] indicate an optional parameter.

Get or set the logger object.

To disable logging, just set logger to the empty string.

This logger is passed to GraphViz2.

Note: logger is a parameter to new().

maxlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

This option is only used if an object of type Log::Handler is created. See Log::Handler::Levels.

Note: maxlevel is a parameter to new().

minlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

This option is only used if an object of type Log::Handler is created. See Log::Handler::Levels.

Note: minlevel is a parameter to new().

new()

The constructor. See "Constructor and Initialization".

result()

Returns a string of space-separated tokens, as output by the parser.

There is result() in its entirety:

sub result
{
	my($self) = @_;

	return join(' ', map{$$_{token} } $self -> stack -> print);

} # End of result.

run()

Returns 0 for success and 1 for failure.

Run the parser on the command provided by new(command => '...') or provided by calling "command([$string])" before calling run().

If the return value is 0, call "result()" to get a string corresponding to the input, or process the stack directly by calling "stack()".

Globs etc in the input will be represented by multiple items in the stack.

stack()

This returns an object of type Set::Array, which you can use to iterate over the items output by the parser.

See "result()" just above for how to use this object.

FAQ

What is the format of stack items?

They are hashrefs, with these keys:

o token

This is the token extracted from the command line.

Note: In the cases of file globbing and redirection of input from a file, these tokens are after expansion of such items.

o type

This is my classification of the type of token detected. The values taken by type are:

o action
o close_parenthesis
o command
o done: In this case, the token will be the empty string.
o input_file: This is used for both explicit file names and for each file name produced by expanding globs.
o open_parenthesis
o output_file
o operator
o parameter

Why do you use pairs of states such as 'action' and 'action_1'?

The way Set::FA::Element was designed, it will not move from a state to the same state when the input matches. So, to trigger the entry or exit subs, I have to rock back-and-forth between 2 states which are more-or-less identical.

Trouble-shooting

Installation failure

I had a failure when installing the module on my laptop for the 1st time. The problem was that, somehow, during the installation of Image::Magick, root had become the owner of a directory under the control of perlbrew. To fix this, I had to do:

sudo chown ron:ron /home/ron/perl5/perlbrew/perls/perl-5.20.2/lib/site_perl/5.20.2/x86_64-linux/auto/Image/Magick

Regions specified as '@100000' are not supported

So, you must put the '@' at the end of the region:

convert magick:logo -resize '10000@' wiz10000.png

Frame references are not supported

So, this won't work:

convert 'images.gif[0]' image.png

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Repository

https://github.com/ronsavage/Image-Magick-CommandParser

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=Image::Magick::CommandParser.

Author

Image::Magick::CommandParser was written by Ron Savage <ron@savage.net.au> in 2016.

My homepage: http://savage.net.au/

Copyright

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Perl License, a copy of which is available at:
http://dev.perl.org/licenses/

To install Image::Magick::CommandParser, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Image::Magick::CommandParser

CPAN shell

perl -MCPAN -e shell
install Image::Magick::CommandParser

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Synopsis

Description

Installation

Constructor and Initialization

Methods

command([$string])

log($level, $s)

logger([$logger_object])

maxlevel([$string])

minlevel([$string])

new()

result()

run()

stack()

FAQ

What is the format of stack items?

Why do you use pairs of states such as 'action' and 'action_1'?

Trouble-shooting

Installation failure

Regions specified as '@100000' are not supported

Frame references are not supported

See Also

Machine-Readable Change Log

Version Numbers

Repository

Support

Author

Copyright

Module Install Instructions