File Coverage

blib/lib/MsOffice/Word/Surgeon/Field.pm
Criterion Covered Total %
statement 22 22 100.0
branch n/a
condition 1 2 50.0
subroutine 8 8 100.0
pod 0 2 0.0
total 31 34 91.1


line stmt bran cond sub pod time code
1             package MsOffice::Word::Surgeon::Field;
2 4     4   57 use 5.24.0;
  4         15  
3 4     4   20 use Moose;
  4         7  
  4         28  
4 4     4   27874 use Moose::Util::TypeConstraints qw(enum);
  4         7  
  4         57  
5 4     4   2113 use MooseX::StrictConstructor;
  4         9  
  4         37  
6              
7 4     4   15530 use namespace::clean -except => 'meta';
  4         12  
  4         41  
8              
9             #======================================================================
10             # ATTRIBUTES
11             #======================================================================
12              
13             has 'xml_before' => (is => 'ro', isa => 'Str', required => 1);
14             has 'code' => (is => 'rw', isa => 'Str', required => 1);
15             has 'result' => (is => 'rw', isa => 'Str', required => 1);
16             has 'status' => (is => 'rw', isa => enum([qw/begin separate end/]), default => "end");
17             has 'type' => (is => 'ro', isa => 'Str', builder => '_type', lazy => 1);
18              
19             #======================================================================
20             # METHODS
21             #======================================================================
22              
23             sub _type {
24 8     8   13 my ($self) = @_;
25              
26 8         189 my ($type) = $self->code =~ /^\s*(\w+)/;
27 8   50     12 $type //= "";
28 8         160 return uc($type);
29             }
30              
31              
32             sub append_to_code {
33 50     50 0 116 my ($self, $more_code) = @_;
34 50         163 $self->{code} .= $more_code;
35             }
36              
37             sub append_to_result {
38 78     78 0 149 my ($self, $more_result) = @_;
39 78         403 $self->{result} .= $more_result;
40             }
41              
42             1;
43              
44             __END__
45              
46             =encoding ISO-8859-1
47              
48             =head1 NAME
49              
50             MsOffice::Word::Surgeon::Field - internal representation for a MsWord field
51              
52             =head1 DESCRIPTION
53              
54             This is used internally by L<MsOffice::Word::Surgeon> for storing
55             a MsWord field.
56              
57              
58             =head1 METHODS
59              
60             =head2 new
61              
62             my $field = MsOffice::Word::Surgeon::Field(
63             xml_before => $xml_string,
64             code => $code_instruction_string,
65             result => $xml_fragment,
66             status => 'begin',
67             );
68              
69             Constructor for a new field object. Arguments are :
70              
71             =over
72              
73             =item xml_before
74              
75             A string containing arbitrary XML preceding that field in the complete document.
76             The string may be empty but must be present.
77              
78             =item code
79              
80             A code containing the instruction string for that field.
81             If the instruction string contains embedded fields, these are represented through
82             the L<MsOffice::Word::Surgeon/show_embedded_field> syntax -- by default, just a pair of curly braces.
83              
84             =item result
85              
86             An XML fragment corresponding to the last update of that field in MsWord.
87              
88             =item status
89              
90             One of C<begin>, C<separate>, or C<end>.
91              
92             Status C<begin> or C<separate> are intermediate, used internally during the parsing process. Normally all
93             fields are in C<end> status.
94              
95             =back
96              
97              
98             =head2 add_to_code
99              
100             While parsing fields, additional field instruction fragments are added through this method
101              
102             =head2 add_to_result
103              
104             While parsing fields, additional XML fragments belonging to the field result are added through this method
105              
106             =head2 type
107              
108             The first instruction in the C<code> part, eg C<REF>, C<QUOTE>, C<ASK>, C<DOCPROPERTY>, etc.
109             Note : in the Microsoft Word Object Model, the L<https://learn.microsoft.com/en-us/office/vba/api/word.field.type|Field.Type> attribute
110             is an integer value in an enumerated type. Here the attribute is just an uppercase string. Lists of valild field types
111             can be found in the Word documentation.
112              
113              
114              
115             =head1 AUTHOR
116              
117             Laurent Dami, E<lt>dami AT cpan DOT org<gt>
118              
119             =head1 COPYRIGHT AND LICENSE
120              
121             Copyright 2024 by Laurent Dami.
122              
123             This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.