1Syntax(3)             User Contributed Perl Documentation            Syntax(3)
2
3
4

NAME

6       License::Syntax - Coding and Decoding of License strings using SPDX and
7       SUSE syntax.
8

VERSION

10       Version 0.13
11

SYNOPSIS

13       This implements the SUSE License Syntax.
14
15           use License::Syntax;
16
17           my $obj = new License::Syntax licensemap => 'licenselist.csv;as';
18           my $obj = new License::Syntax map => { 'GNU General Public License V2.0' => 'GPLv2' };
19           my $obj = new License::Syntax 'pathname.sqlite;table(alias,name)';
20           $obj->loadmap_csv($filename_csv);
21           $obj->loadmap_sqlite($filename_sqlite, $table_name, $alias_col, $name_col);
22           $obj->savemap_csv($filename_csv, scalar(localtime));
23           $obj->savemap_sqlite($filename_sqlite, $table_name, $alias_col, $name_col, 'TRUNCATE');
24           $obj->add_alias($alias, $canonical_name);
25           $name = $obj->canonical_name($alias, $disambiguate);
26           $tree = $obj->tokenize('GPLv2 & Apache 1.1; LGPLv2.1 | BSD4c<<ex(UCB); Any Noncommercial', $disambiguate);
27           $name = $obj->format_tokens($tree);
28

FUNCTIONS

30   new
31       License::Syntax is an object oriented module.  When constructing new
32       License::Syntax objects, you can provide a mapping table for license
33       names. The table is used for recognizing alternate alias names for the
34       licenses (left hand side) and also defines the canonical short names of
35       the licenses (right hand side).  The mapping table is consulted twice,
36       before and after decoding the syntax.  (Thus non-terminal mappings may
37       actually be followed.)
38
39       The mapping table can be provided either
40
41       • as a CSV files of two columns. Column seperator is a comma (,)
42
43       • as a hash, or
44
45       • as table in an sqlite database using the given columns as left hand
46         side and right hand side respectivly.
47
48       As an alternative to specifying a mapping with new(), or additionally,
49       mappings can also be provided via loadmap_sqlite(), loadmap_csv(), or
50       add_alias() methods. Earlier mappings take precedence over later
51       mappings.
52
53   canonical_name
54           $name = $obj->canonical_name($alias);
55       is equivalent to
56           $name = $obj->format_tokens($obj->tokenize($alias));
57
58   savemap_csv
59       $obj->savemap_csv('filename.csv', scalar(localtime));
60
61       Writes the current mapping table as a comma seperated file.
62
63   set_rejects
64       $obj->set_rejects('REJECT', ...);
65
66       define the license names to be rejected. Per default, exactly one name
67       'REJECT' is rejected.
68
69   add_alias
70       $obj->add_alias($alias,$name); $obj->add_alias(undef,$name);
71       $obj->add_alias('',$name);
72
73       adds $name (and optionally $alias) to the objects licensemap.  Both,
74       lower case and exact mappings are maintained.  (add_url is used in
75       loadmap_csv)
76
77       add_alias() takes care to extend to the right. That is, if it's right
78       hand side parameter is already known to be an alias, the new alias is
79       added pointing to the old alias's canonical name (rahter than to the
80       old alias that the caller provided).
81
82       CAVEAT: add_alias() does not maintain full tranitivity, as it does not
83       extend to the left.  If its left hand side is already known to be a
84       canonical name, a warning is issued, but the situation cannot be
85       corrected, as this would require rewriting existing entries. This is
86       non-obvious, as mappings are applied more than once during
87       format_tokens(), so indirect mappings involving non-terminal names, may
88       or may not work. A two step mapping currently works reliably, though.
89
90       add_alias() does nothing, if it would directly redo an existing
91       mapping.
92
93       See also new() for more details about mappings.
94
95   add_url
96       $obj->add_url($urls, $name);
97
98       Add one or multiple URLs to the canonical license name. URLs can be
99       seperated by comma or whitespace.  May be called multiple times for the
100       same name, and fills an array of urls.  (add_url is used in
101       loadmap_csv)
102
103   set_compat_class $obj->set_compat_class($cc, $name);
104       Specify the compatibility class, for a canonical license name.
105       compatibility classes are numerical. These classes allow to derive
106       certain compatibility issues amongst liceses. Some classes are always
107       incompatible (even amongst themselves), other classes are always
108       comaptible, and for some other classses, compatibility is uncertain.
109       The exact semantics are to be defined.  (set_compat_class is used in
110       loadmap_csv).
111
112   savemap_sqlite
113       $obj->savemap_sqlite('filename.sqlite', 'lic_map', 'alias',
114       'shortname', $trunc_flag);
115
116               # sqlite3 filename.sqlite
117               sqlite> select * from lic_map
118               alias | shortname
119               ------|----------
120               ...
121
122       If $trunc_flag is true and the table previously exists, the table is
123       truncated before it is written to; otherwise new contents merges over
124       old contents, if any.
125
126   loadmap_sqlite
127       See also new() for more details about mappings.
128
129   tokenize
130       $tree_arr = $obj->tokenize($complex_license_expr); $tree_arr =
131       $obj->tokenize($complex_license_expr, 1);
132
133       Returns an array reference containing tokens and sub-arrays, describing
134       how the $complex_license_expr is parsed.  If a second parameter
135       disambiguate is provided and is true, extra parenthesis are inserted to
136       unambiguiusly show how the complex expression is interpreted.  If names
137       have been loaded with add_alias, before calling tokenize, all names and
138       aliases are recognized as one token. E.g. "GPL 2.0 or later" would be
139       split as ["GPL 2.0", "or", "later"] otherwise.  No name mapping is
140       performed here.
141
142   format_tokens
143       reverse operation of tokenize()
144
145   loadmap_csv
146       $obj->loadmap_csv('license_map.csv', 'as');
147       $obj->loadmap_csv('synopsis.csv', 'lauaas#c');
148
149       Object method to load (or merge) contents of a CVS table into the
150       object.  This uses a trivial csv parser. Field seperator must be ;
151       linebreaks are record seperators, and the first line is ignored, if it
152       starts with '#'.  Fields can be surrounded by doublequotes, if a comma
153       may be embedded.
154
155       The second parameter is a field template, defining what the meaning of
156       the fields is.
157        l    Long name (none or once). This is a speaking name of the License:
158       Example "Creative Commons Attribution 1.0"
159        a    Alias name (any number). Any other name by which the license is
160       known: Example: "CC-BY 1.0"
161        s    Short name (once). The canonical (unique) short license
162       identifiner: Example: "CC-BY-1"
163        u    URL (any). Multiple URLs can also be written in one filed,
164       seperated by whitespace.
165        #    License classification number (none or once). (1..5)
166        c    Comment (none or once) The default template is "as", an alias,
167       followed by the canonical short name.  Empty fields are ignored, as
168       well as fields that contian only one '?'. Thus you can use records like
169       "","Name" to pass in a valid name without an alias.
170
171       See also new() for more details about mappings.
172

AUTHOR

174       Juergen Weigert, "<jw at suse.de>"
175

BUGS

177       This module defines a different syntax than
178       http://rpmlint.zarb.org/cgi-bin/trac.cgi/browser/trunk/TagsCheck.py
179
180       Please report any bugs or feature requests to "bug-rpm-license at
181       rt.cpan.org", or through the web interface at
182       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=License-Syntax>.  I
183       will be notified, and then you'll automatically be notified of progress
184       on your bug as I make changes.
185

SUPPORT

187       You can find documentation for this module with the perldoc command.
188
189           perldoc License::Syntax
190
191       You can also look for information at:
192
193       •   RT: CPAN's request tracker
194
195           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=License-Syntax>
196
197       •   AnnoCPAN: Annotated CPAN documentation
198
199           <http://annocpan.org/dist/License-Syntax>
200
201       •   CPAN Ratings
202
203           <http://cpanratings.perl.org/d/License-Syntax>
204
205       •   Search CPAN
206
207           <http://search.cpan.org/dist/License-Syntax/>
208

ACKNOWLEDGEMENTS

211       Copyright 2009 Juergen Weigert.
212
213       This program is free software; you can redistribute it and/or modify it
214       under the terms of either: the GNU General Public License as published
215       by the Free Software Foundation; or the Artistic License.
216
217       See http://dev.perl.org/licenses/ for more information.
218
219
220
221perl v5.38.0                      2023-07-20                         Syntax(3)
Impressum