NAME
Devel::Platform::Match - Match platform information with platform specification
VERSION
This document describes version 0.005 of Devel::Platform::Match (from Perl distribution Devel-Platform-Match), released on 2020-10-09.
SYNOPSIS
use Devel::Platform::Match qw(
match_platform
match_platform_bool
parse_platform_spec
);
# assuming we're on an Ubuntu Linux 20.04 64bit
my $envres = match_platform("osflag=linux"); # -> [200, "OK", 1]
my $envres = match_platform("linux32"); # -> [200, "OK", 0] # linux32 is alias for "osflag=linux archname=x86"; archname doesn't match
my $envres = match_platform("win64"); # -> [200, "OK", 0] # win64 is alias for "osflag=Win32 archname=x86_64"; osflag doesn't match
my $envres = match_platform("osflag=linux oslabel=~/Debian|Ubuntu|Mint/"); # -> [200, "OK", 1]
my $envres = match_platform("osflag=linux, oslabel=~/Debian|Ubuntu|Mint/, osvers >= 21"); # -> [200, "OK", 0] # osvers doesn't match
my $envres = match_platform("foo"); # -> [412, "Invalid syntax in platform spec 'foo'"]DESCRIPTION
This module lets you match platform information with platform specification.
PLATFORM SPECIFICATION SYNTAX
Platform specification syntax is modelled after CSS attribute selector (more specifically, Data::CSel's attribute selector).
Platform specification is a whitespace- (or comma-) separated list of clauses.
Each clause is of the form: key op literal.
key is any key of the hash returned by Devel::Platform::Info.
op is operator supported by Data::CSel.
literal is a bareword number or word, or a quoted string. See Data::CSel for more information.
A platform specification with zero clauses ("") will match all platforms.
For convenience, some aliases will be coerced into a proper platform specification first:
"linux32" => "osflag=linux archname=i686",
"linux64" => "osflag=linux archname=x86_64",
"linux-i386" => "osflag=linux archname=i386",
"linux-i686" => "osflag=linux archname=i686",
"linux-amd64" => "osflag=linux archname=x86_64",
"linux-x86_64" => "osflag=linux archname=x86_64",
"win32" => "osflag=Win32 archname=i686",
"win64" => "osflag=Win32 archname=x86_64",
"all" => "",Some examples of valid and invalid platform specifications:
specification parse result note
------------- ------------ ----
linux32 [["osflag","=","linux"], ["archname","=","x86"]] coerced to "osflag=linux archname=x86" before parsing
oslabel=Ubuntu [["oslabel","=","Ubuntu"]]
osflag=linux oslabel=Ubuntu [["osflag","=","linux"], ["oslabel","=","Ubuntu"]]
osflag=linux, oslabel=Ubuntu [["osflag","=","linux"], ["oslabel","=","Ubuntu"]] either whitespace or comma is okay as separator
oslabel=~/Debian|Ubuntu/ [["oslabel","=~",qr/Debian|Ubuntu/]]
is32bit=1 [["is32bit","=",1]] any 32bit platform
is32bit is true [["is32bit","is",1]] any 64bit platform
"" (empty string) [] no clauses, will match any platform info
foo undef invalid syntax, unknown alias
oslabel=Ubuntu,oslabel=Debian [["osflag","=","Ubuntu"], ["osflag","=","Debian"]] valid, but won't match any platform
archname=amd64 [["archname","=","amd64"]] Will match platform info {archname=>"x86_64"} because of normalizationPLATFORM MATCHING
First, some normalization is performed on the info hash. For archname, "amd64" will be coerced to "x86_64".
Then each clause will be tested. When the hash does not have the key specified in the clause, the test fails.
Platform matches if all clauses pass.
FUNCTIONS
match_platform
Usage:
match_platform($spec, $info, $quiet) -> [status, msg, payload, meta]Match platform information against platform spec.
Examples:
Example #1:
match_platform("osflag=linux", { osflag => "linux", oslabel => "Debian" });Result:
[200, "OK (envelope generated)", 1]
See section "PLATFORM MATCHING" for details on how matching is done.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
$info => hash
Hash(ref) of information returned by Devel::Platform::Info's get_info().
If not specified, will retrieve from Devel::Platform::Info.
$quiet => bool
$spec* => str
Returns an enveloped result (an array).
First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.
Return value: (any)
parse_platform_spec
Usage:
parse_platform_spec($spec) -> arrayParse platform specification string into array of clauses.
Examples:
coercion of alias:
parse_platform_spec("linux32"); # -> undefExample #2:
parse_platform_spec("osflag!=linux"); # -> undefExample #3:
parse_platform_spec("foo"); # -> undef
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
$spec* => str
Return value: (array)
match_platform_bool
Usage:
my $match = match_platform_bool($spec [ , $info [ , $quiet ] ]); # -> boolJust like "match_platform" but return a simple boolean value.
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Devel-Platform-Match.
SOURCE
Source repository is at https://github.com/perlancar/perl-Devel-Platform-Match.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Devel-Platform-Match
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
SEE ALSO
App::PlatformMatchUtils provides CLI's for "parse_platform_spec" and "match_platform".
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.