1Ace::Object(3)        User Contributed Perl Documentation       Ace::Object(3)
2
3
4

NAME

6       Ace::Object - Manipulate  Ace Data Objects
7

SYNOPSIS

9           # open database connection and get an object
10           use Ace;
11           $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
12                              -port => 20000100);
13           $sequence  = $db->fetch(Sequence => 'D12345');
14
15           # Inspect the object
16           $r    = $sequence->at('Visible.Overlap_Right');
17           @row  = $sequence->row;
18           @col  = $sequence->col;
19           @tags = $sequence->tags;
20
21           # Explore object substructure
22           @more_tags = $sequence->at('Visible')->tags;
23           @col       = $sequence->at("Visible.$more_tags[1]")->col;
24
25           # Follow a pointer into database
26           $r     = $sequence->at('Visible.Overlap_Right')->fetch;
27           $next  = $r->at('Visible.Overlap_left')->fetch;
28
29           # Classy way to do the same thing
30           $r     = $sequence->Overlap_right;
31           $next  = $sequence->Overlap_left;
32
33           # Pretty-print object
34           print $sequence->asString;
35           print $sequence->asTabs;
36           print $sequence->asHTML;
37
38           # Update object
39           $sequence->replace('Visible.Overlap_Right',$r,'M55555');
40           $sequence->add('Visible.Homology','GR91198');
41           $sequence->delete('Source.Clone','MBR122');
42           $sequence->commit();
43
44           # Rollback changes
45           $sequence->rollback()
46
47           # Get errors
48           print $sequence->error;
49

DESCRIPTION

51       Ace::Object is the base class for objects returned from ACEDB
52       databases. Currently there is only one type of Ace::Object, but this
53       may change in the future to support more interesting object-specific
54       behaviors.
55
56       Using the Ace::Object interface, you can explore the internal structure
57       of an Ace::Object, retrieve its content, and convert it into various
58       types of text representation.  You can also fetch a representation of
59       any object as a GIF image.
60
61       If you have write access to the databases, add new data to an object,
62       replace existing data, or kill it entirely.  You can also create a new
63       object de novo and write it into the database.
64
65       For information on connecting to ACEDB databases and querying them, see
66       Ace.
67

ACEDB::OBJECT METHODS

69       The structure of an Ace::Object is very similar to that of an Acedb
70       object.  It is a tree structure like this one (an Author object):
71
72        Thierry-Mieg J->Full_name ->Jean Thierry-Mieg
73                         |
74                        Laboratory->FF
75                         |
76                        Address->Mail->CRBM duCNRS
77                         |        |     |
78                         |        |    BP 5051
79                         |        |     |
80                         |        |    34033 Montpellier
81                         |        |     |
82                         |        |    FRANCE
83                         |        |
84                         |       E_mail->mieg@kaa.cnrs-mop.fr
85                         |        |
86                         |       Phone ->33-67-613324
87                         |        |
88                         |       Fax   ->33-67-521559
89                         |
90                        Paper->The C. elegans sequencing project
91                                |
92                               Genome Project Database
93                                |
94                               Genome Sequencing
95                                |
96                                How to get ACEDB for your Sun
97                                |
98                               ACEDB is Hungry
99
100       Each object in the tree has two pointers, a "right" pointer to the node
101       on its right, and a "down" pointer to the node beneath it.  Right
102       pointers are used to store hierarchical relationships, such as
103       Address->Mail->E_mail, while down pointers are used to store lists,
104       such as the multiple papers written by the Author.
105
106       Each node in the tree has a type and a name.  Types include integers,
107       strings, text, floating point numbers, as well as specialized
108       biological types, such as "dna" and "peptide."  Another fundamental
109       type is "tag," which is a text identifier used to label portions of the
110       tree.  Examples of tags include "Paper" and "Laboratory" in the example
111       above.
112
113       In addition to these built-in types, there are constructed types known
114       as classes.  These types are specified by the data model.  In the above
115       example, "Thierry-Mieg J" is an object of the "Author" class, and
116       "Genome Project Database" is an object of the "Paper" class.  An
117       interesting feature of objects is that you can follow them into the
118       database, retrieving further information.  For example, after
119       retrieving the "Genome Project Database" Paper from the Author object,
120       you could fetch more information about it, either by following its
121       right pointer, or by using one of the specialized navigation routines
122       described below.
123
124   new() method
125           $object = new Ace::Object($class,$name,$database);
126           $object = new Ace::Object(-class=>$class,
127                                     -name=>$name,
128                                     -db=>database);
129
130       You can create a new Ace::Object from scratch by calling the new()
131       routine with the object's class, its identifier and a handle to the
132       database to create it in.  The object won't actually be created in the
133       database until you add() one or more tags to it and commit() it (see
134       below).  If you do not provide a database handle, the object will be
135       created in memory only.
136
137       Arguments can be passed positionally, or as named parameters, as shown
138       above.
139
140       This routine is usually used internally.  See also add_row(),
141       add_tree(), delete() and replace() for ways to manipulate this object.
142
143   name() method
144           $name = $object->name();
145
146       Return the name of the Ace::Object.  This happens automatically
147       whenever you use the object in a context that requires a string or a
148       number.  For example:
149
150           $object = $db->fetch(Author,"Thierry-Mieg J");
151           print "$object did not write 'Pride and Prejudice.'\n";
152
153   class() method
154           $class = $object->class();
155
156       Return the class of the object.  The return value may be one of
157       "float," "int," "date," "tag," "txt," "dna," "peptide," and "scalar."
158       (The last is used internally by Perl to represent objects created
159       programatically prior to committing them to the database.)  The class
160       may also be a user-constructed type such as Sequence, Clone or Author.
161       These user-constructed types usually have an initial capital letter.
162
163   db() method
164            $db = $object->db();
165
166       Return the database that the object is associated with.
167
168   isClass() method
169            $bool = $object->isClass();
170
171       Returns true if the object is a class (can be fetched from the
172       database).
173
174   isTag() method
175            $bool = $object->isTag();
176
177       Returns true if the object is a tag.
178
179   tags() method
180            @tags = $object->tags();
181
182       Return all the top-level tags in the object as a list.  In the Author
183       example above, the returned list would be
184       ('Full_name','Laboratory','Address','Paper').
185
186       You can fetch tags more deeply nested in the structure by navigating
187       inwards using the methods listed below.
188
189   right() and down() methods
190            $subtree = $object->right;
191            $subtree = $object->right($position);
192            $subtree = $object->down;
193            $subtree = $object->down($position);
194
195       right() and down() provide a low-level way of traversing the tree
196       structure by following the tree's right and down pointers.  Called
197       without any arguments, these two methods will move one step.  Called
198       with a numeric argument >= 0 they will move the indicated number of
199       steps (zero indicates no movement).
200
201            $full_name = $object->right->right;
202            $full_name = $object->right(2);
203
204            $city = $object->right->down->down->right->right->down->down;
205            $city = $object->right->down(2)->right(2)->down(2);
206
207       If $object contains the "Thierry-Mieg J" Author object, then the first
208       series of accesses shown above retrieves the string "Jean Thierry-Mieg"
209       and the second retrieves "34033 Montpellier."  If the right or bottom
210       pointers are NULL, these methods will return undef.
211
212       In addition to being somewhat awkard, you will probably never need to
213       use these methods.  A simpler way to retrieve the same information
214       would be to use the at() method described in the next section.
215
216       The right() and down() methods always walk through the tree of the
217       current object.  They do not follow object pointers into the database.
218       Use fetch() (or the deprecated pick() or follow() methods) instead.
219
220   at() method
221           $subtree    = $object->at($tag_path);
222           @values     = $object->at($tag_path);
223
224       at() is a simple way to fetch the portion of the tree that you are
225       interested in.  It takes a single argument, a simple tag or a path.  A
226       simple tag, such as "Full_name", must correspond to a tag in the column
227       immediately to the right of the root of the tree.  A path such as
228       "Address.Mail" is a dot-delimited path to the subtree.  Some examples
229       are given below.
230
231           ($full_name)   = $object->at('Full_name');
232           @address_lines = $object->at('Address.Mail');
233
234       The second line above is equivalent to:
235
236           @address = $object->at('Address')->at('Mail');
237
238       Called without a tag name, at() just dereferences the object, returning
239       whatever is to the right of it, the same as $object->right
240
241       If a path component already has a dot in it, you may escape the dot
242       with a backslash, as in:
243
244           $s=$db->fetch('Sequence','M4');
245           @homologies = $s->at('Homol.DNA_homol.yk192f7\.3';
246
247       This also demonstrates that path components don't necessarily have to
248       be tags, although in practice they usually are.
249
250       at() returns slightly different results depending on the context in
251       which it is called.  In a list context, it returns the column of values
252       to the right of the tag.  However, in a scalar context, it returns the
253       subtree rooted at the tag.  To appreciate the difference, consider
254       these two cases:
255
256           $name1   = $object->at('Full_name');
257           ($name2) = $object->at('Full_name');
258
259       After these two statements run, $name1 will be the tag object named
260       "Full_name", and $name2 will be the text object "Jean Thierry-Mieg",
261       The relationship between the two is that $name1->right leads to $name2.
262       This is a powerful and useful construct, but it can be a trap for the
263       unwary.  If this behavior drives you crazy, use this construct:
264
265           $name1   = $object->at('Full_name')->at();
266
267       For finer control over navigation, path components can include optional
268       indexes to indicate navigation to the right of the current path
269       component.  Here is the syntax:
270
271           $object->at('tag1[index1].tag2[index2].tag3[index3]...');
272
273       Indexes are zero-based.  An index of [0] indicates no movement relative
274       to the current component, and is the same as not using an index at all.
275       An index of [1] navigates one step to the right, [2] moves two steps to
276       the right, and so on.  Using the Thierry-Mieg object as an example
277       again, here are the results of various indexes:
278
279           $object = $db->fetch(Author,"Thierry-Mieg J");
280           $a = $object->at('Address[0]')   --> "Address"
281           $a = $object->at('Address[1]')   --> "Mail"
282           $a = $object->at('Address[2]')   --> "CRBM duCNRS"
283
284       In an array context, the last index in the path does something very
285       interesting.  It returns the entire column of data K steps to the right
286       of the path, where K is the index.  This is used to implement so-called
287       "tag[2]" syntax, and is very useful in some circumstances.  For
288       example, here is a fragment of code to return the Thierry-Mieg object's
289       full address without having to refer to each of the intervening "Mail",
290       "E_Mail" and "Phone" tags explicitly.
291
292          @address = $object->at('Address[2]');
293          --> ('CRBM duCNRS','BP 5051','34033 Montpellier','FRANCE',
294               'mieg@kaa.cnrs-mop.fr,'33-67-613324','33-67-521559')
295
296       Similarly, "tag[3]" will return the column of data three hops to the
297       right of the tag.  "tag[1]" is identical to "tag" (with no index), and
298       will return the column of data to the immediate right.  There is no
299       special behavior associated with using "tag[0]" in an array context; it
300       will always return the subtree rooted at the indicated tag.
301
302       Internal indices such as "Homol[2].BLASTN", do not have special
303       behavior in an array context.  They are always treated as if they were
304       called in a scalar context.
305
306       Also see col() and get().
307
308   get() method
309           $subtree    = $object->get($tag);
310           @values     = $object->get($tag);
311           @values     = $object->get($tag, $position);
312           @values     = $object->get($tag => $subtag, $position);
313
314       The get() method will perform a breadth-first search through the object
315       (columns first, followed by rows) for the tag indicated by the
316       argument, returning the column of the portion of the subtree it points
317       to.  For example, this code fragment will return the value of the "Fax"
318       tag.
319
320           ($fax_no) = $object->get('Fax');
321                --> "33-67-521559"
322
323       The list versus scalar context semantics are the same as in at(), so if
324       you want to retrieve the scalar value pointed to by the indicated tag,
325       either use a list context as shown in the example, above, or a
326       dereference, as in:
327
328            $fax_no = $object->get('Fax');
329                --> "Fax"
330            $fax_no = $object->get('Fax')->at;
331                --> "33-67-521559"
332
333       An optional second argument to get(), $position, allows you to navigate
334       the tree relative to the retrieved subtree.  Like the at() navigational
335       indexes, $position must be a number greater than or equal to zero.  In
336       a scalar context, $position moves rightward through the tree.  In an
337       array context, $position implements "tag[2]" semantics.
338
339       For example:
340
341            $fax_no = $object->get('Fax',0);
342                 --> "Fax"
343
344            $fax_no = $object->get('Fax',1);
345                 --> "33-67-521559"
346
347            $fax_no = $object->get('Fax',2);
348                 --> undef  # nothing beyond the fax number
349
350            @address = $object->get('Address',2);
351                 --> ('CRBM duCNRS','BP 5051','34033 Montpellier','FRANCE',
352                      'mieg@kaa.cnrs-mop.fr,'33-67-613324','33-67-521559')
353
354       It is important to note that get() only traverses tags.  It will not
355       traverse nodes that aren't tags, such as strings, integers or objects.
356       This is in keeping with the behavior of the Ace query language "show"
357       command.
358
359       This restriction can lead to confusing results.  For example, consider
360       the following object:
361
362        Clone: B0280  Position    Map            Sequence-III  Ends   Left   3569
363                                                                      Right  3585
364                                  Pmap           ctg377        -1040  -1024
365                      Positive    Positive_locus nhr-10
366                      Sequence    B0280
367                      Location    RW
368                      FingerPrint Gel_Number     0
369                                  Canonical_for  T20H1
370                                                 K10E5
371                                  Bands          1354          18
372
373       The following attempt to fetch the left and right positions of the
374       clone will fail, because the search for the "Left" and "Right" tags
375       cannot traverse "Sequence-III", which is an object, not a tag:
376
377         my $left = $clone->get('Left');    # will NOT work
378         my $right = $clone->get('Right');  # neither will this one
379
380       You must explicitly step over the non-tag node in order to make this
381       query work.  This syntax will work:
382
383         my $left = $clone->get('Map',1)->get('Left');   # works
384         my $left = $clone->get('Map',1)->get('Right');  # works
385
386       Or you might prefer to use the tag[2] syntax here:
387
388         my($left,$right) = $clone->get('Map',1)->at('Ends[2]');
389
390       Although not frequently used, there is a form of get() which allows you
391       to stack subtags:
392
393           $locus = $object->get('Positive'=>'Positive_locus');
394
395       Only on subtag is allowed.  You can follow this by a position if wish
396       to offset from the subtag.
397
398           $locus = $object->get('Positive'=>'Positive_locus',1);
399
400   search() method
401       This is a deprecated synonym for get().
402
403   Autogenerated Access Methods
404            $scalar = $object->Name_of_tag;
405            $scalar = $object->Name_of_tag($position);
406            @array  = $object->Name_of_tag;
407            @array  = $object->Name_of_tag($position);
408            @array  = $object->Name_of_tag($subtag=>$position);
409            @array  = $object->Name_of_tag(-fill=>$tag);
410
411       The module attempts to autogenerate data access methods as needed.  For
412       example, if you refer to a method named "Fax" (which doesn't correspond
413       to any of the built-in methods), then the code will call the get()
414       method to find a tag named "Fax" and return its contents.
415
416       Unlike get(), this method will always step into objects.  This means
417       that:
418
419          $map = $clone->Map;
420
421       will return the Sequence_Map object pointed to by the Clone's Map tag
422       and not simply a pointer to a portion of the Clone tree.  Therefore
423       autogenerated methods are functionally equivalent to the following:
424
425          $map = $clone->get('Map')->fetch;
426
427       The scalar context semantics are also slightly different.  In a scalar
428       context, the autogenerated function will *always* move one step to the
429       right.
430
431       The list context semantics are identical to get().  If you want to
432       dereference all members of a multivalued tag, you have to do so
433       manually:
434
435         @papers = $author->Paper;
436         foreach (@papers) {
437           my $paper = $_->fetch;
438           print  $paper->asString;
439         }
440
441       You can provide an optional positional index to rapidly navigate
442       through the tree or to obtain tag[2] behavior.  In the following
443       examples, the first two return the object's Fax number, and the third
444       returns all data two hops to the right of Address.
445
446            $object   = $db->fetch(Author => 'Thierry-Mieg J');
447            ($fax_no) = $object->Fax;
448            $fax_no   = $object->Fax(1);
449            @address  = $object->Address(2);
450
451       You may also position at a subtag, using this syntax:
452
453            $representative = $object->Laboratory('Representative');
454
455       Both named tags and positions can be combined as follows:
456
457            $lab_address = $object->Laboratory(Address=>2);
458
459       If you provide a -fill=>$tag argument, then the object fetch will
460       automatically fill the specified subtree, greatly improving
461       performance.  For example:
462
463             $lab_address = $object->Laboratory(-filled=>'Address');
464
465       ** NOTE: In a scalar context, if the node to the right of the tag is **
466       an object, the method will perform an implicit dereference of the **
467       object.  For example, in the case of:
468
469           $lab = $author->Laboratory;
470
471       **NOTE: The object returned is the dereferenced Laboratory object, not
472       a node in the Author object.  You can control this by giving the
473       autogenerated method a numeric offset, such as Laboratory(0) or
474       Laboratory(1).  For backwards compatibility, Laboratory('@') is
475       equivalent to Laboratory(1).
476
477       The semantics of the autogenerated methods have changed subtly between
478       version 1.57 (the last stable release) and version 1.62.  In earlier
479       versions, calling an autogenerated method in a scalar context returned
480       the subtree rooted at the tag.  In the current version, an implicit
481       right() and dereference is performed.
482
483   fetch() method
484           $new_object = $object->fetch;
485           $new_object = $object->fetch($tag);
486
487       Follow object into the database, returning a new object.  This is the
488       best way to follow object references.  For example:
489
490           $laboratory = $object->at('Laboratory')->fetch;
491           print $laboratory->asString;
492
493       Because the previous example is a frequent idiom, the optional $tag
494       argument allows you to combine the two operations into a single one:
495
496           $laboratory = $object->fetch('Laboratory');
497
498   follow() method
499           @papers        = $object->follow('Paper');
500           @filled_papers = $object->follow(-tag=>'Paper',-filled=>1);
501           @filled_papers = $object->follow(-tag=>'Paper',-filled=>'Author');
502
503       The follow() method will follow a tag into the database, dereferencing
504       the column to its right and returning the objects resulting from this
505       operation.  Beware!  If you follow a tag that points to an object, such
506       as the Author "Paper" tag, you will get a list of all the Paper
507       objects.  If you follow a tag that points to a scalar, such as
508       "Full_name", you will get an empty string.  In a scalar context, this
509       method will return the number of objects that would have been followed.
510
511       The full named-argument form of this call accepts the arguments -tag
512       (mandatory) and -filled (optional).  The former points to the tag to
513       follow.  The latter accepts a boolean argument or the name of a subtag.
514       A numeric true argument will return completely "filled" objects,
515       increasing network and memory usage, but possibly boosting performance
516       if you have a high database access latency.  Alternatively, you may
517       provide the name of a tag to follow, in which case just the named
518       portion of the subtree in the followed objects will be filled (v.g.)
519
520       For backward compatability, if follow() is called without any
521       arguments, it will act like fetch().
522
523   pick() method
524       Deprecated method.  This has the same semantics as fetch(), which
525       should be used instead.
526
527   col() method
528            @column = $object->col;
529            @column = $object->col($position);
530
531       col() flattens a portion of the tree by returning the column one hop to
532       the right of the current subtree. You can provide an additional
533       positional index to navigate through the tree using "tag[2]" behavior.
534       This example returns the author's mailing address:
535
536         @mailing_address = $object->at('Address.Mail')->col();
537
538       This example returns the author's entire address including mail, e-mail
539       and phone:
540
541         @address = $object->at('Address')->col(2);
542
543       It is equivalent to any of these calls:
544
545         $object->at('Address[2]');
546         $object->get('Address',2);
547         $object->Address(2);
548
549       Use whatever syntax is most comfortable for you.
550
551       In a scalar context, col() returns the number of items in the column.
552
553   row() method
554            @row=$object->row();
555            @row=$object->row($position);
556
557       row() will return the row of data to the right of the object.  The
558       first member of the list will be the object itself.  In the case of the
559       "Thierry-Mieg J" object, the example below will return the list
560       ('Address','Mail','CRBM duCNRS').
561
562            @row = $object->Address->row();
563
564       You can provide an optional position to move rightward one or more
565       places before retrieving the row.  This code fragment will return
566       ('Mail','CRBM duCNRS'):
567
568            @row = $object->Address->row(1);
569
570       In a scalar context, row() returns the number of items in the row.
571
572   asString() method
573           $object->asString;
574
575       asString() returns a pretty-printed ASCII representation of the object
576       tree.
577
578   asTable() method
579           $object->asTable;
580
581       asTable() returns the object as a tab-delimited text table.
582
583   asAce() method
584           $object->asAce;
585
586       asAce() returns the object as a tab-delimited text table in ".ace"
587       format.
588
589   asHTML() method
590          $object->asHTML;
591          $object->asHTML(\&tree_traversal_code);
592
593       asHTML() returns an HTML 3 table representing the object, suitable for
594       incorporation into a Web browser page.  The callback routine, if
595       provided, will have a chance to modify the object representation before
596       it is incorporated into the table, for example by turning it into an
597       HREF link.  The callback takes a single argument containing the object,
598       and must return a string-valued result.  It may also return a list as
599       its result, in which case the first member of the list is the string
600       representation of the object, and the second member is a boolean
601       indicating whether to prune the table at this level.  For example, you
602       can prune large repetitive lists.
603
604       Here's a complete example:
605
606          sub process_cell {
607            my $obj = shift;
608            return "$obj" unless $obj->isObject || $obj->isTag;
609
610            my @col = $obj->col;
611            my $cnt = scalar(@col);
612            return ("$obj -- $cnt members",1);  # prune
613                   if $cnt > 10                 # if subtree to big
614
615            # tags are bold
616            return "<B>$obj</B>" if $obj->isTag;
617
618            # objects are blue
619            return qq{<FONT COLOR="blue">$obj</FONT>} if $obj->isObject;
620          }
621
622          $object->asHTML(\&process_cell);
623
624   asXML() method
625          $result = $object->asXML;
626
627       asXML() returns a well-formed XML representation of the object.  The
628       particular representation is still under discussion, so this feature is
629       primarily for demonstration.
630
631   asGIF() method
632         ($gif,$boxes) = $object->asGIF();
633         ($gif,$boxes) = $object->asGIF(-clicks=>[[$x1,$y1],[$x2,$y2]...]
634                                        -dimensions=> [$width,$height],
635                                        -coords    => [$top,$bottom],
636                                        -display   => $display_type,
637                                        -view      => $view_type,
638                                        -getcoords => $true_or_false
639                                        );
640
641       asGIF() returns the object as a GIF image.  The contents of the GIF
642       will be whatever xace would ordinarily display in graphics mode, and
643       will vary for different object classes.
644
645       You can optionally provide asGIF with a -clicks argument to simulate
646       the action of a user clicking on the image.  The click coordinates
647       should be formatted as an array reference that contains a series of
648       two-element subarrays, each corresponding to the X and Y coordinates of
649       a single mouse click.  There is currently no way to pass information
650       about middle or right mouse clicks, dragging operations, or keystrokes.
651       You may also specify a -dimensions to control the width and height of
652       the returned GIF.  Since there is no way of obtaining the preferred
653       size of the image in advance, this is not usually useful.
654
655       The optional -display argument allows you to specify an alternate
656       display for the object.  For example, Clones can be displayed either
657       with the PMAP display or with the TREE display.  If not specified, the
658       default display is used.
659
660       The optional -view argument allows you to specify an alternative view
661       for MAP objects only.  If not specified, you'll get the default view.
662
663       The option -coords argument allows you to provide the top and bottom of
664       the display for MAP objects only.  These coordinates are in the map's
665       native coordinate system (cM, bp).  By default, AceDB will show most
666       (but not necessarily all) of the map according to xace's display rules.
667       If you call this method with the -getcoords argument and a true value,
668       it will return a two-element array containing the coordinates of the
669       top and bottom of the map.
670
671       asGIF() returns a two-element array.  The first element is the GIF
672       data.  The second element is an array reference that indicates special
673       areas of the image called "boxes."  Boxes are rectangular areas that
674       surround buttons, and certain displayed objects.  Using the contents of
675       the boxes array, you can turn the GIF image into a client-side image
676       map.  Unfortunately, not everything that is clickable is represented as
677       a box.  You still have to pass clicks on unknown image areas back to
678       the server for processing.
679
680       Each box in the array is a hash reference containing the following
681       keys:
682
683           'coordinates'  => [$left,$top,$right,$bottom]
684           'class'        => object class or "BUTTON"
685           'name'         => object name, if any
686           'comment'      => a text comment of some sort
687
688       coordinates points to an array of points indicating the top-left and
689       bottom-right corners of the rectangle.  class indicates the class of
690       the object this rectangle surrounds.  It may be a database object, or
691       the special word "BUTTON" for one of the display action buttons.  name
692       indicates the name of the object or the button.  comment is some piece
693       of information about the object in question.  You can display it in the
694       status bar of the browser or in a popup window if your browser provides
695       that facility.
696
697   asDNA() and asPeptide() methods
698           $dna = $object->asDNA();
699           $peptide = $object->asPeptide();
700
701       If you are dealing with a sequence object of some sort, these methods
702       will return strings corresponding to the DNA or peptide sequence in
703       FASTA format.
704
705   add_row() method
706           $result_code = $object->add_row($tag=>$value);
707           $result_code = $object->add_row($tag=>[list,of,values]);
708           $result_code = $object->add(-path=>$tag,
709                                       -value=>$value);
710
711       add_row() updates the tree by adding data to the indicated tag path.
712       The example given below adds the value "555-1212" to a new Address
713       entry named "Pager".  You may call add_row() a second time to add a new
714       value under this tag, creating multi-valued entries.
715
716        $object->add_row('Address.Pager'=>'555-1212');
717
718       You may provide a list of values to add an entire row of data.  For
719       example:
720
721        $sequence->add_row('Assembly_tags'=>['Finished Left',38949,38952,'AC3']);
722
723       Actually, the array reference is not entirely necessary, and if you
724       prefer you can use this more concise notation:
725
726        $sequence->add_row('Assembly_tags','Finished Left',38949,38952,'AC3');
727
728       No check is done against the database model for the correct data type
729       or tag path.  The update isn't actually performed until you call
730       commit(), at which time a result code indicates whether the database
731       update was successful.
732
733       You may create objects that reference other objects this way:
734
735           $lab = new Ace::Object('Laboratory','LM',$db);
736           $lab->add_row('Full_name','The Laboratory of Medicine');
737           $lab->add_row('City','Cincinatti');
738           $lab->add_row('Country','USA');
739
740           $author = new Ace::Object('Author','Smith J',$db);
741           $author->add_row('Full_name','Joseph M. Smith');
742           $author->add_row('Laboratory',$lab);
743
744           $lab->commit();
745           $author->commit();
746
747       The result code indicates whether the addition was syntactically
748       correct.  add_row() will fail if you attempt to add a duplicate entry
749       (that is, one with exactly the same tag and value).  In this case, use
750       replace() instead.  Currently there is no checking for an attempt to
751       add multiple values to a single-valued (UNIQUE) tag.  The error will be
752       detected and reported at commit() time however.
753
754       The add() method is an alias for add_row().
755
756       See also the Ace->new() method.
757
758   add_tree()
759         $result_code = $object->add_tree($tag=>$ace_object);
760         $result_code = $object->add_tree(-tag=>$tag,-tree=>$ace_object);
761
762       The add_tree() method will insert an entire Ace subtree into the object
763       to the right of the indicated tag.  This can be used to build up
764       complex Ace objects, or to copy portions of objects from one database
765       to another.  The first argument is a tag path, and the second is the
766       tree that you wish to insert.  As with add_row() the database will only
767       be updated when you call commit().
768
769       When inserting a subtree, you must be careful to remember that
770       everything to the *right* of the node that you are pointing at will be
771       inserted; not the node itself.  For example, given this Sequence
772       object:
773
774         Sequence AC3
775           DB_info     Database    EMBL
776           Assembly_tags   Finished Left   1   4   AC3
777                           Clone left end      1   4   AC3
778                           Clone right end     5512    5515    K07C5
779                                               38949   38952   AC3
780                           Finished Right      38949   38952   AC3
781
782       If we use at('Assembly_tags') to fetch the subtree rooted on the
783       "Assembly_tags" tag, it is the tree to the right of this tag, beginning
784       with "Finished Left", that will be inserted.
785
786       Here is an example of copying the "Assembly_tags" subtree from one
787       database object to another:
788
789        $remote = Ace->connect(-port=>200005)  || die "can't connect";
790        $ac3 = $remote->fetch(Sequence=>'AC3') || die "can't get AC7";
791        my $assembly = $ac3->at('Assembly_tags');
792
793        $local = Ace->connect(-path=>'~acedb') || die "can't connect";
794        $AC3copy = Ace::Object->new(Sequence=>'AC3copy',$local);
795        $AC3copy->add_tree('Assembly_tags'=>$tags);
796        $AC3copy->commit || warn $AC3copy->error;
797
798       Notice that this syntax will not work the way you think it should:
799
800        $AC3copy->add_tree('Assembly_tags'=>$ac3->at('Assembly_tags'));
801
802       This is because call at() in an array context returns the column to the
803       right of the tag, not the tag itself.
804
805       Here's an example of building up a complex structure from scratch using
806       a combination of add() and add_tree():
807
808        $newObj = Ace::Object->new(Sequence=>'A555',$local);
809        my $assembly = Ace::Object->new(tag=>'Assembly_tags');
810        $assembly->add('Finished Left'=>[10,20,'ABC']);
811        $assembly->add('Clone right end'=>[1000,2000,'DEF']);
812        $assembly->add('Clone right end'=>[8000,9876,'FRED']);
813        $assembly->add('Finished Right'=>[1000,3000,'ETHEL']);
814        $newObj->add_tree('Assembly_tags'=>$assembly);
815        $newObj->commit || warn $newObj->error;
816
817   delete() method
818           $result_code = $object->delete($tag_path,$value);
819           $result_code = $object->delete(-path=>$tag_path,
820                                          -value=>$value);
821
822       Delete the indicated tag and value from the object.  This example
823       deletes the address line "FRANCE" from the Author's mailing address:
824
825           $object->delete('Address.Mail','FRANCE');
826
827       No actual database deletion occurs until you call commit().  The
828       delete() result code indicates whether the deletion was successful.
829       Currently it is always true, since the database model is not checked.
830
831   replace() method
832           $result_code = $object->replace($tag_path,$oldvalue,$newvalue);
833           $result_code = $object->replace(-path=>$tag_path,
834                                           -old=>$oldvalue,
835                                           -new=>$newvalue);
836
837       Replaces the indicated tag and value with the new value.  This example
838       changes the address line "FRANCE" to "LANGUEDOC" in the Author's
839       mailing address:
840
841           $object->delete('Address.Mail','FRANCE','LANGUEDOC');
842
843       No actual database changes occur until you call commit().  The delete()
844       result code indicates whether the replace was successful.  Currently is
845       true if the old value was identified.
846
847   commit() method
848            $result_code = $object->commit;
849
850       Commits all add(), replace() and delete() operations to the database.
851       It can also be used to write a completely new object into the database.
852       The result code indicates whether the object was successfully written.
853       If an error occurred, further details can be found in the Ace->error()
854       error string.
855
856   rollback() method
857           $object->rollback;
858
859       Discard all adds, deletions and replacements, returning the object to
860       the state it was in prior to the last commit().
861
862       rollback() works by deleting the object from Perl memory and fetching
863       the object anew from AceDB.  If someone has changed the object in the
864       database while you were working with it, you will see this version, ot
865       the one you originally fetched.
866
867       If you are creating an entirely new object, you must add at least one
868       tag in order to enter the object into the database.
869
870   kill() method
871           $result_code = $object->kill;
872
873       This will remove the object from the database immediately and
874       completely.  It does not wait for a commit(), and does not respond to a
875       rollback().  If successful, you will be left with an empty object that
876       contains just the class and object names.  Use with care!
877
878       In the case of failure, which commonly happens when the database is not
879       open for writing, this method will return undef.  A description of the
880       problem can be found by calling the error() method.
881
882   date_style() method
883          $object->date_style('ace');
884
885       This is a convenience method that can be used to set the date format
886       for all objects returned by the database.  It is exactly equivalent to
887
888          $object->db->date_style('ace');
889
890       Note that the text representation of the date will change for all
891       objects returned from this database, not just the current one.
892
893   isRoot() method
894           print "Top level object" if $object->isRoot;
895
896       This method will return true if the object is a "top level" object,
897       that is the root of an object tree rather than a subtree.
898
899   model() method
900           $model = $object->model;
901
902       This method will return the object's model as an Ace::Model object, or
903       undef if the object does not have a model. See Ace::Model for details.
904
905   timestamp() method
906          $stamp = $object->timestamp;
907
908       The timestamp() method will retrieve the modification time and date
909       from the object.  This works both with top level objects and with
910       subtrees.  Timestamp handling must be turned on in the database, or
911       timestamp() will return undef.
912
913       The returned timestamp is actually a UserSession object which can be
914       printed and explored like any other object.  However, there is
915       currently no useful information in UserSession other than its name.
916
917   comment() method
918          $comment = $object->comment;
919
920       This returns the comment attached to an object or object subtree, if
921       any.  Comments are Comment objects and have the interesting property
922       that a single comment can refer to multiple objects.  If there is no
923       comment attached to the current subtree, this method will return undef.
924
925       Currently you cannot create a new comment in AcePerl or edit an old
926       one.
927
928   error() method
929           $error = $object->error;
930
931       Returns the error from the previous operation, if any.  As in
932       Ace::error(), this string will only have meaning if the previous
933       operation returned a result code indicating an error.
934
935   factory() method
936       WARNING - THIS IS DEFUNCT AND NO LONGER WORKS.  USE THE Ace->class()
937       METHOD INSTEAD
938
939           $package = $object->factory;
940
941       When a root Ace object instantiates its tree of tags and values, it
942       creates a hierarchical structure of Ace::Object objects.  The factory()
943       method determines what class to bless these subsidiary objects into.
944       By default, they are Ace::Object objects, but you can override this
945       method in a child class in order to create more specialized Ace::Object
946       classes.  The method should return a string corresponding to the
947       package to bless the object into.  It receives the current Ace::Object
948       as its first argument.
949
950   debug() method
951           $object->debug(1);
952
953       Change the debugging mode.  A zero turns off debugging messages.
954       Integer values produce debug messages on standard error.  Higher
955       integers produce progressively more verbose messages.  This actually is
956       just a front end to Ace->debug(), so the debugging level is global.
957

SEE ALSO

959       Ace, Ace::Model, Ace::Object, Ace::Local,
960       Ace::Sequence,Ace::Sequence::Multi
961

AUTHOR

963       Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
964       Mieg <mieg@kaa.crbm.cnrs-mop.fr>
965
966       Copyright (c) 1997-1998, Lincoln D. Stein
967
968       This library is free software; you can redistribute it and/or modify it
969       under the same terms as Perl itself.  See DISCLAIMER.txt for
970       disclaimers of warranty.
971
972
973
974perl v5.12.0                      2005-04-20                    Ace::Object(3)
Impressum