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 data‐
52 bases. Currently there is only one type of Ace::Object, but this may
53 change in the future to support more interesting object-specific behav‐
54 iors.
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 biologi‐
108 cal types, such as "dna" and "peptide." Another fundamental type is
109 "tag," which is a text identifier used to label portions of the tree.
110 Examples of tags include "Paper" and "Laboratory" in the example above.
111 In addition to these built-in types, there are constructed types known
113 as classes. These types are specified by the data model. In the above
114 example, "Thierry-Mieg J" is an object of the "Author" class, and
115 "Genome Project Database" is an object of the "Paper" class. An inter‐
116 esting feature of objects is that you can follow them into the data‐
117 base, retrieving further information. For example, after retrieving
118 the "Genome Project Database" Paper from the Author object, you could
119 fetch more information about it, either by following its right pointer,
120 or by using one of the specialized navigation routines described below.
121 new() method
123 $object = new Ace::Object($class,$name,$database);
125 $object = new Ace::Object(-class=>$class,
126 -name=>$name,
127 -db=>database);
128 You can create a new Ace::Object from scratch by calling the new() rou‐
130 tine with the object's class, its identifier and a handle to the data‐
131 base to create it in. The object won't actually be created in the
132 database until you add() one or more tags to it and commit() it (see
133 below). If you do not provide a database handle, the object will be
134 created in memory only.
135 Arguments can be passed positionally, or as named parameters, as shown
137 above.
138 This routine is usually used internally. See also add_row(),
140 add_tree(), delete() and replace() for ways to manipulate this object.
141 name() method
143 $name = $object->name();
145 Return the name of the Ace::Object. This happens automatically when‐
147 ever you use the object in a context that requires a string or a num‐
148 ber. 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();
156 Return the class of the object. The return value may be one of
158 "float," "int," "date," "tag," "txt," "dna," "peptide," and "scalar."
159 (The last is used internally by Perl to represent objects created pro‐
160 gramatically prior to committing them to the database.) The class may
161 also be a user-constructed type such as Sequence, Clone or Author.
162 These user-constructed types usually have an initial capital letter.
163 db() method
165 $db = $object->db();
167 Return the database that the object is associated with.
169 isClass() method
171 $bool = $object->isClass();
173 Returns true if the object is a class (can be fetched from the data‐
175 base).
176 isTag() method
178 $bool = $object->isTag();
180 Returns true if the object is a tag.
182 tags() method
184 @tags = $object->tags();
186 Return all the top-level tags in the object as a list. In the Author
188 example above, the returned list would be ('Full_name','Labora‐
189 tory','Address','Paper').
190 You can fetch tags more deeply nested in the structure by navigating
192 inwards using the methods listed below.
193 right() and down() methods
195 $subtree = $object->right;
197 $subtree = $object->right($position);
198 $subtree = $object->down;
199 $subtree = $object->down($position);
200 right() and down() provide a low-level way of traversing the tree
202 structure by following the tree's right and down pointers. Called
203 without any arguments, these two methods will move one step. Called
204 with a numeric argument >= 0 they will move the indicated number of
205 steps (zero indicates no movement).
206 $full_name = $object->right->right;
208 $full_name = $object->right(2);
209 $city = $object->right->down->down->right->right->down->down;
211 $city = $object->right->down(2)->right(2)->down(2);
212 If $object contains the "Thierry-Mieg J" Author object, then the first
214 series of accesses shown above retrieves the string "Jean Thierry-Mieg"
215 and the second retrieves "34033 Montpellier." If the right or bottom
216 pointers are NULL, these methods will return undef.
217 In addition to being somewhat awkard, you will probably never need to
219 use these methods. A simpler way to retrieve the same information
220 would be to use the at() method described in the next section.
221 The right() and down() methods always walk through the tree of the cur‐
223 rent object. They do not follow object pointers into the database.
224 Use fetch() (or the deprecated pick() or follow() methods) instead.
225 at() method
227 $subtree = $object->at($tag_path);
229 @values = $object->at($tag_path);
230 at() is a simple way to fetch the portion of the tree that you are
232 interested in. It takes a single argument, a simple tag or a path. A
233 simple tag, such as "Full_name", must correspond to a tag in the column
234 immediately to the right of the root of the tree. A path such as
235 "Address.Mail" is a dot-delimited path to the subtree. Some examples
236 are given below.
237 ($full_name) = $object->at('Full_name');
239 @address_lines = $object->at('Address.Mail');
240 The second line above is equivalent to:
242 @address = $object->at('Address')->at('Mail');
244 Called without a tag name, at() just dereferences the object, returning
246 whatever is to the right of it, the same as $object->right
247 If a path component already has a dot in it, you may escape the dot
249 with a backslash, as in:
250 $s=$db->fetch('Sequence','M4');
252 @homologies = $s->at('Homol.DNA_homol.yk192f7\.3';
253 This also demonstrates that path components don't necessarily have to
255 be tags, although in practice they usually are.
256 at() returns slightly different results depending on the context in
258 which it is called. In a list context, it returns the column of values
259 to the right of the tag. However, in a scalar context, it returns the
260 subtree rooted at the tag. To appreciate the difference, consider
261 these two cases:
262 $name1 = $object->at('Full_name');
264 ($name2) = $object->at('Full_name');
265 After these two statements run, $name1 will be the tag object named
267 "Full_name", and $name2 will be the text object "Jean Thierry-Mieg",
268 The relationship between the two is that $name1->right leads to $name2.
269 This is a powerful and useful construct, but it can be a trap for the
270 unwary. If this behavior drives you crazy, use this construct:
271 $name1 = $object->at('Full_name')->at();
273 For finer control over navigation, path components can include optional
275 indexes to indicate navigation to the right of the current path compo‐
276 nent. Here is the syntax:
277 $object->at('tag1[index1].tag2[index2].tag3[index3]...');
279 Indexes are zero-based. An index of [0] indicates no movement relative
281 to the current component, and is the same as not using an index at all.
282 An index of [1] navigates one step to the right, [2] moves two steps to
283 the right, and so on. Using the Thierry-Mieg object as an example
284 again, here are the results of various indexes:
285 $object = $db->fetch(Author,"Thierry-Mieg J");
287 $a = $object->at('Address[0]') --> "Address"
288 $a = $object->at('Address[1]') --> "Mail"
289 $a = $object->at('Address[2]') --> "CRBM duCNRS"
290 In an array context, the last index in the path does something very
292 interesting. It returns the entire column of data K steps to the right
293 of the path, where K is the index. This is used to implement so-called
294 "tag[2]" syntax, and is very useful in some circumstances. For exam‐
295 ple, here is a fragment of code to return the Thierry-Mieg object's
296 full address without having to refer to each of the intervening "Mail",
297 "E_Mail" and "Phone" tags explicitly.
298 @address = $object->at('Address[2]');
300 --> ('CRBM duCNRS','BP 5051','34033 Montpellier','FRANCE',
301 'mieg@kaa.cnrs-mop.fr,'33-67-613324','33-67-521559')
302 Similarly, "tag[3]" will return the column of data three hops to the
304 right of the tag. "tag[1]" is identical to "tag" (with no index), and
305 will return the column of data to the immediate right. There is no
306 special behavior associated with using "tag[0]" in an array context; it
307 will always return the subtree rooted at the indicated tag.
308 Internal indices such as "Homol[2].BLASTN", do not have special behav‐
310 ior in an array context. They are always treated as if they were
311 called in a scalar context.
312 Also see col() and get().
314 get() method
316 $subtree = $object->get($tag);
318 @values = $object->get($tag);
319 @values = $object->get($tag, $position);
320 @values = $object->get($tag => $subtag, $position);
321 The get() method will perform a breadth-first search through the object
323 (columns first, followed by rows) for the tag indicated by the argu‐
324 ment, returning the column of the portion of the subtree it points to.
325 For example, this code fragment will return the value of the "Fax" tag.
326 ($fax_no) = $object->get('Fax');
328 --> "33-67-521559"
329 The list versus scalar context semantics are the same as in at(), so if
331 you want to retrieve the scalar value pointed to by the indicated tag,
332 either use a list context as shown in the example, above, or a derefer‐
333 ence, as in:
334 $fax_no = $object->get('Fax');
336 --> "Fax"
337 $fax_no = $object->get('Fax')->at;
338 --> "33-67-521559"
339 An optional second argument to get(), $position, allows you to navigate
341 the tree relative to the retrieved subtree. Like the at() navigational
342 indexes, $position must be a number greater than or equal to zero. In
343 a scalar context, $position moves rightward through the tree. In an
344 array context, $position implements "tag[2]" semantics.
345 For example:
347 $fax_no = $object->get('Fax',0);
349 --> "Fax"
350 $fax_no = $object->get('Fax',1);
352 --> "33-67-521559"
353 $fax_no = $object->get('Fax',2);
355 --> undef # nothing beyond the fax number
356 @address = $object->get('Address',2);
358 --> ('CRBM duCNRS','BP 5051','34033 Montpellier','FRANCE',
359 'mieg@kaa.cnrs-mop.fr,'33-67-613324','33-67-521559')
360 It is important to note that get() only traverses tags. It will not
362 traverse nodes that aren't tags, such as strings, integers or objects.
363 This is in keeping with the behavior of the Ace query language "show"
364 command.
365 This restriction can lead to confusing results. For example, consider
367 the following object:
368 Clone: B0280 Position Map Sequence-III Ends Left 3569
370 Right 3585
371 Pmap ctg377 -1040 -1024
372 Positive Positive_locus nhr-10
373 Sequence B0280
374 Location RW
375 FingerPrint Gel_Number 0
376 Canonical_for T20H1
377 K10E5
378 Bands 1354 18
379 The following attempt to fetch the left and right positions of the
381 clone will fail, because the search for the "Left" and "Right" tags
382 cannot traverse "Sequence-III", which is an object, not a tag:
383 my $left = $clone->get('Left'); # will NOT work
385 my $right = $clone->get('Right'); # neither will this one
386 You must explicitly step over the non-tag node in order to make this
388 query work. This syntax will work:
389 my $left = $clone->get('Map',1)->get('Left'); # works
391 my $left = $clone->get('Map',1)->get('Right'); # works
392 Or you might prefer to use the tag[2] syntax here:
394 my($left,$right) = $clone->get('Map',1)->at('Ends[2]');
396 Although not frequently used, there is a form of get() which allows you
398 to stack subtags:
399 $locus = $object->get('Positive'=>'Positive_locus');
401 Only on subtag is allowed. You can follow this by a position if wish
403 to offset from the subtag.
404 $locus = $object->get('Positive'=>'Positive_locus',1);
406 search() method
408 This is a deprecated synonym for get().
410 Autogenerated Access Methods
412 $scalar = $object->Name_of_tag;
414 $scalar = $object->Name_of_tag($position);
415 @array = $object->Name_of_tag;
416 @array = $object->Name_of_tag($position);
417 @array = $object->Name_of_tag($subtag=>$position);
418 @array = $object->Name_of_tag(-fill=>$tag);
419 The module attempts to autogenerate data access methods as needed. For
421 example, if you refer to a method named "Fax" (which doesn't correspond
422 to any of the built-in methods), then the code will call the get()
423 method to find a tag named "Fax" and return its contents.
424 Unlike get(), this method will always step into objects. This means
426 that:
427 $map = $clone->Map;
429 will return the Sequence_Map object pointed to by the Clone's Map tag
431 and not simply a pointer to a portion of the Clone tree. Therefore
432 autogenerated methods are functionally equivalent to the following:
433 $map = $clone->get('Map')->fetch;
435 The scalar context semantics are also slightly different. In a scalar
437 context, the autogenerated function will *always* move one step to the
438 right.
439 The list context semantics are identical to get(). If you want to
441 dereference all members of a multivalued tag, you have to do so manu‐
442 ally:
443 @papers = $author->Paper;
445 foreach (@papers) {
446 my $paper = $_->fetch;
447 print $paper->asString;
448 }
449 You can provide an optional positional index to rapidly navigate
451 through the tree or to obtain tag[2] behavior. In the following exam‐
452 ples, the first two return the object's Fax number, and the third
453 returns all data two hops to the right of Address.
454 $object = $db->fetch(Author => 'Thierry-Mieg J');
456 ($fax_no) = $object->Fax;
457 $fax_no = $object->Fax(1);
458 @address = $object->Address(2);
459 You may also position at a subtag, using this syntax:
461 $representative = $object->Laboratory('Representative');
463 Both named tags and positions can be combined as follows:
465 $lab_address = $object->Laboratory(Address=>2);
467 If you provide a -fill=>$tag argument, then the object fetch will auto‐
469 matically fill the specified subtree, greatly improving performance.
470 For example:
471 $lab_address = $object->Laboratory(-filled=>'Address');
473 ** NOTE: In a scalar context, if the node to the right of the tag is **
475 an object, the method will perform an implicit dereference of the **
476 object. For example, in the case of:
477 $lab = $author->Laboratory;
479 **NOTE: The object returned is the dereferenced Laboratory object, not
481 a node in the Author object. You can control this by giving the auto‐
482 generated method a numeric offset, such as Laboratory(0) or Labora‐
483 tory(1). For backwards compatibility, Laboratory('@') is equivalent to
484 Laboratory(1).
485 The semantics of the autogenerated methods have changed subtly between
487 version 1.57 (the last stable release) and version 1.62. In earlier
488 versions, calling an autogenerated method in a scalar context returned
489 the subtree rooted at the tag. In the current version, an implicit
490 right() and dereference is performed.
491 fetch() method
493 $new_object = $object->fetch;
495 $new_object = $object->fetch($tag);
496 Follow object into the database, returning a new object. This is the
498 best way to follow object references. For example:
499 $laboratory = $object->at('Laboratory')->fetch;
501 print $laboratory->asString;
502 Because the previous example is a frequent idiom, the optional $tag
504 argument allows you to combine the two operations into a single one:
505 $laboratory = $object->fetch('Laboratory');
507 follow() method
509 @papers = $object->follow('Paper');
511 @filled_papers = $object->follow(-tag=>'Paper',-filled=>1);
512 @filled_papers = $object->follow(-tag=>'Paper',-filled=>'Author');
513 The follow() method will follow a tag into the database, dereferencing
515 the column to its right and returning the objects resulting from this
516 operation. Beware! If you follow a tag that points to an object, such
517 as the Author "Paper" tag, you will get a list of all the Paper
518 objects. If you follow a tag that points to a scalar, such as
519 "Full_name", you will get an empty string. In a scalar context, this
520 method will return the number of objects that would have been followed.
521 The full named-argument form of this call accepts the arguments -tag
523 (mandatory) and -filled (optional). The former points to the tag to
524 follow. The latter accepts a boolean argument or the name of a subtag.
525 A numeric true argument will return completely "filled" objects,
526 increasing network and memory usage, but possibly boosting performance
527 if you have a high database access latency. Alternatively, you may
528 provide the name of a tag to follow, in which case just the named por‐
529 tion of the subtree in the followed objects will be filled (v.g.)
530 For backward compatability, if follow() is called without any argu‐
532 ments, it will act like fetch().
533 pick() method
535 Deprecated method. This has the same semantics as fetch(), which
537 should be used instead.
538 col() method
540 @column = $object->col;
542 @column = $object->col($position);
543 col() flattens a portion of the tree by returning the column one hop to
545 the right of the current subtree. You can provide an additional posi‐
546 tional index to navigate through the tree using "tag[2]" behavior.
547 This example returns the author's mailing address:
548 @mailing_address = $object->at('Address.Mail')->col();
550 This example returns the author's entire address including mail, e-mail
552 and phone:
553 @address = $object->at('Address')->col(2);
555 It is equivalent to any of these calls:
557 $object->at('Address[2]');
559 $object->get('Address',2);
560 $object->Address(2);
561 Use whatever syntax is most comfortable for you.
563 In a scalar context, col() returns the number of items in the column.
565 row() method
567 @row=$object->row();
569 @row=$object->row($position);
570 row() will return the row of data to the right of the object. The
572 first member of the list will be the object itself. In the case of the
573 "Thierry-Mieg J" object, the example below will return the list
574 ('Address','Mail','CRBM duCNRS').
575 @row = $object->Address->row();
577 You can provide an optional position to move rightward one or more
579 places before retrieving the row. This code fragment will return
580 ('Mail','CRBM duCNRS'):
581 @row = $object->Address->row(1);
583 In a scalar context, row() returns the number of items in the row.
585 asString() method
587 $object->asString;
589 asString() returns a pretty-printed ASCII representation of the object
591 tree.
592 asTable() method
594 $object->asTable;
596 asTable() returns the object as a tab-delimited text table.
598 asAce() method
600 $object->asAce;
602 asAce() returns the object as a tab-delimited text table in ".ace" for‐
604 mat.
605 asHTML() method
607 $object->asHTML;
609 $object->asHTML(\&tree_traversal_code);
610 asHTML() returns an HTML 3 table representing the object, suitable for
612 incorporation into a Web browser page. The callback routine, if pro‐
613 vided, will have a chance to modify the object representation before it
614 is incorporated into the table, for example by turning it into an HREF
615 link. The callback takes a single argument containing the object, and
616 must return a string-valued result. It may also return a list as its
617 result, in which case the first member of the list is the string repre‐
618 sentation of the object, and the second member is a boolean indicating
619 whether to prune the table at this level. For example, you can prune
620 large repetitive lists.
621 Here's a complete example:
623 sub process_cell {
625 my $obj = shift;
626 return "$obj" unless $obj->isObject ⎪⎪ $obj->isTag;
627 my @col = $obj->col;
629 my $cnt = scalar(@col);
630 return ("$obj -- $cnt members",1); # prune
631 if $cnt > 10 # if subtree to big
632 # tags are bold
634 return "<B>$obj</B>" if $obj->isTag;
635 # objects are blue
637 return qq{<FONT COLOR="blue">$obj</FONT>} if $obj->isObject;
638 }
639 $object->asHTML(\&process_cell);
641 asXML() method
643 $result = $object->asXML;
645 asXML() returns a well-formed XML representation of the object. The
647 particular representation is still under discussion, so this feature is
648 primarily for demonstration.
649 asGIF() method
651 ($gif,$boxes) = $object->asGIF();
653 ($gif,$boxes) = $object->asGIF(-clicks=>[[$x1,$y1],[$x2,$y2]...]
654 -dimensions=> [$width,$height],
655 -coords => [$top,$bottom],
656 -display => $display_type,
657 -view => $view_type,
658 -getcoords => $true_or_false
659 );
660 asGIF() returns the object as a GIF image. The contents of the GIF
662 will be whatever xace would ordinarily display in graphics mode, and
663 will vary for different object classes.
664 You can optionally provide asGIF with a -clicks argument to simulate
666 the action of a user clicking on the image. The click coordinates
667 should be formatted as an array reference that contains a series of
668 two-element subarrays, each corresponding to the X and Y coordinates of
669 a single mouse click. There is currently no way to pass information
670 about middle or right mouse clicks, dragging operations, or keystrokes.
671 You may also specify a -dimensions to control the width and height of
672 the returned GIF. Since there is no way of obtaining the preferred
673 size of the image in advance, this is not usually useful.
674 The optional -display argument allows you to specify an alternate dis‐
676 play for the object. For example, Clones can be displayed either with
677 the PMAP display or with the TREE display. If not specified, the
678 default display is used.
679 The optional -view argument allows you to specify an alternative view
681 for MAP objects only. If not specified, you'll get the default view.
682 The option -coords argument allows you to provide the top and bottom of
684 the display for MAP objects only. These coordinates are in the map's
685 native coordinate system (cM, bp). By default, AceDB will show most
686 (but not necessarily all) of the map according to xace's display rules.
687 If you call this method with the -getcoords argument and a true value,
688 it will return a two-element array containing the coordinates of the
689 top and bottom of the map.
690 asGIF() returns a two-element array. The first element is the GIF
692 data. The second element is an array reference that indicates special
693 areas of the image called "boxes." Boxes are rectangular areas that
694 surround buttons, and certain displayed objects. Using the contents of
695 the boxes array, you can turn the GIF image into a client-side image
696 map. Unfortunately, not everything that is clickable is represented as
697 a box. You still have to pass clicks on unknown image areas back to
698 the server for processing.
699 Each box in the array is a hash reference containing the following
701 keys:
702 'coordinates' => [$left,$top,$right,$bottom]
704 'class' => object class or "BUTTON"
705 'name' => object name, if any
706 'comment' => a text comment of some sort
707 coordinates points to an array of points indicating the top-left and
709 bottom-right corners of the rectangle. class indicates the class of
710 the object this rectangle surrounds. It may be a database object, or
711 the special word "BUTTON" for one of the display action buttons. name
712 indicates the name of the object or the button. comment is some piece
713 of information about the object in question. You can display it in the
714 status bar of the browser or in a popup window if your browser provides
715 that facility.
716 asDNA() and asPeptide() methods
718 $dna = $object->asDNA();
720 $peptide = $object->asPeptide();
721 If you are dealing with a sequence object of some sort, these methods
723 will return strings corresponding to the DNA or peptide sequence in
724 FASTA format.
725 add_row() method
727 $result_code = $object->add_row($tag=>$value);
729 $result_code = $object->add_row($tag=>[list,of,values]);
730 $result_code = $object->add(-path=>$tag,
731 -value=>$value);
732 add_row() updates the tree by adding data to the indicated tag path.
734 The example given below adds the value "555-1212" to a new Address
735 entry named "Pager". You may call add_row() a second time to add a new
736 value under this tag, creating multi-valued entries.
737 $object->add_row('Address.Pager'=>'555-1212');
739 You may provide a list of values to add an entire row of data. For
741 example:
742 $sequence->add_row('Assembly_tags'=>['Finished Left',38949,38952,'AC3']);
744 Actually, the array reference is not entirely necessary, and if you
746 prefer you can use this more concise notation:
747 $sequence->add_row('Assembly_tags','Finished Left',38949,38952,'AC3');
749 No check is done against the database model for the correct data type
751 or tag path. The update isn't actually performed until you call com‐
752 mit(), at which time a result code indicates whether the database
753 update was successful.
754 You may create objects that reference other objects this way:
756 $lab = new Ace::Object('Laboratory','LM',$db);
758 $lab->add_row('Full_name','The Laboratory of Medicine');
759 $lab->add_row('City','Cincinatti');
760 $lab->add_row('Country','USA');
761 $author = new Ace::Object('Author','Smith J',$db);
763 $author->add_row('Full_name','Joseph M. Smith');
764 $author->add_row('Laboratory',$lab);
765 $lab->commit();
767 $author->commit();
768 The result code indicates whether the addition was syntactically cor‐
770 rect. add_row() will fail if you attempt to add a duplicate entry
771 (that is, one with exactly the same tag and value). In this case, use
772 replace() instead. Currently there is no checking for an attempt to
773 add multiple values to a single-valued (UNIQUE) tag. The error will be
774 detected and reported at commit() time however.
775 The add() method is an alias for add_row().
777 See also the Ace->new() method.
779 add_tree()
781 $result_code = $object->add_tree($tag=>$ace_object);
783 $result_code = $object->add_tree(-tag=>$tag,-tree=>$ace_object);
784 The add_tree() method will insert an entire Ace subtree into the object
786 to the right of the indicated tag. This can be used to build up com‐
787 plex Ace objects, or to copy portions of objects from one database to
788 another. The first argument is a tag path, and the second is the tree
789 that you wish to insert. As with add_row() the database will only be
790 updated when you call commit().
791 When inserting a subtree, you must be careful to remember that every‐
793 thing to the *right* of the node that you are pointing at will be
794 inserted; not the node itself. For example, given this Sequence
795 object:
796 Sequence AC3
798 DB_info Database EMBL
799 Assembly_tags Finished Left 1 4 AC3
800 Clone left end 1 4 AC3
801 Clone right end 5512 5515 K07C5
802 38949 38952 AC3
803 Finished Right 38949 38952 AC3
804 If we use at('Assembly_tags') to fetch the subtree rooted on the
806 "Assembly_tags" tag, it is the tree to the right of this tag, beginning
807 with "Finished Left", that will be inserted.
808 Here is an example of copying the "Assembly_tags" subtree from one
810 database object to another:
811 $remote = Ace->connect(-port=>200005) ⎪⎪ die "can't connect";
813 $ac3 = $remote->fetch(Sequence=>'AC3') ⎪⎪ die "can't get AC7";
814 my $assembly = $ac3->at('Assembly_tags');
815 $local = Ace->connect(-path=>'~acedb') ⎪⎪ die "can't connect";
817 $AC3copy = Ace::Object->new(Sequence=>'AC3copy',$local);
818 $AC3copy->add_tree('Assembly_tags'=>$tags);
819 $AC3copy->commit ⎪⎪ warn $AC3copy->error;
820 Notice that this syntax will not work the way you think it should:
822 $AC3copy->add_tree('Assembly_tags'=>$ac3->at('Assembly_tags'));
824 This is because call at() in an array context returns the column to the
826 right of the tag, not the tag itself.
827 Here's an example of building up a complex structure from scratch using
829 a combination of add() and add_tree():
830 $newObj = Ace::Object->new(Sequence=>'A555',$local);
832 my $assembly = Ace::Object->new(tag=>'Assembly_tags');
833 $assembly->add('Finished Left'=>[10,20,'ABC']);
834 $assembly->add('Clone right end'=>[1000,2000,'DEF']);
835 $assembly->add('Clone right end'=>[8000,9876,'FRED']);
836 $assembly->add('Finished Right'=>[1000,3000,'ETHEL']);
837 $newObj->add_tree('Assembly_tags'=>$assembly);
838 $newObj->commit ⎪⎪ warn $newObj->error;
839 delete() method
841 $result_code = $object->delete($tag_path,$value);
843 $result_code = $object->delete(-path=>$tag_path,
844 -value=>$value);
845 Delete the indicated tag and value from the object. This example
847 deletes the address line "FRANCE" from the Author's mailing address:
848 $object->delete('Address.Mail','FRANCE');
850 No actual database deletion occurs until you call commit(). The
852 delete() result code indicates whether the deletion was successful.
853 Currently it is always true, since the database model is not checked.
854 replace() method
856 $result_code = $object->replace($tag_path,$oldvalue,$newvalue);
858 $result_code = $object->replace(-path=>$tag_path,
859 -old=>$oldvalue,
860 -new=>$newvalue);
861 Replaces the indicated tag and value with the new value. This example
863 changes the address line "FRANCE" to "LANGUEDOC" in the Author's mail‐
864 ing address:
865 $object->delete('Address.Mail','FRANCE','LANGUEDOC');
867 No actual database changes occur until you call commit(). The delete()
869 result code indicates whether the replace was successful. Currently is
870 true if the old value was identified.
871 commit() method
873 $result_code = $object->commit;
875 Commits all add(), replace() and delete() operations to the database.
877 It can also be used to write a completely new object into the database.
878 The result code indicates whether the object was successfully written.
879 If an error occurred, further details can be found in the Ace->error()
880 error string.
881 rollback() method
883 $object->rollback;
885 Discard all adds, deletions and replacements, returning the object to
887 the state it was in prior to the last commit().
888 rollback() works by deleting the object from Perl memory and fetching
890 the object anew from AceDB. If someone has changed the object in the
891 database while you were working with it, you will see this version, ot
892 the one you originally fetched.
893 If you are creating an entirely new object, you must add at least one
895 tag in order to enter the object into the database.
896 kill() method
898 $result_code = $object->kill;
900 This will remove the object from the database immediately and com‐
902 pletely. It does not wait for a commit(), and does not respond to a
903 rollback(). If successful, you will be left with an empty object that
904 contains just the class and object names. Use with care!
905 In the case of failure, which commonly happens when the database is not
907 open for writing, this method will return undef. A description of the
908 problem can be found by calling the error() method.
909 date_style() method
911 $object->date_style('ace');
913 This is a convenience method that can be used to set the date format
915 for all objects returned by the database. It is exactly equivalent to
916 $object->db->date_style('ace');
918 Note that the text representation of the date will change for all
920 objects returned from this database, not just the current one.
921 isRoot() method
923 print "Top level object" if $object->isRoot;
925 This method will return true if the object is a "top level" object,
927 that is the root of an object tree rather than a subtree.
928 model() method
930 $model = $object->model;
932 This method will return the object's model as an Ace::Model object, or
934 undef if the object does not have a model. See Ace::Model for details.
935 timestamp() method
937 $stamp = $object->timestamp;
939 The timestamp() method will retrieve the modification time and date
941 from the object. This works both with top level objects and with sub‐
942 trees. Timestamp handling must be turned on in the database, or time‐
943 stamp() will return undef.
944 The returned timestamp is actually a UserSession object which can be
946 printed and explored like any other object. However, there is cur‐
947 rently no useful information in UserSession other than its name.
948 comment() method
950 $comment = $object->comment;
952 This returns the comment attached to an object or object subtree, if
954 any. Comments are Comment objects and have the interesting property
955 that a single comment can refer to multiple objects. If there is no
956 comment attached to the current subtree, this method will return undef.
957 Currently you cannot create a new comment in AcePerl or edit an old
959 one.
960 error() method
962 $error = $object->error;
964 Returns the error from the previous operation, if any. As in
966 Ace::error(), this string will only have meaning if the previous opera‐
967 tion returned a result code indicating an error.
968 factory() method
970 WARNING - THIS IS DEFUNCT AND NO LONGER WORKS. USE THE Ace->class()
972 METHOD INSTEAD
973 $package = $object->factory;
975 When a root Ace object instantiates its tree of tags and values, it
977 creates a hierarchical structure of Ace::Object objects. The factory()
978 method determines what class to bless these subsidiary objects into.
979 By default, they are Ace::Object objects, but you can override this
980 method in a child class in order to create more specialized Ace::Object
981 classes. The method should return a string corresponding to the pack‐
982 age to bless the object into. It receives the current Ace::Object as
983 its first argument.
984 debug() method
986 $object->debug(1);
988 Change the debugging mode. A zero turns off debugging messages. Inte‐
990 ger values produce debug messages on standard error. Higher integers
991 produce progressively more verbose messages. This actually is just a
992 front end to Ace->debug(), so the debugging level is global.
993
995 Ace, Ace::Model, Ace::Object, Ace::Local,
996 Ace::Sequence,Ace::Sequence::Multi
997
999 Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
1000 Mieg <mieg@kaa.crbm.cnrs-mop.fr>
1001 Copyright (c) 1997-1998, Lincoln D. Stein
1003 This library is free software; you can redistribute it and/or modify it
1005 under the same terms as Perl itself. See DISCLAIMER.txt for dis‐
1006 claimers of warranty.
1007perl v5.8.8 2001-02-20 Ace::Object(3)