← Back to branch summary

~ubuntu-branches/ubuntu/trusty/teeworlds/trusty-updates

« back to all changes in this revision

Viewing changes to docs/tool/Modules/NaturalDocs/ImageReferenceTable.pm

  • Committer: Bazaar Package Importer
  • Author(s): Felix Geyer
  • Date: 2011-08-05 15:02:49 UTC
  • mfrom: (1.2.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20110805150249-1kai5j7v29m13dl3
Tags: 0.6.1+dfsg-1
* New upstream release.
* Repackage upstream tarball to remove pre-compiled libraries.
* Update watch file.
* Refresh patches.
* Drop patches that have been applied upstream: fix-ftbfs-hurd.patch,
  fix-ftbfs-kfreebsd.patch and gcc-endianness.patch.
* Use dh_link to create the DejaVuSans.ttf symlink.
* Query dpkg-buildflags instead of relying on dpkg-buildpackage to set the
  environment variables.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/tool/Modules/NaturalDocs/ImageReferenceTable.pm
1
 
###############################################################################
2
 
#
3
 
#   Package: NaturalDocs::ImageReferenceTable
4
 
#
5
 
###############################################################################
6
 
#
7
 
#   A <NaturalDocs::SourceDB>-based package that manages all the image references appearing in source files.
8
 
#
9
 
###############################################################################
10
 
 
11
 
# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
12
 
# Natural Docs is licensed under the GPL
13
 
 
14
 
use strict;
15
 
use integer;
16
 
 
17
 
use NaturalDocs::ImageReferenceTable::String;
18
 
use NaturalDocs::ImageReferenceTable::Reference;
19
 
 
20
 
 
21
 
package NaturalDocs::ImageReferenceTable;
22
 
 
23
 
use base 'NaturalDocs::SourceDB::Extension';
24
 
 
25
 
 
26
 
###############################################################################
27
 
# Group: Information
28
 
 
29
 
#
30
 
#   Topic: Usage
31
 
#
32
 
#       - <NaturalDocs::Project> and <NaturalDocs::SourceDB> must be initialized before this package can be used.
33
 
#
34
 
#       - Call <Register()> before using.
35
 
#
36
 
#
37
 
#   Topic: Programming Notes
38
 
#
39
 
#       When working on this code, remember that there are three things it has to juggle.
40
 
#
41
 
#       - The information in <NaturalDocs::SourceDB>.
42
 
#       - Image file references in <NaturalDocs::Project>.
43
 
#       - Source file rebuilding on changes.
44
 
#
45
 
#       Managing the actual image files will be handled between <NaturalDocs::Project> and the <NaturalDocs::Builder>
46
 
#       sub-packages.
47
 
#
48
 
#
49
 
#   Topic: Implementation
50
 
#
51
 
#       Managing image references is simpler than managing the references in <NaturalDocs::SymbolTable>.  In SymbolTable,
52
 
#       you have to worry about reference targets popping into and out of existence.  A link may go to a file that hasn't been
53
 
#       reparsed yet and the target may no longer exist.  We have to deal with that when we know it, which may be after the
54
 
#       reference's file was parsed.  Also, a new definition may appear that serves as a better interpretation of a link than its
55
 
#       current target, and again we may only know that after the reference's file has been parsed already.  So we have to deal
56
 
#       with scores and potential symbols and each symbol knowing exactly what links to it and so forth.
57
 
#
58
 
#       Not so with image references.  All possible targets (all possible image files) are known by <NaturalDocs::Project> early
59
 
#       on and will remain consistent throughout execution.  So because of that, we can get away with only storing reference
60
 
#       counts with each image and determining exactly where a reference points to as we find them.
61
 
#
62
 
#       Reference counts are stored with the image file information in <NaturalDocs::Project>.  However, it is not loaded and
63
 
#       saved to disk by it.  Rather, it is regenerated by this package when it loads <ImageReferenceTable.nd>.
64
 
#       NaturalDocs::Project only stores the last modification time (so it can add files to the build list if they've changed) and
65
 
#       whether it had any references at all on the last run (so it knows whether it should care if they've changed.)
66
 
#       ImageReferenceTable.nd stores each reference's target, width, and height.  Whether their interpretations have changed is
67
 
#       dealt with in the <Load()> function, again since the list of targets (image files) is constant.
68
 
#
69
 
#       The package is based on <NaturalDocs::SourceDB>, so read it's documentation for more information on how it works.
70
 
#
71
 
 
72
 
 
73
 
###############################################################################
74
 
# Group: Variables
75
 
 
76
 
 
77
 
#
78
 
#   var: extensionID
79
 
#   The <ExtensionID> granted by <NaturalDocs::SourceDB>.
80
 
#
81
 
my $extensionID;
82
 
 
83
 
 
84
 
 
85
 
###############################################################################
86
 
# Group: Files
87
 
 
88
 
 
89
 
#
90
 
#   File: ImageReferenceTable.nd
91
 
#
92
 
#   The data file which stores all the image references from the last run of Natural Docs.
93
 
#
94
 
#   Format:
95
 
#
96
 
#       > [Standard Binary Header]
97
 
#
98
 
#       It starts with the standard binary header from <NaturalDocs::BinaryFile>.
99
 
#
100
 
#       > [Image Reference String or undef]
101
 
#       > [AString16: target file]
102
 
#       > [UInt16: target width or 0]
103
 
#       > [UInt16: target height or 0]
104
 
#
105
 
#       For each <ImageReferenceString>, it's target, width, and height are stored.  The target is needed so we can tell if it
106
 
#       changed from the last run, and the dimensions are needed because if the target hasn't changed but the file's dimensions
107
 
#       have, the source files need to be rebuilt.
108
 
#
109
 
#       <ImageReferenceStrings> are encoded by <NaturalDocs::ImageReferenceTable::String>.
110
 
#
111
 
#       > [AString16: definition file or undef] ...
112
 
#
113
 
#       Then comes a series of AString16s for all the files that define the reference until it hits an undef.
114
 
#
115
 
#       This whole series is repeated for each <ImageReferenceString> until it hits an undef.
116
 
#
117
 
#       Revisions:
118
 
#
119
 
#               1.4:
120
 
#
121
 
#                       - The file was added to Natural Docs.
122
 
#
123
 
 
124
 
 
125
 
 
126
 
###############################################################################
127
 
# Group: Functions
128
 
 
129
 
 
130
 
#
131
 
#   Function: Register
132
 
#   Registers the package with <NaturalDocs::SourceDB>.
133
 
#
134
 
sub Register
135
 
    {
136
 
    my $self = shift;
137
 
    $extensionID = NaturalDocs::SourceDB->RegisterExtension($self, 0);
138
 
    };
139
 
 
140
 
 
141
 
#
142
 
#   Function: Load
143
 
#
144
 
#   Loads the data from <ImageReferenceTable.nd>.  Returns whether it was successful.
145
 
#
146
 
sub Load # => bool
147
 
    {
148
 
    my $self = shift;
149
 
 
150
 
    if (NaturalDocs::Settings->RebuildData())
151
 
        {  return 0;  };
152
 
 
153
 
    # The file format hasn't changed since it was introduced.
154
 
    if (!NaturalDocs::BinaryFile->OpenForReading( NaturalDocs::Project->DataFile('ImageReferenceTable.nd') ))
155
 
        {  return 0;  };
156
 
 
157
 
 
158
 
    # [Image Reference String or undef]
159
 
    while (my $referenceString = NaturalDocs::ImageReferenceTable::String->FromBinaryFile())
160
 
        {
161
 
        NaturalDocs::SourceDB->AddItem($extensionID, $referenceString,
162
 
                                                           NaturalDocs::ImageReferenceTable::Reference->New());
163
 
 
164
 
        # [AString16: target file]
165
 
        # [UInt16: target width or 0]
166
 
        # [UInt16: target height or 0]
167
 
 
168
 
        my $targetFile = NaturalDocs::BinaryFile->GetAString16();
169
 
        my $width = NaturalDocs::BinaryFile->GetUInt16();
170
 
        my $height = NaturalDocs::BinaryFile->GetUInt16();
171
 
 
172
 
        my $newTargetFile = $self->SetReferenceTarget($referenceString);
173
 
        my $newWidth;
174
 
        my $newHeight;
175
 
 
176
 
        if ($newTargetFile)
177
 
            {
178
 
            NaturalDocs::Project->AddImageFileReference($newTargetFile);
179
 
            ($newWidth, $newHeight) = NaturalDocs::Project->ImageFileDimensions($newTargetFile);
180
 
            };
181
 
 
182
 
        my $rebuildDefinitions = ($newTargetFile ne $targetFile || $newWidth != $width || $newHeight != $height);
183
 
 
184
 
 
185
 
        # [AString16: definition file or undef] ...
186
 
        while (my $definitionFile = NaturalDocs::BinaryFile->GetAString16())
187
 
            {
188
 
            NaturalDocs::SourceDB->AddDefinition($extensionID, $referenceString, $definitionFile);
189
 
 
190
 
            if ($rebuildDefinitions)
191
 
                {  NaturalDocs::Project->RebuildFile($definitionFile);  };
192
 
            };
193
 
        };
194
 
 
195
 
 
196
 
    NaturalDocs::BinaryFile->Close();
197
 
    return 1;
198
 
    };
199
 
 
200
 
 
201
 
#
202
 
#   Function: Save
203
 
#
204
 
#   Saves the data to <ImageReferenceTable.nd>.
205
 
#
206
 
sub Save
207
 
    {
208
 
    my $self = shift;
209
 
 
210
 
    my $references = NaturalDocs::SourceDB->GetAllItemsHashRef($extensionID);
211
 
 
212
 
    NaturalDocs::BinaryFile->OpenForWriting( NaturalDocs::Project->DataFile('ImageReferenceTable.nd') );
213
 
 
214
 
    while (my ($referenceString, $referenceObject) = each %$references)
215
 
        {
216
 
        # [Image Reference String or undef]
217
 
        # [AString16: target file]
218
 
        # [UInt16: target width or 0]
219
 
        # [UInt16: target height or 0]
220
 
 
221
 
        NaturalDocs::ImageReferenceTable::String->ToBinaryFile($referenceString);
222
 
 
223
 
        my $target = $referenceObject->Target();
224
 
        my ($width, $height);
225
 
 
226
 
        if ($target)
227
 
            {  ($width, $height) = NaturalDocs::Project->ImageFileDimensions($target);  };
228
 
 
229
 
        NaturalDocs::BinaryFile->WriteAString16( $referenceObject->Target() );
230
 
        NaturalDocs::BinaryFile->WriteUInt16( ($width || 0) );
231
 
        NaturalDocs::BinaryFile->WriteUInt16( ($height || 0) );
232
 
 
233
 
        # [AString16: definition file or undef] ...
234
 
 
235
 
        my $definitions = $referenceObject->GetAllDefinitionsHashRef();
236
 
 
237
 
        foreach my $definition (keys %$definitions)
238
 
            {  NaturalDocs::BinaryFile->WriteAString16($definition);  };
239
 
 
240
 
        NaturalDocs::BinaryFile->WriteAString16(undef);
241
 
        };
242
 
 
243
 
    NaturalDocs::ImageReferenceTable::String->ToBinaryFile(undef);
244
 
 
245
 
    NaturalDocs::BinaryFile->Close();
246
 
    };
247
 
 
248
 
 
249
 
#
250
 
#   Function: AddReference
251
 
#
252
 
#   Adds a new image reference.
253
 
#
254
 
sub AddReference #(FileName file, string referenceText)
255
 
    {
256
 
    my ($self, $file, $referenceText) = @_;
257
 
 
258
 
    my $referenceString = NaturalDocs::ImageReferenceTable::String->Make($file, $referenceText);
259
 
 
260
 
    if (!NaturalDocs::SourceDB->HasItem($extensionID, $referenceString))
261
 
        {
262
 
        my $referenceObject = NaturalDocs::ImageReferenceTable::Reference->New();
263
 
        NaturalDocs::SourceDB->AddItem($extensionID, $referenceString, $referenceObject);
264
 
 
265
 
        my $target = $self->SetReferenceTarget($referenceString);
266
 
        if ($target)
267
 
            {  NaturalDocs::Project->AddImageFileReference($target);  };
268
 
        };
269
 
 
270
 
    NaturalDocs::SourceDB->AddDefinition($extensionID, $referenceString, $file);
271
 
    };
272
 
 
273
 
 
274
 
#
275
 
#   Function: OnDeletedDefinition
276
 
#
277
 
#   Called for each definition deleted by <NaturalDocs::SourceDB>.  This is called *after* the definition has been deleted from
278
 
#   the database, so don't expect to be able to read it.
279
 
#
280
 
sub OnDeletedDefinition #(ImageReferenceString referenceString, FileName file, bool wasLastDefinition)
281
 
    {
282
 
    my ($self, $referenceString, $file, $wasLastDefinition) = @_;
283
 
 
284
 
    if ($wasLastDefinition)
285
 
        {
286
 
        my $referenceObject = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
287
 
        my $target = $referenceObject->Target();
288
 
 
289
 
        if ($target)
290
 
            {  NaturalDocs::Project->DeleteImageFileReference($target);  };
291
 
 
292
 
        NaturalDocs::SourceDB->DeleteItem($extensionID, $referenceString);
293
 
        };
294
 
    };
295
 
 
296
 
 
297
 
#
298
 
#   Function: GetReferenceTarget
299
 
#
300
 
#   Returns the image file the reference resolves to, or undef if none.
301
 
#
302
 
#   Parameters:
303
 
#
304
 
#       sourceFile - The source <FileName> the reference appears in.
305
 
#       text - The reference text.
306
 
#
307
 
sub GetReferenceTarget #(FileName sourceFile, string text) => FileName
308
 
    {
309
 
    my ($self, $sourceFile, $text) = @_;
310
 
 
311
 
    my $referenceString = NaturalDocs::ImageReferenceTable::String->Make($sourceFile, $text);
312
 
    my $reference = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
313
 
 
314
 
    if (!defined $reference)
315
 
        {  return undef;  }
316
 
    else
317
 
        {  return $reference->Target();  };
318
 
    };
319
 
 
320
 
 
321
 
#
322
 
#   Function: SetReferenceTarget
323
 
#
324
 
#   Determines the best target for the passed <ImageReferenceString> and sets it on the
325
 
#   <NaturalDocs::ImageReferenceTable::Reference> object.  Returns the new target <FileName>.  Does *not* add any source
326
 
#   files to the bulid list.
327
 
#
328
 
sub SetReferenceTarget #(ImageReferenceString referenceString) => FileName
329
 
    {
330
 
    my ($self, $referenceString) = @_;
331
 
 
332
 
    my $referenceObject = NaturalDocs::SourceDB->GetItem($extensionID, $referenceString);
333
 
    my ($sourcePath, $text) = NaturalDocs::ImageReferenceTable::String->InformationOf($referenceString);
334
 
 
335
 
 
336
 
    # Try the path relative to the source file first.
337
 
 
338
 
    my $target;
339
 
 
340
 
    my $imageFile = NaturalDocs::File->JoinPaths($sourcePath, $text);
341
 
    my $exists = NaturalDocs::Project->ImageFileExists($imageFile);
342
 
 
343
 
 
344
 
    # Then try relative image directories.
345
 
 
346
 
    if (!$exists)
347
 
        {
348
 
        my $relativeImageDirectories = NaturalDocs::Settings->RelativeImageDirectories();
349
 
 
350
 
        for (my $i = 0; $i < scalar @$relativeImageDirectories && !$exists; $i++)
351
 
            {
352
 
            $imageFile = NaturalDocs::File->JoinPaths($sourcePath, $relativeImageDirectories->[$i], 1);
353
 
            $imageFile = NaturalDocs::File->JoinPaths($imageFile, $text);
354
 
 
355
 
            $exists = NaturalDocs::Project->ImageFileExists($imageFile);
356
 
            };
357
 
        };
358
 
 
359
 
 
360
 
    # Then try absolute image directories.
361
 
 
362
 
    if (!$exists)
363
 
        {
364
 
        my $imageDirectories = NaturalDocs::Settings->ImageDirectories();
365
 
 
366
 
        for (my $i = 0; $i < scalar @$imageDirectories && !$exists; $i++)
367
 
            {
368
 
            $imageFile = NaturalDocs::File->JoinPaths($imageDirectories->[$i], $text);
369
 
            $exists = NaturalDocs::Project->ImageFileExists($imageFile);
370
 
            };
371
 
        };
372
 
 
373
 
 
374
 
    if ($exists)
375
 
        {  $target = NaturalDocs::Project->ImageFileCapitalization($imageFile);  };
376
 
    #else leave it as undef.
377
 
 
378
 
    $referenceObject->SetTarget($target);
379
 
    return $target;
380
 
    };
381
 
 
382
 
 
383
 
1;