1Ace::Object(3) User Contributed Perl Documentation Ace::Object(3)
2
6 Ace::Object - Manipulate Ace Data Objects
7
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 # Inspect the object
16 $r = $sequence->at('Visible.Overlap_Right');
17 @row = $sequence->row;
18 @col = $sequence->col;
19 @tags = $sequence->tags;
20 # Explore object substructure
22 @more_tags = $sequence->at('Visible')->tags;
23 @col = $sequence->at("Visible.$more_tags[1]")->col;
24 # Follow a pointer into database
26 $r = $sequence->at('Visible.Overlap_Right')->fetch;
27 $next = $r->at('Visible.Overlap_left')->fetch;
28 # Classy way to do the same thing
30 $r = $sequence->Overlap_right;
31 $next = $sequence->Overlap_left;
32 # Pretty-print object
34 print $sequence->asString;
35 print $sequence->asTabs;
36 print $sequence->asHTML;
37 # 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 # Rollback changes
45 $sequence->rollback()
46 # Get errors
48 print $sequence->error;
49
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 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 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 For information on connecting to ACEDB databases and querying them, see
66 Ace.
67
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 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 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 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 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 new() method
125 $object = new Ace::Object($class,$name,$database);
126 $object = new Ace::Object(-class=>$class,
127 -name=>$name,
128 -db=>database);
129 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 Arguments can be passed positionally, or as named parameters, as shown
138 above.
139 This routine is usually used internally. See also add_row(),
141 add_tree(), delete() and replace() for ways to manipulate this object.
142 name() method
144 $name = $object->name();
145 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 $object = $db->fetch(Author,"Thierry-Mieg J");
151 print "$object did not write 'Pride and Prejudice.'\n";
152 class() method
154 $class = $object->class();
155 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 db() method
164 $db = $object->db();
165 Return the database that the object is associated with.
167 isClass() method
169 $bool = $object->isClass();
170 Returns true if the object is a class (can be fetched from the
172 database).
173 isTag() method
175 $bool = $object->isTag();
176 Returns true if the object is a tag.
178 tags() method
180 @tags = $object->tags();
181 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 You can fetch tags more deeply nested in the structure by navigating
187 inwards using the methods listed below.
188 right() and down() methods
190 $subtree = $object->right;
191 $subtree = $object->right($position);
192 $subtree = $object->down;
193 $subtree = $object->down($position);
194 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 $full_name = $object->right->right;
202 $full_name = $object->right(2);
203 $city = $object->right->down->down->right->right->down->down;
205 $city = $object->right->down(2)->right(2)->down(2);
206 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 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 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 at() method
221 $subtree = $object->at($tag_path);
222 @values = $object->at($tag_path);
223 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 ($full_name) = $object->at('Full_name');
232 @address_lines = $object->at('Address.Mail');
233 The second line above is equivalent to:
235 @address = $object->at('Address')->at('Mail');
237 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 If a path component already has a dot in it, you may escape the dot
242 with a backslash, as in:
243 $s=$db->fetch('Sequence','M4');
245 @homologies = $s->at('Homol.DNA_homol.yk192f7\.3';
246 This also demonstrates that path components don't necessarily have to
248 be tags, although in practice they usually are.
249 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 $name1 = $object->at('Full_name');
257 ($name2) = $object->at('Full_name');
258 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 $name1 = $object->at('Full_name')->at();
266 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 $object->at('tag1[index1].tag2[index2].tag3[index3]...');
272 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 $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 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 @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 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 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 Also see col() and get().
307 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 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 ($fax_no) = $object->get('Fax');
321 --> "33-67-521559"
322 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 $fax_no = $object->get('Fax');
329 --> "Fax"
330 $fax_no = $object->get('Fax')->at;
331 --> "33-67-521559"
332 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 For example:
340 $fax_no = $object->get('Fax',0);
342 --> "Fax"
343 $fax_no = $object->get('Fax',1);
345 --> "33-67-521559"
346 $fax_no = $object->get('Fax',2);
348 --> undef # nothing beyond the fax number
349 @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 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 This restriction can lead to confusing results. For example, consider
360 the following object:
361 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 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 my $left = $clone->get('Left'); # will NOT work
378 my $right = $clone->get('Right'); # neither will this one
379 You must explicitly step over the non-tag node in order to make this
381 query work. This syntax will work:
382 my $left = $clone->get('Map',1)->get('Left'); # works
384 my $left = $clone->get('Map',1)->get('Right'); # works
385 Or you might prefer to use the tag[2] syntax here:
387 my($left,$right) = $clone->get('Map',1)->at('Ends[2]');
389 Although not frequently used, there is a form of get() which allows you
391 to stack subtags:
392 $locus = $object->get('Positive'=>'Positive_locus');
394 Only on subtag is allowed. You can follow this by a position if wish
396 to offset from the subtag.
397 $locus = $object->get('Positive'=>'Positive_locus',1);
399 search() method
401 This is a deprecated synonym for get().
402 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 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 Unlike get(), this method will always step into objects. This means
417 that:
418 $map = $clone->Map;
420 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 $map = $clone->get('Map')->fetch;
426 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 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 @papers = $author->Paper;
436 foreach (@papers) {
437 my $paper = $_->fetch;
438 print $paper->asString;
439 }
440 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 $object = $db->fetch(Author => 'Thierry-Mieg J');
447 ($fax_no) = $object->Fax;
448 $fax_no = $object->Fax(1);
449 @address = $object->Address(2);
450 You may also position at a subtag, using this syntax:
452 $representative = $object->Laboratory('Representative');
454 Both named tags and positions can be combined as follows:
456 $lab_address = $object->Laboratory(Address=>2);
458 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 $lab_address = $object->Laboratory(-filled=>'Address');
464 ** 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 $lab = $author->Laboratory;
470 **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 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 fetch() method
484 $new_object = $object->fetch;
485 $new_object = $object->fetch($tag);
486 Follow object into the database, returning a new object. This is the
488 best way to follow object references. For example:
489 $laboratory = $object->at('Laboratory')->fetch;
491 print $laboratory->asString;
492 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 $laboratory = $object->fetch('Laboratory');
497 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 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 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 For backward compatability, if follow() is called without any
521 arguments, it will act like fetch().
522 pick() method
524 Deprecated method. This has the same semantics as fetch(), which
525 should be used instead.
526 col() method
528 @column = $object->col;
529 @column = $object->col($position);
530 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 @mailing_address = $object->at('Address.Mail')->col();
537 This example returns the author's entire address including mail, e-mail
539 and phone:
540 @address = $object->at('Address')->col(2);
542 It is equivalent to any of these calls:
544 $object->at('Address[2]');
546 $object->get('Address',2);
547 $object->Address(2);
548 Use whatever syntax is most comfortable for you.
550 In a scalar context, col() returns the number of items in the column.
552 row() method
554 @row=$object->row();
555 @row=$object->row($position);
556 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 @row = $object->Address->row();
563 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 @row = $object->Address->row(1);
569 In a scalar context, row() returns the number of items in the row.
571 asString() method
573 $object->asString;
574 asString() returns a pretty-printed ASCII representation of the object
576 tree.
577 asTable() method
579 $object->asTable;
580 asTable() returns the object as a tab-delimited text table.
582 asAce() method
584 $object->asAce;
585 asAce() returns the object as a tab-delimited text table in ".ace"
587 format.
588 asHTML() method
590 $object->asHTML;
591 $object->asHTML(\&tree_traversal_code);
592 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 Here's a complete example:
605 sub process_cell {
607 my $obj = shift;
608 return "$obj" unless $obj->isObject || $obj->isTag;
609 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 # tags are bold
616 return "<B>$obj</B>" if $obj->isTag;
617 # objects are blue
619 return qq{<FONT COLOR="blue">$obj</FONT>} if $obj->isObject;
620 }
621 $object->asHTML(\&process_cell);
623 asXML() method
625 $result = $object->asXML;
626 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 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 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 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 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 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 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 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 Each box in the array is a hash reference containing the following
681 keys:
682 '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 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 asDNA() and asPeptide() methods
698 $dna = $object->asDNA();
699 $peptide = $object->asPeptide();
700 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 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 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 $object->add_row('Address.Pager'=>'555-1212');
717 You may provide a list of values to add an entire row of data. For
719 example:
720 $sequence->add_row('Assembly_tags'=>['Finished Left',38949,38952,'AC3']);
722 Actually, the array reference is not entirely necessary, and if you
724 prefer you can use this more concise notation:
725 $sequence->add_row('Assembly_tags','Finished Left',38949,38952,'AC3');
727 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 You may create objects that reference other objects this way:
734 $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 $author = new Ace::Object('Author','Smith J',$db);
741 $author->add_row('Full_name','Joseph M. Smith');
742 $author->add_row('Laboratory',$lab);
743 $lab->commit();
745 $author->commit();
746 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 The add() method is an alias for add_row().
755 See also the Ace->new() method.
757 add_tree()
759 $result_code = $object->add_tree($tag=>$ace_object);
760 $result_code = $object->add_tree(-tag=>$tag,-tree=>$ace_object);
761 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 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 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 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 Here is an example of copying the "Assembly_tags" subtree from one
787 database object to another:
788 $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 $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 Notice that this syntax will not work the way you think it should:
799 $AC3copy->add_tree('Assembly_tags'=>$ac3->at('Assembly_tags'));
801 This is because call at() in an array context returns the column to the
803 right of the tag, not the tag itself.
804 Here's an example of building up a complex structure from scratch using
806 a combination of add() and add_tree():
807 $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 delete() method
818 $result_code = $object->delete($tag_path,$value);
819 $result_code = $object->delete(-path=>$tag_path,
820 -value=>$value);
821 Delete the indicated tag and value from the object. This example
823 deletes the address line "FRANCE" from the Author's mailing address:
824 $object->delete('Address.Mail','FRANCE');
826 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 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 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 $object->delete('Address.Mail','FRANCE','LANGUEDOC');
842 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 commit() method
848 $result_code = $object->commit;
849 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 rollback() method
857 $object->rollback;
858 Discard all adds, deletions and replacements, returning the object to
860 the state it was in prior to the last commit().
861 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 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 kill() method
871 $result_code = $object->kill;
872 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 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 date_style() method
883 $object->date_style('ace');
884 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 $object->db->date_style('ace');
889 Note that the text representation of the date will change for all
891 objects returned from this database, not just the current one.
892 isRoot() method
894 print "Top level object" if $object->isRoot;
895 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 model() method
900 $model = $object->model;
901 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 timestamp() method
906 $stamp = $object->timestamp;
907 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 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 comment() method
918 $comment = $object->comment;
919 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 Currently you cannot create a new comment in AcePerl or edit an old
926 one.
927 error() method
929 $error = $object->error;
930 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 factory() method
936 WARNING - THIS IS DEFUNCT AND NO LONGER WORKS. USE THE Ace->class()
937 METHOD INSTEAD
938 $package = $object->factory;
940 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 debug() method
951 $object->debug(1);
952 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
959 Ace, Ace::Model, Ace::Object, Ace::Local,
960 Ace::Sequence,Ace::Sequence::Multi
961
963 Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
964 Mieg <mieg@kaa.crbm.cnrs-mop.fr>
965 Copyright (c) 1997-1998, Lincoln D. Stein
967 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.
971perl v5.12.0 2005-04-20 Ace::Object(3)