| 1 | ## -*- Mode: CPerl -*- | ||
| 2 | ## | ||
| 3 | ## File: DTA::CAB::Chain.pm | ||
| 4 | ## Author: Bryan Jurish <moocow@cpan.org> | ||
| 5 | ## Description: generic analyzer API: analyzer "chains" / "cascades" / "pipelines" / ... | ||
| 6 | |||
| 7 | package DTA::CAB::Chain; | ||
| 8 | use DTA::CAB::Analyzer; | ||
| 9 | use DTA::CAB::Datum ':all'; | ||
| 10 | use Carp; | ||
| 11 | use strict; | ||
| 12 | |||
| 13 | ##============================================================================== | ||
| 14 | ## Globals | ||
| 15 | ##============================================================================== | ||
| 16 | |||
| 17 | our @ISA = qw(DTA::CAB::Analyzer); | ||
| 18 | |||
| 19 | BEGIN { | ||
| 20 | *isa = \&UNIVERSAL::isa; | ||
| 21 | *can = \&UNIVERSAL::can; | ||
| 22 | } | ||
| 23 | |||
| 24 | ##============================================================================== | ||
| 25 | ## Constructors etc. | ||
| 26 | ##============================================================================== | ||
| 27 | |||
| 28 | ## $obj = CLASS_OR_OBJ->new(%args) | ||
| 29 | ## + object structure: | ||
| 30 | ## ( | ||
| 31 | ## ##-- Analyzers | ||
| 32 | ## chain => [ $a1, $a2, ..., $aN ], ##-- default analysis chain; see also chain() method (default: empty) | ||
| 33 | ## | ||
| 34 | ## ##-- verbose trace | ||
| 35 | ## logTrace => $level, ##-- trace sub-analyzer execution (default: 'none') | ||
| 36 | ## ) | ||
| 37 | sub new { | ||
| 38 | my $that = shift; | ||
| 39 | my $ach = bless({ | ||
| 40 | ##-- user args | ||
| 41 | chain => [], | ||
| 42 | logTrace => 'none', | ||
| 43 | @_ | ||
| 44 | }, ref($that)||$that); | ||
| 45 | $ach->initialize(); | ||
| 46 | $ach->{label} = $ach->defaultLabel if (!defined($ach->{label})); | ||
| 47 | return $ach; | ||
| 48 | } | ||
| 49 | |||
| 50 | ## undef = $ach->initialize(); | ||
| 51 | ## + default implementation does nothing | ||
| 52 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 53 | |||
| 54 | ## undef = $ach->dropClosures(); | ||
| 55 | ## + drops '_analyze*' closures | ||
| 56 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 57 | |||
| 58 | ## @keys = $anl->typeKeys(\%opts) | ||
| 59 | ## + returns list of type-wise keys to be expanded for this analyzer by expandTypes() | ||
| 60 | ## + default just concatenates keys for sub-analyzers | ||
| 61 | sub typeKeys { | ||
| 62 | my $ach = shift; | ||
| 63 | return map {ref($_) ? $_->typeKeys(@_) : qw()} @{$ach->chain(@_)} | ||
| 64 | } | ||
| 65 | |||
| 66 | |||
| 67 | ##============================================================================== | ||
| 68 | ## Methods: Chain selection | ||
| 69 | ##============================================================================== | ||
| 70 | |||
| 71 | ## \@analyzers = $ach->chain() | ||
| 72 | ## \@analyzers = $ach->chain(\%opts) | ||
| 73 | ## + get selected analyzer chain | ||
| 74 | ### + OLD: default method just returns $anl->{chain} | ||
| 75 | ### + NEW: default method returns all globally enabled analyzers in $anl->{chain} | ||
| 76 | sub chain { | ||
| 77 | my $ach = shift; | ||
| 78 | #return $ach->{chain}; | ||
| 79 | return [grep {$_ && $_->enabled} @{$ach->{chain}}]; | ||
| 80 | } | ||
| 81 | |||
| 82 | ## \@analyzers = $ach->subAnalyzers() | ||
| 83 | ## \@analyzers = $ach->subAnalyzers(\%opts) | ||
| 84 | ## + returns a list of all sub-analyzers | ||
| 85 | ## + override just calls chain() | ||
| 86 | sub subAnalyzers { | ||
| 87 | return $_[0]->chain(@_[1..$#_]); | ||
| 88 | } | ||
| 89 | |||
| 90 | |||
| 91 | ##============================================================================== | ||
| 92 | ## Methods: I/O | ||
| 93 | ##============================================================================== | ||
| 94 | |||
| 95 | ##-------------------------------------------------------------- | ||
| 96 | ## Methods: I/O: Input: all | ||
| 97 | |||
| 98 | ## $bool = $ach->ensureLoaded() | ||
| 99 | ## $bool = $ach->ensureLoaded(\%opts) | ||
| 100 | ## + ensures analysis data is loaded from default files | ||
| 101 | ## + default version calls $a->ensureLoaded() for each $a in $ach->subAnalyzers(\%opts) | ||
| 102 | sub ensureLoaded { | ||
| 103 | my $ach = shift; | ||
| 104 | my $subs = $ach->subAnalyzers(@_); | ||
| 105 | my $rc = 1; | ||
| 106 | foreach (@$subs) { | ||
| 107 | $rc &&= $_->ensureLoaded() if (ref($_) && $_->can('ensureLoaded')); | ||
| 108 | last if (!$rc); ##-- short-circuit | ||
| 109 | } | ||
| 110 | return $rc; | ||
| 111 | } | ||
| 112 | |||
| 113 | ##============================================================================== | ||
| 114 | ## Methods: Persistence | ||
| 115 | ##============================================================================== | ||
| 116 | |||
| 117 | ##====================================================================== | ||
| 118 | ## Methods: Persistence: Perl | ||
| 119 | |||
| 120 | ## @keys = $class_or_obj->noSaveKeys() | ||
| 121 | ## + returns list of keys not to be saved | ||
| 122 | ## + default just greps for CODE-refs | ||
| 123 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 124 | |||
| 125 | ## $loadedObj = $CLASS_OR_OBJ->loadPerlRef($ref) | ||
| 126 | ## + default implementation just clobbers $CLASS_OR_OBJ with $ref and blesses | ||
| 127 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 128 | |||
| 129 | ##====================================================================== | ||
| 130 | ## Methods: Persistence: Bin | ||
| 131 | |||
| 132 | ## @keys = $class_or_obj->noSaveBinKeys() | ||
| 133 | ## + returns list of keys not to be saved for binary mode | ||
| 134 | ## + default just returns list of known '_analyze' keys | ||
| 135 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 136 | |||
| 137 | ## $loadedObj = $CLASS_OR_OBJ->loadBinRef($ref) | ||
| 138 | ## + drops closures | ||
| 139 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 140 | |||
| 141 | ##============================================================================== | ||
| 142 | ## Methods: Analysis | ||
| 143 | ##============================================================================== | ||
| 144 | |||
| 145 | ##------------------------------------------------------------------------ | ||
| 146 | ## Methods: Analysis: Generic | ||
| 147 | |||
| 148 | ## $bool = $ach->canAnalyze() | ||
| 149 | ## $bool = $ach->canAnalyze(\%opts) | ||
| 150 | ## + returns true if analyzer can perform its function (e.g. data is loaded & non-empty) | ||
| 151 | ## + returns true if all enabled analyzers in the chain can analyze | ||
| 152 | sub canAnalyze { | ||
| 153 | my $ach = shift; | ||
| 154 | my $subs = $ach->subAnalyzers(@_); | ||
| 155 | foreach (grep {ref($_) && $_->enabled(@_)} @$subs) { | ||
| 156 | if (!$_ || !$_->canAnalyze) { | ||
| 157 | #$ach->logwarn("canAnalyze() returning 0 for sub-analyzer \"$_\""); | ||
| 158 | return 0; | ||
| 159 | } | ||
| 160 | } | ||
| 161 | return 1; | ||
| 162 | } | ||
| 163 | |||
| 164 | |||
| 165 | ## $bool = $anl->enabled(\%opts) | ||
| 166 | ## + returns $anl->{enabled} and disjunction over all sub-analyzers | ||
| 167 | sub enabled { | ||
| 168 | my $ach = shift; | ||
| 169 | return $ach->SUPER::enabled(@_) && scalar(grep {$_->enabled(@_)} @{$ach->subAnalyzers(@_)}); | ||
| 170 | } | ||
| 171 | |||
| 172 | |||
| 173 | ## undef = $anl->initInfo() | ||
| 174 | ## + logs initialization info | ||
| 175 | ## + default method reports values of {label}, enabled() | ||
| 176 | sub initInfo { | ||
| 177 | my $anl = shift; | ||
| 178 | if (!$anl->{initQuiet}) { | ||
| 179 | $anl->SUPER::initInfo(@_); | ||
| 180 | $_->initInfo(@_) foreach (@{$anl->subAnalyzers(@_)}); | ||
| 181 | $anl->{initQuiet}=1; | ||
| 182 | } | ||
| 183 | } | ||
| 184 | |||
| 185 | |||
| 186 | ##============================================================================== | ||
| 187 | ## Methods: Analysis: v1.x | ||
| 188 | |||
| 189 | ##------------------------------------------------------------------------ | ||
| 190 | ## Methods: Analysis: v1.x: API | ||
| 191 | |||
| 192 | ## $doc = $ach->analyzeDocument($doc,\%opts) | ||
| 193 | ## + analyze a DTA::CAB::Document $doc | ||
| 194 | ## + top-level API routine | ||
| 195 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 196 | |||
| 197 | ## $doc = $ach->analyzeTypes($doc,$types,\%opts) | ||
| 198 | ## + perform type-wise analysis of all (text) types in $doc->{types} | ||
| 199 | ## + Chain default calls $a->analyzeTypes for each analyzer $a in the chain | ||
| 200 | sub analyzeTypes { | ||
| 201 | my ($ach,$doc,$types,$opts) = @_; | ||
| 202 | foreach (@{$ach->chain($opts)}) { | ||
| 203 | next if (!$_->doAnalyze($opts,'Types') || !$_->enabled($opts)); | ||
| 204 | $ach->vlog($opts->{logTrace}//$ach->{logTrace},"analyzeTypes: $_->{label}"); | ||
| 205 | $_->analyzeTypes($doc,$types,$opts); | ||
| 206 | } | ||
| 207 | return $doc; | ||
| 208 | } | ||
| 209 | |||
| 210 | ## $doc = $ach->analyzeTokens($doc,\%opts) | ||
| 211 | ## + perform token-wise analysis of all tokens $doc->{body}[$si]{tokens}[$wi] | ||
| 212 | ## + default implementation just shallow copies tokens in $doc->{types} | ||
| 213 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 214 | |||
| 215 | ## $doc = $ach->analyzeSentences($doc,\%opts) | ||
| 216 | ## + perform sentence-wise analysis of all sentences $doc->{body}[$si] | ||
| 217 | ## + Chain default calls $a->analyzeSentences for each analyzer $a in the chain | ||
| 218 | sub analyzeSentences { | ||
| 219 | my ($ach,$doc,$opts) = @_; | ||
| 220 | foreach (@{$ach->chain($opts)}) { | ||
| 221 | next if (!$_->doAnalyze($opts,'Sentences') || !$_->enabled($opts)); | ||
| 222 | $ach->vlog($opts->{logTrace}//$ach->{logTrace},"analyzeSentences: $_->{label}"); | ||
| 223 | $_->analyzeSentences($doc,$opts); | ||
| 224 | } | ||
| 225 | return $doc; | ||
| 226 | } | ||
| 227 | |||
| 228 | ## $doc = $ach->analyzeLocal($doc,\%opts) | ||
| 229 | ## + perform local document-level analysis of $doc | ||
| 230 | ## + Chain default calls $a->analyzeLocal for each analyzer $a in the chain | ||
| 231 | sub analyzeLocal { | ||
| 232 | my ($ach,$doc,$opts) = @_; | ||
| 233 | foreach (@{$ach->chain($opts)}) { | ||
| 234 | next if (!$_->doAnalyze($opts,'Local') || !$_->enabled($opts)); | ||
| 235 | $ach->vlog($opts->{logTrace}//$ach->{logTrace},"analyzeLocal: $_->{label}"); | ||
| 236 | $_->analyzeLocal($doc,$opts); | ||
| 237 | } | ||
| 238 | return $doc; | ||
| 239 | } | ||
| 240 | |||
| 241 | ## $doc = $ach->analyzeClean($doc,\%opts) | ||
| 242 | ## + cleanup any temporary data associated with $doc | ||
| 243 | ## + Chain default calls $a->analyzeClean for each analyzer $a in the chain, | ||
| 244 | ## then superclass Analyzer->analyzeClean | ||
| 245 | sub analyzeClean { | ||
| 246 | my ($ach,$doc,$opts) = @_; | ||
| 247 | foreach (@{$ach->chain($opts)}) { | ||
| 248 | next if (!$_->doAnalyze($opts,'Clean') || !$_->enabled($opts)); | ||
| 249 | $ach->vlog($opts->{logTrace}//$ach->{logTrace},"analyzeClean: $_->{label}"); | ||
| 250 | $_->analyzeClean($doc,$opts); | ||
| 251 | } | ||
| 252 | return $ach->SUPER::analyzeClean($doc,$opts) if ($ach->doAnalyze($opts,'Clean')); | ||
| 253 | return $doc; | ||
| 254 | } | ||
| 255 | |||
| 256 | ##------------------------------------------------------------------------ | ||
| 257 | ## Methods: Analysis: v1.x: Wrappers | ||
| 258 | |||
| 259 | ## $tok = $ach->analyzeToken($tok_or_string,\%opts) | ||
| 260 | ## + perform type- and token-analyses on $tok_or_string | ||
| 261 | ## + wrapper for $ach->analyzeDocument() | ||
| 262 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 263 | |||
| 264 | ## $tok = $ach->analyzeSentence($sent_or_array,\%opts) | ||
| 265 | ## + perform type-, token-, and sentence-analyses on $sent_or_array | ||
| 266 | ## + wrapper for $ach->analyzeDocument() | ||
| 267 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 268 | |||
| 269 | ## $rpc_xml_base64 = $anl->analyzeData($data_str,\%opts) | ||
| 270 | ## + analyze a raw (formatted) data string $data_str with internal parsing & formatting | ||
| 271 | ## + wrapper for $anl->analyzeDocument() | ||
| 272 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 273 | |||
| 274 | ##============================================================================== | ||
| 275 | ## Methods: XML-RPC | ||
| 276 | ## + INHERITED from DTA::CAB::Analyzer | ||
| 277 | |||
| 278 | 1; ##-- be happy | ||
| 279 | |||
| 280 | __END__ |