File Coverage

blib/lib/WebFetch/Input/PerlStruct.pm
Criterion Covered Total %
statement 20 27 74.0
branch 2 8 25.0
condition 0 6 0.0
subroutine 6 6 100.0
pod 1 1 100.0
total 29 48 60.4


line stmt bran cond sub pod time code
1             # WebFetch::Input::PerlStruct
2             # ABSTRACT: accept a Perl structure with pre-parsed news into WebFetch
3             #
4             # Copyright (c) 1998-2022 Ian Kluft. This program is free software; you can
5             # redistribute it and/or modify it under the terms of the GNU General Public
6             # License Version 3. See https://www.gnu.org/licenses/gpl-3.0-standalone.html
7              
8             # pragmas to silence some warnings from Perl::Critic
9             ## no critic (Modules::RequireExplicitPackage)
10             # This solves a catch-22 where parts of Perl::Critic want both package and use-strict to be first
11 2     2   40513 use strict;
  2         17  
  2         63  
12 2     2   16 use warnings;
  2         3  
  2         52  
13 2     2   9 use utf8;
  2         4  
  2         16  
14             ## use critic (Modules::RequireExplicitPackage)
15              
16             package WebFetch::Input::PerlStruct;
17             $WebFetch::Input::PerlStruct::VERSION = '0.15.8';
18 2     2   94 use base "WebFetch";
  2         4  
  2         938  
19              
20             # define exceptions/errors
21             use Exception::Class (
22 2         19 "WebFetch::Input::PerlStruct::Exception::NoStruct" => {
23             isa => "WebFetch::Exception",
24             alias => "throw_nostruct",
25             description => "no 'content' structure was provided",
26             },
27              
28             "WebFetch::Input::PerlStruct::Exception::BadStruct" => {
29             isa => "WebFetch::Exception",
30             alias => "throw_badstruct",
31             description => "content of 'content' was not recognizable",
32             },
33              
34 2     2   30 );
  2         3  
35              
36             # configuration parameters
37              
38             # no user-servicable parts beyond this point
39              
40             # register capabilities with WebFetch
41             __PACKAGE__->module_register("input:perlstruct");
42              
43             sub fetch
44             {
45 1     1 1 3 my ($self) = @_;
46              
47             # get the content from the provided perl structure
48 1 50       4 if ( !defined $self->{content} ) {
49 0         0 throw_nostruct "content struct does not exist";
50             }
51 1 50       10 if ( ref( $self->{content} )->isa("WebFetch::Data::Store") ) {
    0          
52 1         4 $self->{data} = $self->{content};
53 1         7 return;
54             } elsif ( ref( $self->{content} ) eq "HASH" ) {
55 0 0 0       if ( ( exists $self->{content}{fields} )
      0        
56             and ( exists $self->{content}{records} )
57             and ( exists $self->{content}{wk_names} ) )
58             {
59 0           $self->data->{fields} = $self->{content}{fields};
60 0           $self->data->{wk_names} = $self->{content}{wk_names};
61 0           $self->data->{records} = $self->{content}{records};
62 0           return;
63             }
64             }
65 0           throw_badstruct "content should be a WebFetch::Data::Store";
66             }
67              
68             1;
69              
70             =pod
71              
72             =encoding UTF-8
73              
74             =head1 NAME
75              
76             WebFetch::Input::PerlStruct - accept a Perl structure with pre-parsed news into WebFetch
77              
78             =head1 VERSION
79              
80             version 0.15.8
81              
82             =head1 SYNOPSIS
83              
84             In perl scripts:
85              
86             use WebFetch::Input::PerlStruct;
87              
88             $obj = WebFetch::Input::PerlStruct->new(
89             "content" => content_struct,
90             "dir" => output_dir,
91             "dest" => output_file,
92             "dest_format" => output_format, # used to select WebFetch output module
93             [ "group" => file_group_id, ]
94             [ "mode" => file_mode_perms, ]
95             [ "quiet" => 1 ]);
96              
97             I<Note: WebFetch::Input::PerlStruct is a Perl interface only.
98             It does not support usage from the command-line.>
99              
100             =head1 DESCRIPTION
101              
102             This module accepts a perl structure with pre-parsed news
103             and pushes it into the WebFetch infrastructure.
104              
105             The webmaster of a remote site only needs to arrange for a cron job to
106             update a WebFetch Export file, and let others know the URL to reach
107             that file.
108             (On the exporting site, it is most likely they'll use
109             WebFetch::SiteNews to export their own news.)
110             Then you can use the WebFetch::Input::PerlStruct module to read the
111             remote file and generate and HTML summary of the news.
112              
113             After WebFetch::Input::PerlStruct runs,
114             the file specified in the --file parameter will be created or replaced.
115             If there already was a file by that name, it will be moved to
116             a filename with "O" (for old) prepended to the file name.
117              
118             Most of the parameters listed are inherited from WebFetch.
119             See the WebFetch module documentation for details.
120              
121             =head1 THE CONTENT STRUCTURE
122              
123             The $content_struct parameter may be in either of two formats.
124              
125             If $content_struct is a hash reference containing entries called
126             "fields", "wk_names" and "records", then it is assumed to be already
127             in the format of the "data" element of the WebFetch Embedding API.
128              
129             Otherwise, it must be a reference to an array of hashes.
130             Each of the hashes represents a separate news item,
131             in the order they should be displayed.
132              
133             The field names should be consistent through all records.
134             WebFetch uses the field names from the first record and assumes the
135             remainder are identical.
136              
137             The names of the fields are chosen by the calling function.
138             If an array called "wk_names" is provided then it used to map
139             well-known field names of the WebFetch Embedding API to field names in
140             this data.
141             Otherwise, meaning can only be applied to field names if they already
142             match WebFetch's well-known field names.
143              
144             =head1 SEE ALSO
145              
146             L<WebFetch>
147             L<https://github.com/ikluft/WebFetch>
148              
149             =head1 BUGS AND LIMITATIONS
150              
151             Please report bugs via GitHub at L<https://github.com/ikluft/WebFetch/issues>
152              
153             Patches and enhancements may be submitted via a pull request at L<https://github.com/ikluft/WebFetch/pulls>
154              
155             =head1 AUTHOR
156              
157             Ian Kluft <https://github.com/ikluft>
158              
159             =head1 COPYRIGHT AND LICENSE
160              
161             This software is Copyright (c) 1998-2023 by Ian Kluft.
162              
163             This is free software, licensed under:
164              
165             The GNU General Public License, Version 3, June 2007
166              
167             =cut
168              
169             __END__
170             # POD docs follow